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."
          }
        ]
      }
    }

Multiple Table​

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

    {
      "Table1": {
        "Sheet1": {
          "header": { ... },
          "rows": [
            { ... }
          ]
        },
        "Sheet2": {
          "header": { ... },
          "rows": [
            { ... }
          ]
        }
      },
      "Table2": {
        "Sheet1": {
          "header": { ... },
          "rows": [
            { ... }
          ]
        },
        "Sheet2": {
          "header": { ... },
          "rows": [
            { ... }
          ]
        }
      }
    }

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.

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

You can also use text formatting tags inside the field input to style the displayed text. For example, to display a bold name followed by a colored title:

[bold]name[/bold]
[separator: - ][fontcolor:gray]title[/fontcolor]

This would produce: John Doe - Software Developer (in gray).

Read more about all available formatting options here.

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.
  • Vertical & Horizontal Padding: Add padding around the content in pixels.
  • Rotation: Rotate the content within its allocated space.
  • Rounding: Set the border rounding in pixels for the field container.
  • Character Limit: Set the maximum number of characters displayed for this field. When the text exceeds this limit, it will be truncated with an ellipsis (...). A value of 0 means no truncation.

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.

Grid Layout​

Configure the overall structure of the grid displaying the data:

  • Orientation: Choose between vertical (rows scroll down) or horizontal (columns scroll right) layout.
  • Rows: Visible when navigation is enabled, or in horizontal mode without navigation. Controls the number of rows displayed per page (with navigation) or the number of rows in each column (horizontal without navigation).
  • Columns: Visible when navigation is enabled, or in vertical mode without navigation. Controls the number of columns displayed per page (with navigation) or the number of columns in the grid (vertical without navigation).
  • Widget Padding: Set padding around the entire widget content.
  • Horizontal & Vertical Gap: Adjust the spacing between cards.

Card Settings​

Configure the appearance of individual cards:

  • Edit card layout: Opens the visual layout editor for card field positioning.
  • Card width: Set a maximum card width in pixels (horizontal mode only, 0 = fill available space).
  • Card height: Set a maximum card height in pixels (vertical mode only, 0 = fill available space).
  • Card Rounding: Adjust the border rounding of each card.
  • Background image: Select a static image to display as the background of every card.
  • Background fitting: Control how the background image fits within the card (None, Contain, Cover, Fill).
  • Background position: Set the alignment of the background image within the card.

Field Settings​

Configure borders and background for the field areas inside each card:

  • Field border color: Set the border color around each field.
  • Field border width: Set the border thickness around each field (0 = hidden).
  • Field background color: Set the background color for all fields.
  • Always show field background: When enabled, the field background color will be rendered even when there is no data for that card slot.

Behaviour​

Control interactive behavior and visual effects:

  • Interactive: Allow cards to be clickable and trigger sensor events.
  • Hover effects: Show hover effects when the cursor is over a card.
  • Allow animations: Enable page transition animations in the widget.
  • Scrollbar color: Customize the scrollbar color to match your design.

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, auto-scrolling and navigation within the widget:

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

  • Selected page accent color: Select the accent color used for the selected page number styling.

  • Show prev/next buttons: If enabled, previous/next navigation buttons will be displayed within the widget.

  • Show page indicators: When activated, page number indicators will be displayed in the navigation bar.

  • Automatic pagination: When enabled, you can set the pagination time in seconds. The widget will automatically cycle through pages at this interval.

  • Auto Scroll: Available when navigation is disabled. Enables continuous automatic scrolling through all entries.

    • Auto Scroll speed: Controls the scroll speed.
    • Scroll-back speed: Duration in milliseconds for scrolling back to the top.
    • Pause at the end: Seconds to wait at the bottom before scrolling back to top.
    • Pause on hover: Stop auto scrolling when the widget is hovered or interacted with.

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.

Custom No-Results Message​

When the "Empty search message" setting is set to "Custom message", this group becomes visible. It allows you to define a custom message and style it with font family, size, style, color, letter spacing and text shadow settings.

Last updated on