Skip to main content

Configuring the Widget

Data Source​

To properly display information in the widget, you need to connect a data source.
To use the data in the widget, link the selected data source to the Data property via the widget's data source picker.

Datasource types​

Object​

  • An object containing nested objects:
    This format allows for a structured dataset where each item is stored as a key-value pair inside an object.
    When this selected, the original object key will be added to the serialized object as a new key called: original-object-key

    {
      "test": {
        "id": "test",
        "name": "John Doe"
      }
    }

Array​

  • An array of objects:
    This format is commonly used when handling lists of items.

    [
      {
        "id": "test",
        "name": "John Doe"
      }
    ]

Table​

  • An object containing table structured data: With this format, you can easily switch between worksheet using the built-in external commands. When this type is selected, then you can set the default worksheet name in a text field under the type selector.

    {
      "Sheet1": {
        "header": {
          "id": "string",
          "name": "string",
          "description": "string"
        },
        "rows": [
          {
            "id": "1",
            "name": "Péter",
            "description": "Lorem ipsum."
          }
        ]
      },
      "Sheet2": {
        "header": {
          "id": "string",
          "name": "string",
          "description": "string"
        },
        "rows": [
          {
            "id": "1",
            "name": "Róbert",
            "description": "Lorem ipsum."
          }
        ]
      }
    }

Skip data where​

In the widget, there is an option where you can skip those entries where a value or every value is missing/undefined.
If you select the Any value is undefined, then those entries from the datasource will be skipped where any field is empty or null or undefined.
If you select the All values are undefined, then those entries from the datasource will be skipped where every field is empty or null or undefined. If you select the Do not skip any rows, then nothing will be filtered out from the datasource.

Font Settings​

This section allows you to define global text styles that will be applied to all fields by default.
These settings include:

  • Font Family: Choose a typeface for the displayed text.
  • Font Size: Set the base font size, which will be used as a reference for other text adjustments.

These settings provide a consistent typography style across the widget.

Input Field Settings​

Here, you can specify which object properties should be displayed in different fields of the widget.
The available fields are First, Second, Third, and Fourth.

  • Each property key should be entered on a separate line.
  • If multiple properties should be combined into a single field, list them on different lines within the same field input.

For example, if you have an object with properties firstName and lastName, and you want them displayed together in the First field, enter:

firstName
lastName

This configuration ensures that multiple values can be combined inside a single field.

If one of your property is containing currency without formatting, and you want to format it, you can easily define the formatting here for the property key using selectors.

For example, let's say you have a property called itemPrice inside your datasource objects.
It is containing numbers like: 1000 or 23000, and you want to format it into: $ 1,000 and $ 2,3000, then in the field settings set the property itemPrice like:

[price:$:prefix:,]itemPrice

As you can see, the price selector is in used, where the currency symbol is $ and used as a prefix with the , separator.

Unique Field Settings​

Each of the four fields (First, Second, Third, Fourth) has individual styling options that override the global font settings.
These include:

  • Font Size Multiplier: Adjusts the font size relative to the global font size.
  • Font Style: Choose from normal, italic, bold, or other styles.
  • Font color: Define a text color that will be applied to the specified field.
  • Background color: Define a background color that will be applied to the specified field as a new background.
  • Letter Spacing: Customize spacing between characters.
  • Text Shadow: Apply a shadow effect to the text.
  • Vertical & Horizontal Alignment: Position text within its allocated space.
  • Rotation: Rotate the content within its allocated space.

This allows for more refined styling adjustments on a per-field basis.

Sort Settings​

In this group, you can set the default sort behavior used across the widget.
With external commands, you can update these settings during runtime.

  • Sort By: Set which field is used for the sorting algorithm.
  • Sort order: Set the default order used by the sorting algorithm.

Search Settings​

Search settings can be separated into three parts: Simple Search Settings, Complex Search Settings and Shared Settings.

By default, you can see the Simple Search Settings, because the search type is set to simple initially.

Simple Search Settings​

