You can use a Custom widget field to include your own HTML content inside a form. Your widget can interact with the form, display a custom interface, run JavaScript code and interact with third-party web services (if connectivity is available).
Note: Custom widgets are available on the Premium plan (or above).
Step 1:
Using your preferred text / code editor, create a .html file that will store your custom widget. Depending on what you want the widget to do, you will write HTML and JavaScript code accordingly. In your "<head>" tag, include a script reference to the MobenziWidgetAPI Javascript library - this will provide functions that allow your to interact with the form.
For example, here's the code for a widget that displays the text "Hello World":
<html>
<head>
<script src="https://cdn-gateway.mobenzi.com/res/lib/MobenziWidgetAPI.js"></script>
</head>
<body>
<h1>Hello World</h1>
<script>
// You can fetch any parameters passed to the widget as follows
var myparam = MobenziWidgetAPI.GetParameter('parameter_name');
// If you need to, you can return a string value to the form - this will be stored as the widget's field value.
MobenziWidgetAPI.SetReturnValue('custom_widget_data');
</script>
</body>
</html>Step 2:
Add a custom widget field to your form like you would any other field. Choose "Custom Widget" (1) from the Advanced field category in the "Add Field / Group" popup.
By default, widgets do not store a value and are marked as optional.
Step 3:
You can choose to host your widget on your own web server or upload it to the project resource library (2) - meaning it will work offline (provided you also upload any other resources that the widget uses).
If you choose to embed the widget, upload the .html file you created in step 1 to your project library then select it as the resource file (3).
If you choose to host the widget code externally on your own web server, enter the URL that points to the widget - this can be a static HTML file or any other web service (e.g. PHP, NodeJS) that returns HTML.
Passing values to the widget
Often, widgets are used to perform custom logic or data processing that cannot be achieved using the built-in functions available in the form. If you want to pass values from the form to your widget, you can do so by specifying them in the Parameters tab (4):
The values will be available to the widget and you can use some simple JavaScript to retrieve them:
// This example assumes you pass two parameters to the widget: "mode" and "limit".
var mode = MobenziWidgetAPI.GetParameter('mode');
var limit = MobenziWidgetAPI.GetParameter('limit');Returning a value to the form
Widgets can store a value just like other types of fields. If you want your widget to return a value to the form, you'll need to add some JavaScript that specifies the value that should be stored.
The value returned is stored as a string (text) and can be used to determine skip logic and can have validation rules applied.
// Add this JavaScript to your widget and call this function when you wish to set the return value of the widget.
// Note: You must include a script reference to include the Mobenzi Widget API in your widget's <head> tag.
MobenziWidgetAPI.SetReturnValue("yourValue");Advanced widget display settings
From the "Advanced" field tab, you can specify the height of the widget (in pixels) and the width of the widget (as a percentage of the form's width). You can also specify whether or not a scrollbar should appear if the width/height of the widget's content exceeds the width/height specified.
It is also possible to dynamically set the widget's height - for example if you want the widget to adjust to the height of the content (which might vary). This is done by including a line of Javascript in the widget that should be called when the content of the widget changes.
// Add this JavaScript to your widget and call this function whenever the content of your widget changes. // Passing a value will set the height of the widget in pixels. // Calling the function without a value will set the height of the widget to the current full height of the widget's content (i.e. no scrolling). MobenziWidgetAPI.SetHeight();