html

Overview

The html UI component is mostly useful for two purposes:

  • Embedding imagery, branding, content, etc. into an app.

  • Extending the functionality offered "natively" by JourneyApps. For example, you could embed an HTML page that offers some level of interactiveness to create user interface elements or experiences that are not possible to implement natively in JourneyApps.

For more information about interactive html components see the Advanced Topics section:

If you simply need to display a single static image, use the display-image component instead of the html component.

Types of HTML Sources

The html component can display HTML content from two types of sources:

1. A local HTML file that is embedded inside your app. HTML files can be uploaded to your app using the Assets workspace in OXIDE. Specify a local path to the HTML file in the src attribute.

Example:

<html src="html/terms-and-conditions.html" />

2. A remote HTML page — specify an https:// URL in the src attribute.

Example:

<html src="https://en.m.wikipedia.org/wiki/Hippocrates_of_Chios"/>

Notes on remote HTML sources:

  • Remote URLs must be accessed with https on iOS.

  • Since JourneyApps Runtime version 4.86.1, cross origin (remote) HTML sources can access the device’s microphone and camera.

In TypeScript apps, App packages can also act as a source for a html component. Please see the documentation for further information.

Standard Attributes

src

Optional

Type: string

Default: unset

Path to the HTML source file. The value provided can be a format string if you need to dynamically specify the path or URL of the HTML file.

If you are using a remote URL, this can be used to send an argument/parameter to the remote page, e.g. an ID of an object in your app, which could look something like: src="http://example.com/some_page/{form.id}"

Advanced Attributes

height

Version compatibility

height was introduced in version 4.41.0 of the JourneyApps Container.

Optional

Type: number

Default: 50px

Specify the height (in pixel) of the html component.

show-fullscreen-button

Version compatibility

show-fullscreen-button was introduced in version 4.41.0 of the JourneyApps Container.

Optional

Type: boolean

Default: false

Shows a fullscreen button that allows the user to view the html component in fullscreen mode.

show-if and hide-if

Component Methods

The following component methods are available when assigning an id to the component and calling component.html({id:'my_id'}) from JS/TS:

on()

on(command: string, (param1?: any, ..., paramN?: any) => any)

Listen for messages sent from the html component to the app or from the app to the html component using either the post() or postNonBlocking() methods. The method listens for messages on the specified command.

Behavior since runtime version 4.86.4

As of runtime version 4.86.4, registering a callback for a command using the .on() method will clear any callback already registered for that command on the specific component and view.

In prior runtime versions, subsequent callbacks registered for a command on a specific component and view were ignored.

See more details in this section about communicating with the html component.

post()

post(command: string, param1?: any, ..., paramN?: any) : Promise<any>

Send a message from the html component to the app or from the app to the html component. The application will show a blocking spinner when posts are executed. The message is received on the other side by listening for the specified command using the on() method.

See more details in this section about communicating with the html component.

Known limitation

It is not possible to post messages from your view's init() function. If your html component needs data from the view on view initialization, you should:

  1. Send a message from the html component to the app when your html component's load event fires.

  2. Register a on() callback in your view's init() function which responds to the message in step 1 with the necessary information.

Basic example:

// In your view's JS
var value = component.html({id: 'my_id'}).post('get-value');
dialog("Value is " + value);
// In your <html/> component's JS
let client = new JourneyIFrameClient();
let value = 17;

client.on('get-value', function() {
    // Value returned here will be sent to the JourneyApps Container
    return value;
});

Example with parameters:

component.html({id: 'my_id'}).post('get-value', 1, 2, 3);

will pass three parameters to 'get-value': 1, 2 and 3.

// In your <html/> component's JS
let client = new JourneyIFrameClient();

client.on('get-value', function(param1, param2, param3) {
  // 1, 2 and 3 will be in param1, param2 and param3
});

postNonBlocking()

postNonBlocking(command: string, param1?: any, ..., paramN?: any) : Promise<any>

Send a message from the html component to the app or from the app to the html component, without showing a blocking spinner. The message is received on the other side by listening for the specified command: string using the on() method.

See more details in this section about communicating with the html component.

deregister()

deregister(command: string)

Clear a specific or all on() callbacks for a html component on a view.

Example: Clear all callbacks for the targeted html component on the current view:

component.html({id: 'my_id'}).deregister();

Example: Clear all callbacks for the mounted command for the targeted html component on the current view:

component.html({id: 'my_id'}).deregister('mounted');

See more details in this section about communicating with the html component.

Last updated