When the search type is set to simple, you can select which fields is used as searchable fields during runtime.
If it is set to All, then the search algorithm will search between every field. (First, Second, Third, Fourth)

You can update these fields using the setSearchProperties external command.
Read more about the command here.

Complex Search Settings​

When the search type is set to complex, you can provide datasource property keys which will be used as searchable properties during runtime.
Each line represents one key in the datasource object.

If it is empty, then the search will doesn't to anything when you want to use it, because there will be no property to search from.

Shared Settings​

Regardless of search type, whether it is simple or complex, there are some settings which will be applied anyway.

  • Search behavior:
    Defines how to search in a property or in the fields.
    Whether it is partially matches, or just matches with the start or the ending of the value, or exactly matches with the search value.

  • Case-sensitive search:
    Whether to search according to letter casing. If it is enabled, then everything will be parsed to lower case during search.

  • Skip Without Images:
    Automatically filter out any entry that lacks an image field.
    (A field is an image field if it is set in Image Settings)

  • Remove Specific Words or Characters:
    Define a list of words, letters, or text patterns to be stripped from all entries before display.

This section allows you to control data presentation and enhance readability by filtering out irrelevant details.

Table Settings​

Configure the overall structure and appearance of the table displaying the data:

  • Row & Column Count: Define how many rows and columns the table should contain.
  • Character Limits Per Field: Set a maximum character length for each field. If a field exceeds this limit, the text will be split into multiple lines.
  • Table Layout: Choose from different predefined layouts for how fields are displayed.
  • Cell Height & Spacing: Adjust the height of each cell and the spacing between horizontal and vertical entries.
  • Cell Rounding: Adjust the rounding of each cell.

These settings help ensure that the table is well-organized and visually appealing.

Image Settings​

If any field contains image URLs, you can configure how they are displayed:

  • Assign Image Fields: Select which fields contain image URLs and should be treated as images.
  • Multiple Image Fields: If your data contains multiple image fields, you can assign more than one.
  • Set Image Dimensions: Define the width and height of images in pixels.
  • Image Fitting & Rounding: Adjust how images are scaled to fit within their container and whether they have rounded corners.

Folder Lookup​

This feature is particularly useful when your data contains image filenames (like photo1.jpg) that need to be resolved to full paths or URLs from a specific folder or directory structure.
If a filename isn't found in the folder mapping, the widget will fall back to using the original field value as the image source.

  • Enable folder lookup: Toggle this setting to activate filename-to-URL mapping functionality.
  • Folder picker: Select the folder which will searched for filenames during lookup.

This section allows you to control pagination and navigation within the widget using three toggle options:

  • Enable Navigation:
    When enabled, entries will be split into multiple pages.
    When disabled, all entries will be displayed on a single page.

  • Selected page accent color: With this color picker, you can select the accent color which will be used for the selected page number styling.

  • Enable Navbar Buttons:
    If enabled, navigation buttons (such as previous/next) will be displayed within the widget.

  • Enable Page Info Buttons:
    When activated, additional page information (such as current page number) will be displayed.

  • Automatic pagination:
    When this is enabled, you can set the automatic pagination time in seconds. The widget will switch pages at the preset time according to this. It will go through the available pages inside the widget.

These settings allow you to manage how users navigate through large datasets in the widget.

Info

If you want a custom solution for the navigation and page info buttons, you can enable Navigation while disabling the other two options. This allows you to connect an external Form widget to the Directory app. The Form widget can communicate with the Directory app through sensor events and its own value options, providing more flexibility in handling navigation.

Developer Settings​

For additional customization and styling:

  • Table Border Width & Cell Border Color: Modify the thickness and color of table borders.
  • Cell Background Color: Customize the cell background color. (This will override the field background color setting)
  • Scrollbar Color: Customize the scrollbar to match your design.
  • Interactive: Whether the widget send out sensor event from itself.
  • Hover effects: Whether the cards need to have hover effects.

interactive, background, hover effect

Last updated on