A custom widget is a user-created widget that can be programmed to do basically anything. Usage in a dashboard is identical to that of any of the built-in widgets. However, unlike those widgets, which are not editable by users, a custom widget can be given all sorts of settings, a completely custom appearance and style, and as many readouts, buttons, and inputs as desired.

Custom widgets are only editable by the organization that creates them; an OEM's custom widgets are visible/usable only for its users and the dealers and clients related to it. This ensures that OEMs maintain complete control of their custom widgets and don't have to worry about the possibility of an outside user going around and messing things up in their widgets' code.

1. Open the navigation menu.
2. Select the Custom Widgets item.
3. Double-click the desired widget.
   • If no widgets exist, use the button to create one.

• Click the button to switch between the two modes for adding widget settings. The default mode uses the UI; toggling the mode allows for editing the settings JSON directly.
• Click the button to preview what the widget's settings will look like when being used in a dashboard.
  • Changing the values will not change the settings' default values. These are actually the settings for the widget preview at the right of the page.
• Click the button to open the sidebar and access the widget's platform-level settings.
  • These are not the settings that appear when the widget is added to a dashboard.
  • Organization
    • Specify which organization this widget was created by.
    • The organization must be an OEM or higher; dealers and clients cannot edit custom widgets. See the organization roles for more info.
  • Name
    • Identifies the widget around the Spoke Zone platform.

There are three main pieces of a custom widget: the source code, the use-by-use settings, and the UI styles.

All newly created custom widgets have default code/settings/styles for a very basic button that highlights the key elements of developing a widget.

The preview at the right of the page shows what the widget would look like on a real dashboard with the current code and styles. It updates each time the widget is saved. If there is a syntax error somewhere, the widget will not appear.

Click the button in the section selector to access the source code.

Widgets are built using JavaScript (JS), so JS variables, functions, and other pieces of code can be defined the same way as when writing regular JS code.

There are a few key parts/functions:

• JQuery elements are used as the building blocks of the UI. They are created as HTML and (if needed) inline CSS.

  // Examples of how to create JQuery UI elements. // This creates a basic container. var mainCol = $(`<div class="main-column"></div>`); // This creates a white "save" icon. // Note the use of a variable in the middle using a JQuery element selector. const svgColor = "white"; const saveSvg = $(` <svg class="icon-btn-svg text-style" height="24px" width="24px" xmlns="http://www.w3.org/2000/svg"> <title>content-save-outline</title> <path fill="${svgColor}" d="M17 3H5C3.89 3 3 3.9 3 5V19C3 20.1 3.89 21 5 21H19C20.1 21 21 20.1 21 19V7L17 3M19 19H5V5H16.17L19 7.83V19M12 12C10.34 12 9 13.34 9 15S10.34 18 12 18 15 16.66 15 15 13.66 12 12 12M6 6H15V10H6V6Z" /> </svg> `);

• These elements are then put together in the required render function to create the finished UI. Use the $(element-name).append(other-element-name) syntax to combine elements.

  • At the top of the widget is the line const { container, publish } = data;. The container variable is the outermost UI variable that everything else must be put inside.
  // This would all be inside the render() function... // The render() function is called repeatedly while a dashboard is open. // The container must be cleared so that the UI can refresh. container.empty(); // Add a click handler to a button element defined elsewhere. $(buttonElement).click((e) => { console.log('Button clicked'); }); // Add a click handler defined elsewhere to another button. $(buttonElement2).click(this.onButton2Clicked.bind(this)); // Add a CSS class. $(buttonElement).addClass('text-justify'); // Put the button inside the container. $(container).append(buttonElement).append(buttonElement2);

• Update the widget when its settings change by defining the onSettingsChanged function.

  // The function signature has a "newSettings" variable, which is a JSON object. // It contains all the new settings as values with the setting names as keys. this.onSettingsChanged = function (newSettings) { // "test_setting_1" is a checkbox. if (newSettings.test_setting_1) console.log('Test setting is true now'); }

Click the button in the section selector to access the widget's settings.

• Click the button in the top left to add a new setting.
• Click the button at the top right of a setting to delete it.
• Use the and buttons to reorder the settings.
  • The order they are put in is the order in which they will appear when being edited in a dashboard, as can be seen from the settings preview.

All settings have three basic fields:

• Name: the name that will appear to users when working with the widget on a dashboard.
• ID: the identifier that can be used to get info about the setting in the widget's source code.
  • This ID must be unique to this widget. Spoke Zone will not allow duplicate IDs.
• Default Value: the initial value of the setting when it is first created. Different widget types have different types of default values.

Widgets can have 7 different types of settings:

• Calculated settings are used to read a value being sent up from a device via MQTT.
• Checkbox settings are used to specify a boolean value.
  • These are commonly used to dynamically enable/disable a specific part of the widget.
• Datasource settings allow a widget to get access to one of the datasources added to a dashboard.
  • The widget can then read MQTT payloads sent by the datasource and send MQTT commands.
• Number settings allow a user to input a numeric value.
  • A default value can be specified, but there is no way to specify a minimum or maximum. Input validation must be done in the widget source code.
• Repeated settings contain a group of subsettings that can be repeated as many times as the user wants.
  • Subsettings are specified the same way as regular settings. Click the button next to the Child Settings label to add a new one.
  • Repeated settings are very powerful because of their flexibility. A great example can be found in the Line Graph Widget.
• Select settings allow the user to pick a preset option from a dropdown list.
  • Each option has a name, which is what the user sees, and a value, which is what the widget uses.
  • To add new options, first fill in the name and value of the current last option, then click the button to the right of the option.
  • Click the button to remove an option.
• Text settings are for inputting a simple text string.

Click the button in the section selector to access the widget's styles.

This is where CSS styling for the widget can be specified. Define CSS classes and then use them anywhere in the widget source code when creating JQuery elements.