Configure a Static Entity

This tutorial demonstrates how to configure both manually maintained and dynamically loaded static entities.

Before you begin

Before starting this tutorial, you should:

• Understand the basics of static entities, and
• Be familiar with the Static Entity Editor.

Create the static entity

1. Open the Data Model section in the Design editor.
2. Create a new static entity by entering the static entity ID in the dialog and click OK.

When the static entity editor opens, update the following settings:

Configure a manually maintained static entity

To configure a manually maintained static entity:

1. Configure general settings

Use the following general settings:

Property	Value
Source	Static
Display column	label
Use other values	Leave disabled unless required

📌

Attention

The display column determines which property value users see in dropdowns and other selection controls. If the display value should come from a custom property, create the property first and then update the display column setting to use it.

The “$isOther” option

Static entities can optionally allow users to enter custom values that are not part of the predefined option list.

To add this feature, enable Use “other” values.

2. Configure properties

Static entities commonly define the following core properties:

Property	Purpose	Example
identifier	PascalCase internal identifier	Usd
id	Unique internal value	usd
label	Display value shown to users	USD

Properties can be edited or extended to support the required reference data structure.

Existing properties such as label can be modified by expanding the property using the down caret.

The property editor allows you to configure:

• the property type, and
• whether the property is an expression.

When the Expression checkbox is enabled, the property value is calculated dynamically instead of being entered manually.

🚨

Danger

Available variables and supported expressions depend on the expression context. Do not assume that other static entity properties are automatically available inside the expression.

Configure properties

Use the + Add property button to add additional properties.

1. Click on the + Add property button.

2. Enter the property name in the New property dialog.

3. Click OK to create the property.

4. Expand the property using the down caret to configure:

   • the property type, and
   • whether the property is an expression.

   Some property type selections may affect whether the Expression option remains available.

5. Set the property type to any one of the primitive types such as string, number, or boolean, or reference another static entity.

6. When the property type is set to [Static Entity], the editor displays an additional REFERENCED ENTITY dropdown containing the static entities available in the application.

7. Choose the relevant entity from the REFERENCED ENTITY dropdown.

8. If the property should evaluate at runtime, enable the Expression checkbox.

📌

Attention

The Expression checkbox is no longer visible after choosing a static entity as a property type.

9. Save your changes before continuing.

3. Add static entries

Use the Static Entries section to add and maintain static entity entries manually.

To add a new entry:

1. Click + Add entry.

2. Enter values for each configured property.

3. For example, set:

identifier	id	label
Usd	usd	USD
Eur	eur	EUR

💡

Insight

Each row represents a single static entity entry and stores values for the properties defined in the Properties section.

If a custom property has been created, values must also be provided for this property.

For example:

identifier	id	label	Additional Names
Usd	usd	USD	United States Dollar, US Dollar
Eur	eur	EUR	European Currency, Euro

Configure an “Other” entry

To configure an Other option:

1. Add or select the entry that should behave as the Other option.
2. Check $isOther for that entry.

3. Save and close the editor.

At runtime, when the user selects the entry marked with $isOther, Lowgile automatically displays an additional input field next to the dropdown.

📌

Attention

The $isOther property is a behavior flag used to identify the Other entry and should not be used as the display column.

Configure a dynamic static entity

Dynamic static entities load their entries dynamically from a configured source, such as a file, API, database query, or server-side script.

To configure a dynamic static entry:

1. Configure the source type

Update the following general settings:

Property	Value
Source	Select one of the supported dynamic source types
Display column	label

The following dynamic source types are supported:

• Dynamic (running on server and client): Loads entries in both client and server execution contexts.
• Dynamic (needs to run on server): Loads entries only in a server-side execution context.

2. Configure caching

Dynamic static entities optionally support both server-side and client-side caching.

The configured caching values determine how long dynamic entries are reused before Lowgile reloads the source data the next time the static entity is accessed.

Leave the default caching values unchanged for now.

3. Configure the dynamic entries script

Use the Dynamic Entries Script section to load the entries stored in the static entity.

📌

Attention

The data must match the properties configured in the static entity otherwise the upload operation will fail.

Dynaic entries script example

The following example demonstrates the basic structure of a dynamic entries script.

The script starts with the default optionsList function:

async function optionsList(): Promise<This.Entity.Entry[]> {

}

Add logic that loads data from the configured source.

For example:

const source = await loadSourceData()

Then return the loaded data as static entity entries:c

return source.parseToObjects()

For example, an XLS-based static entity may use code similar to:

async function optionsList(): Promise<This.Materials.Entry[]> {
  const xls = await Sys.Xls.SimpleXls.fromFile('Materials.xlsx', 'xlsx')
  return xls.parseToObjects({ sheetNameOrNumber: 'Materials' })
}

Related documentation

• Static Entity Editor
• Dropdown Component
• Static Entities