Widgets
Widgets are navigational menu blocks shown on the Home Hub or in a jig (screen), and are used to display information and provide interactivity. Widget sizes and the content to display on the widget are configurable, such as icons, locations, images, charts, and more.
There are two types of widgets:
- components.widgets that display alongside other components within a . These widgets are configured inside the YAML.
A widget can be configured with the following sizes: - 1x1 - 2x2 - 2x4 - 4x2 - 4x4 Consider the layout of the widgets on the mobile app screen. Specific sizes cover the entire width of the screen, for example, 4x4. The image on the right shows the layout of widgets on a mobile app screen.
Depending on where the widget will be displayed, depends on where you configure the YAML for the widget, this is either in the index.jigx file or in the actual file.
For widgets to show on the they must be added to the index.jigx file under the widgets: property. The core properties include: -size: - This can 1x1, 2x2, 4x2, 4x4 or 2x4. -jigId: - Reference the that will open when the widget is tapped.
Optional properties include: - onPress - configure the widget to perform an action like open a url when pressed. - inputs - passes data into the when the widget is pressed.
By default when tapping on a widget you are directed to the corresponding . You can change the behavior of the widget by adding an onPress event to the widget configuration. The onPress is configured with an action, which is triggered when pressing on the widget. Use IntelliSense (ctrl+space) to see the available list of actions.
There are various UI elements available to make your inviting and engaging to end users. Content or information can be shown on the surface of a widget. Here is a list of available content/information widgets:
Widget content | Description |
|---|---|
icons | Choose an icon from thousands of available icons. |
Configure a button with an action that executes. | |
avatar | Display an avatar on the widget. |
chart | Configure a bar, line or pie chart to display on the widget. |
image | Configure an image to display on the widget, consider the size: of the widget to ensure the image displays as expected , 1x1 is not suitable for most images. |
list | Display a list of data in the widget with additional left and right elements if required. |
location | Show a location in a map on the widget with markers. |
status | Configure a visual representation of a status, such as goal status, or sales quartely status. |
value | Show values and amounts on the widget, such as Sales target or number of orders to date. |
To change the widget content either specify the icon: or widget: property at the top of the under the jig.type: property.
You still need to add the widget size: and jigId to the index.jigx file after changing the content of the widget in the file.
By default widgets are shown on the with an icon. If no icon is specificed assigns a default icon to the widget. To configure an icon, add the icon property in the itself. Start typing the first two letters of an icon to see a list of thousands of icons you can choose from.
In the example below the location icon is specified to replace the default icon.
- In open the whose widget you want to configure.
- Under the jig:type property use IntelliSense (ctrl+space) and select widgets:.
- Specify the size: of the widget from the available list.
- Next choose the type: of content to display on the widget, use IntelliSense (ctrl+space) to invoke the list of available types.
- Depending on the type you selected additional properties are required, see Widgets examples on how to configure each type accordingly.
- Add the widget (size and jigId) to the the index.jigx file.
In the example below the widget content is configured to show a location on the widget surface.
Widgets can be used as Components in a by using component.widget as the type: . This component is an extension of the functionality of widgets on your . It makes the same widgets available inside a , giving them greater visual appeal and enhanced capabilities.
- This component is exclusive to the jig.default and the components.widget displays alongside other components within the .
- Add multiple widgets in a using multiple size and jigId.
- Widget content can be shown on the widget surface and is configured in the individual s. (Same as for ).
- The when and inputs properties are available to dertermine when the widget must be visible and for passing data into the associated with the widget.
The widgets display order on a screen is determined by the order of the size and JigId in the YAML. You can change the order of the widgets by simply changing the order in the YAML of the jigIds. It is important to take into consideration the configured size of each widget when ordering widgets. Changing the order of the widgets can give your app a completely different look. Placing a 4x2 followed by 4x4 will result in white space next to the 4x2.
Intial widget order in index.jigx
Reordered and resized widgets in index.jigx
Widget labels are shown under the widget, and are read from the configured title: property of the .
- To display a widget with no label use title: ' ' in the .
Enhance your widget with a customizable badge for instance showing the number of events this week or the number of new orders. Add the badge property to the YAML with an expression.
Inputs allow you to pass data to the associated with the widget. For example, when a customer taps on My Orders widget the input is configured to pass that specific customer's Id and Name to the ensuring only the orders for that customer are shown. For more information on inputs see Passing data using inputs.
You have the ability to control which widgets are visible and well as when the widget must be visible.
- Control which widgets are visible to certain user groups by granting permissions on each widget in a solution in Jigx Management > Widgets. By default everyone with access to the solution has the widgets visible on the .
- Use the when: property configured by an expression or a boolean statement to determine when a widget must be visible. For example, show the order widget when there are orders awaiting approval.
See Widget Templates for steps on how to add widgets to s from a preconfigured set of templates.
- The content of the widget will determine the size to select. For example, showing an image or location on a 1x1 widget will not display well rather uses a 4x4 or 4x2.
- Best practice is to arrange widgets that fill the screen with no additional white space. Plan and design the widget layout and size of each widget in a design app or simply draw it on paper. For more information see Planning your app.
- A 1x1 widget can only dispay with an icon.
See Widgets for full code samples.
