# 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: {% content-ref url="html/html-advanced-topics" %} [html-advanced-topics](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/html/html-advanced-topics) {% endcontent-ref %} {% hint style="info" %} If you simply need to display a single static image, use the [`display-image`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/display-image) component instead of the `html` component. {% endhint %} ![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-d791bd929904719e190bb1353c9c9bfc41949377%2Fhtml-component-example.png?alt=media) ### 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: ```xml ``` **2. A remote HTML page** — specify an `https://` URL in the `src` attribute. Example: ```xml ``` {% hint style="info" %} **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. {% endhint %} {% hint style="info" %} In [TypeScript](https://docs.journeyapps.com/reference/build/syntax/typescript-apps) apps, App packages can also act as a source for a `html` component. Please see the [documentation](https://docs.journeyapps.com/reference/build/extending-your-app-with-custom-code/app-packages/app-packages-overview) for further information. {% endhint %} ## Standard Attributes ### `src` **Optional** **Type**: `string` **Default**: unset Path to the HTML [source file](#types-of-html-sources). The value provided can be a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) 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` {% hint style="info" %} **Version compatibility** `height` was introduced in version **4.41.0** of the JourneyApps Container. {% endhint %} **Optional** **Type**: number **Default**: 50px Specify the height (in pixel) of the `html` component. ### `show-fullscreen-button` {% hint style="info" %} **Version compatibility** `show-fullscreen-button` was introduced in version **4.41.0** of the JourneyApps Container. {% endhint %} **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` {% content-ref url="../xml-fields/show-if" %} [show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if) {% endcontent-ref %} {% content-ref url="../xml-fields/hide-if" %} [hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if) {% endcontent-ref %} ## Component Methods The following component methods are available when assigning an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/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`. {% hint style="info" %} **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. {% endhint %} See more details in [this section](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/html-advanced-topics#communicating-with-the-html-component) about communicating with the `html` component. ### `post()` `post(command: string, param1?: any, ..., paramN?: any) : Promise` 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](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/html-advanced-topics#communicating-with-the-html-component) about communicating with the `html` component. {% hint style="warning" %} **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. {% endhint %} Basic example: ```javascript // In your view's JS var value = component.html({id: 'my_id'}).post('get-value'); dialog("Value is " + value); ``` ```javascript // In your 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: ```javascript component.html({id: 'my_id'}).post('get-value', 1, 2, 3); ``` will pass three parameters to `'get-value'`: `1`, `2` and `3`. ```javascript // In your 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` 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](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/html-advanced-topics#communicating-with-the-html-component) 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: ```javascript component.html({id: 'my_id'}).deregister(); ``` **Example**: Clear all callbacks for the `mounted` command for the targeted `html` component on the current view: ```javascript component.html({id: 'my_id'}).deregister('mounted'); ``` See more details in [this section](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/html-advanced-topics#communicating-with-the-html-component) about communicating with the `html` component. ###