Build a widget
This topic provides examples to help you get started with widgets.
A widget is a special type of page with an independent scope. You can use a widget renderer to add a widget to a page. This creates a self-contained logic loop and improves the efficiency of application development and maintenance.
1. Create a widget
You can create a widget in the Page & Layout & Widget panel. After the widget is created, the designer enters widget edit mode by default. From the widget list, you can rename, clone, or delete widgets.
2. Widget components and code
In widget edit mode, you can add components and code to the widget. The available capabilities are the same as those for a page.
Scope: Elements within a widget can access each other and can directly access global scope elements. However, they cannot directly access other widgets or elements on the parent page.
Container layout: Within a widget, all containers use a flexible layout by default. Grid layouts are not supported in widgets.
3. Input parameters and simulated parameters
Input parameters are used to pass external data to a widget. These parameters can be used by modules within the widget, such as components, code, and events (mounted and willUnmount).
Simulated input parameters: To simplify widget development and adapt to different input parameter formats, you can set simulated input parameters based on the parameter type definitions. Simulated input parameters are used only in widget edit mode and are not the default values for the input parameters.
Input parameters within a widget are read-only and can be used directly. The following figure shows a Text component rendering an input parameter.
If you modify the definition of an input parameter, you must update all references to it within the widget.
Simulated input parameters are used only in widget edit mode and are not the default values for the input parameters.
4. Events
The following table lists the events emitted during the widget rendering lifecycle. You can use these events with callbacks to implement your widget's rendering logic.
Event name |
Description |
mounted |
Triggered when the widget finishes loading. Use this event to initialize data or set a state. |
willUnmount |
Triggered before the widget is unmounted. |
5. Event declarations
Event declarations define the format of messages that a widget sends externally. After you declare an event, the widget must be configured to trigger it. The widget renderer on the page then receives the event. For example:
1. In the widget, declare a "payment" event with the event ID "pay".
Define the parameter type for the "payment" event as "string". This represents the ID of the product to be paid for.
2. For the payment button, add a click event that triggers the "payment" event. Pass the id, which is received as an input parameter, as the event parameter.
In this example, you can also use a script to trigger the event: mobi.sendEvent('pay', id);
3. In the widget renderer, bind and render widget1, pass the parameter { "id": "666" }, and add a callback response for the "payment" event.
In the widget's event callback response, use eventParams to retrieve the event parameters.
6. Canvas preview width
In widget edit mode, you can adjust the canvas preview width to simulate the widget's actual rendered width. This helps you design the widget layout accurately.
