The Custom Widgets API is a JavaScript API that can be included in a custom widget field to interact with the form in which the widget is being used.


Including the API in your widget


To use the Custom Widgets API, in your "<head>" tag of your widget's HTML code, include a script reference to the MobenziWidgetAPI Javascript library - this will provide functions that allow your to interact with the form.


<script src="https://cdn-gateway.mobenzi.com/res/lib/MobenziWidgetAPI.js"></script>


Setting the return value of the widget


Widgets can store a value just like other types of fields. If you want your widget to return a value to the form, you can use the SetReturnValue() function.


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");


Accessing data passed to the widget


Often, values are passed to a widget from the main form. These can be retrieved from the widget using the GetParameter() function.


// This example assumes you pass two parameters to the widget: "mode" and "limit".

var mode = MobenziWidgetAPI.GetParameter('mode');
var limit = MobenziWidgetAPI.GetParameter('limit');


Programmatically setting the widget field height


In some cases, you might want to set the height of the custom widget dynamically to avoid displaying scrollbars and have the widget's height match the content that it contains. This can be achieved by calling the SetHeight() function.


// 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();