Formatting Rule¶

The formatting rule in Emakin adjusts a widget's appearance based on the value of a data model property. This feature enhances the user experience by making the form visually dynamic and context-sensitive.

The following widget properties can be updated using formatting rules:

Hidden: Hides the widget from the screen.
Disabled: Makes the widget read-only by disabling its editing features.
BackgroundColor: Changes the widget's background color.
Color: Updates the text color of the widget.
Bold: Makes the widget's text bold.
Italic: Makes the widget's text italic.

Property Propagation¶

Formatting properties apply to child widgets of a container widget through inheritance.

When a container widget is hidden, child widgets and their associated rules, including validation rules, are no longer executed.

Properties such as BackgroundColor, Color, Bold, and Italic are inherited by child widgets. This inheritance can be overridden by defining specific formatting rules for the child widgets.

Overriding Inherited Properties¶

Formatting rule properties use Inherit or an empty string as their default value:

• Inherit Value:

  • The widget inherits the property value from its parent container widget.
  • Example: If a Row Container is disabled, all its child widgets are automatically disabled.

• Explicit Override:

  • A child widget can override the inherited state with a specific formatting rule.
  • Example: A text box within a disabled row container can define a rule setting its Disabled property to False, making it editable.

By leveraging formatting rules and property inheritance, Emakin forms can be customized for responsive, user-friendly interfaces while minimizing repetitive configurations.

Rule Condition¶

Formatting rule conditions are defined using JavaScript functions that return a boolean value. These functions are triggered when changes occur in the data model, updating the widget accordingly.

Condition scripts support the async/await pattern for asynchronous operations. This allows validation logic to include external API calls or long-running tasks.

Available Scripting Variables¶

• $Xml Represents the XML data model element bound to the widget.
• $ActiveUser Contains current user identity details.
• $Disabled Indicates the form's disabled state.
• $Process The ID of the currently running process.
• $StaticUrl The URL for accessing static files.

Structure of $ActiveUser JSON Object:

1
2
3
4
5
6
7

{
    "name": "<user_display_name>",
    "type": "User",
    "domain": "<domain_id>",
    "id": "<user_id>",
    "email": "<user_email>"
}

Example¶

In the following example, a formatting rule is defined for a text box widget. The rule changes the text box's background color to red when the value of the status property in the data model is set to rejected.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<TextBox XPath="status">
    <Rules>
        <FormattingRule Hidden="Inherit" Disabled="Inherit" BackgroundColor="#f44336" Color="#fff" Bold="" Italic="">
            <Condition>
                <Content><![CDATA[return $Xml.Evaluate('rejected');]]></Content>
                <Definitions/>
            </Condition>
        </FormattingRule>
    </Rules>
</TextBox>