Widgets

Widgets are navigational menu blocks shown either on the Home Hub or in a jig (screen) and are used to display information and provide interactivity. Widget sizes and content, such as icons, locations, images, charts, and more, are configurable.

Configuration Sizes

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.

Widget layouts

How to configure widgets

Widget configuration

1. Add an icon to the top level of your jig.

2. The jigId, and size are configured in a jig.grid or grid-item component to display the widget.

jig-with-icon.jigx

title: Add new employee
type: jig.default
icon: person

jig-grid.jigx

2x2, 2x4, 4x2, and 4x4 widgets configured with content

1. Widgets are configured in the YAML in a jig file and a unique Widget Name is provided that is referred to as the widgetId.

2. The jigId, widgetId, and size are configured in a jig.grid or grid-item component to display the widget.

3. If inputs are required to pass data into the widget then configure them in the grid-item under the inputs property. Inputs are not mandatory and are dependant on the scenario.

jig-with-widget.jigx

widgets:
  # Provide a unique name for the widget. This becomes the widgetId.
  dev-avatar:
    # Configure the type of widget to display in the grid-item.
    type: widget.avatar
    options:
      text: LS
      # Configure the widget properties with inputs defined in the grid-item,
      # if data is to be passed into the widget.
      uri: [email protected]
      bottom:
        type: component.titles
        options:
          align: center
          title: [email protected]
          subtitle: React Web Developer

jig.grid.jigx

Change the widget behavior

By default when tapping on a widget you are directed to the corresponding jig. 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 to see the available list of actions.

jig.jigx

- type: component.grid-item
    options:
      size: "1x1"
      children:
        type: component.jig-widget
        options:
          jigId: company-site
          # Add an onpress to open a specific URL.
          onPress:
            type: action.open-url
            options:
              url: https://docs.jigx.com

Change the widget content

There are various UI elements available to make your widget 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.
actions (buttons)	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 quarterly status.
value	Show values and amounts on the widget, such as Sales target or number of orders to date.

1. To configure the widget content specify the widget: property at the bottom of the jig.

2. Provide a Widget name for the widget that is referenced as the widgetId.

3. Select the type of content to display in the widget.

You still need to add the widget size: and jigId to the grid-item component after changing the content of the widget in the jig file.

1.Configure an icon

By default widgets are shown on the grid-item with an icon. If no icon is specified Jigx assigns a default icon to the widget. To configure an icon, add the icon property in the jig 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.

Default icon

Location icon on widget

yoga-location.jigx

title: Location
type: jig.default
# add an icon in the jig that displays on the widget.
icon: location

datasources:
  address:
    type: datasource.static
    options:
      data:
        - street: 768 5th Ave
          city: New York
          country: US
children:
  - type: component.location
    options:
      viewPoint:
        centerPosition: middle
        address: |
          [email protected]  
          & ',' & @ctx.datasources.address.city
          & ',' & @ctx.datasources.address.country
        zoomLevel: 9

grid-item.jigx

2.Configure the widget content

1. In Jigx Builder open the jig whose widget you want to configure.

2. Use IntelliSense (ctrl+space) at the root level and select widgets:.

3. Specify the Widget Name.

4. Next choose the type: of content to display on the widget, such as widget.location use IntelliSense to invoke the list of available types.

5. Depending on the type you selected additional properties are required, see widget examples on how to configure each type accordingly.

6. Add the widget (size , jigId, widgetId, and inputs) to the grid-item.

In the example below the widget content is configured to show a location on the widget surface.

Widget with location content

yoga-studio.jigx

title: Location
type: jig.default

datasources:
  address:
    type: datasource.static
    options:
      data:
        - street: 768 5th Ave
          city: New York
          country: US
children:
  - type: component.location
    options:
      viewPoint:
        centerPosition: middle
        address: |
          [email protected]  
          & ',' & @ctx.datasources.address.city
          & ',' & @ctx.datasources.address.country
        zoomLevel: 9

#Add a location content type to display on the widget surface.
widgets:
  locationWidget:
    type: widget.location
    options:
      viewPoint:
        centerPosition: middle
        address: |
          [email protected]  
          & ',' & @ctx.datasources.address.city
          & ',' & @ctx.datasources.address.country
        zoomLevel: 9

home.jigx

How to move or rearrange widgets

The widgets display order on a screen is determined by the order of the grid-item in the YAML. You can change the order of the widgets by simply changing the order in the YAML. 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.

Initial widget order in grid

Initial widget order

home.jigx

title: Yoga
type: jig.grid

children:
  # First widget displayed
  - type: component.grid-item
    options:
      size: "4x2"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-image-widget
          widgetId: yoga-image
  # Second widget
  - type: component.grid-item
    options:
      size: "1x1"
      children:
        type: component.jig-widget
        options:
          jigId: my-bookings
  # Third widget
  - type: component.grid-item
    options:
      size: "1x1"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-location
  # Fourth widget
  - type: component.grid-item
    options:
      size: "1x1"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-info
  # Fifth widget
  - type: component.grid-item
    options:
      size: "1x1"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-meals

Reordered and resized widgets.

Reordered widget

home.jigx

title: Yoga
type: jig.grid

children:
  - type: component.grid-item
    options:
      size: "2x2"
      children:
        type: component.jig-widget
        options:
          jigId: my-bookings
  - type: component.grid-item
    options:
      size: "2x2"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-location
  - type: component.grid-item
    options:
      size: "4x2"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-image-widget
          widgetId: yoga-image

  - type: component.grid-item
    options:
      size: "2x2"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-info
  - type: component.grid-item
    options:
      size: "2x2"
      children:
        type: component.jig-widget
        options:
          jigId: yoga-meals

Widget labels and titles

Widget labels are shown under the widget, and are read from the configured title: property of the jig.

1. To display a widget with no label use title: ' ' in the jig.

2. To display a label on the widget surface use the widget titles.

Widget badging

Enhance your widget with a customizable badges for instance showing the number of events this week or the number of new orders. Add the badge property to the jig YAML with an expression.

Widget badge

calendar-jig

# jig file
title: Calendar
type: jig.calendar
icon: calendar-3
# badge counting the number of events in the calendar, the badge shows on the widget
badge: =$count(@ctx.datasources.calendar-data.id)

new-customer-jig

Inputs

Inputs allow you to pass data to the jig 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 jig ensuring only the orders for that customer are shown. For more information on inputs see Passing data using input

index.jigx

- type: component.grid-item
  options:
    size: "2x2"
    children:
      type: component.jig-widget
      options:
        jigId: my-orders
        widgetId: order-detail
        # Specify the inputs for the widget.
        inputs:
          customer-name: [email protected][5].name
          id: [email protected][5].id

Widget visibility & access

You have the ability to control which widgets are visible as well as when the widget must be visible.

1. 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 in the app.

2. 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.

grid.jigx

- type: component.grid-item
    # Determine when the widget will display
    when: [email protected] = 'easy'
    options:
      size: "4x4"
      children:
        type: component.jig-widget
        options:
          jigId: location

Considerations

• 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 will only display an icon.

Examples and code snippets

See Widgets for full code samples.