Conditional States

Scope of Conditions

Conditional states enhance Pages by allowing dynamic adaptation based on specified conditions, significantly improving interactivity and user-specific functionality.

tip

Once a condition is associated with a state, it becomes a Conditional state. As soon as the condition is True, the state is enabled. If the condition is False, the state is disabled.

Conditions within Qodly are classified into two types:

Local Conditions

Local Conditions are specific to the currently selected state and can be customized to meet unique logic requirements of that state.

Saved Conditions

Saved Conditions are reusable and can be applied across different states, stored within the Saved Conditions area for easy access and application.

info

For more details, please refer to the Saved Conditions area section.

Conditions Interface

Accessible via the Conditions button next to the States header, this interface is pivotal in visualizing and managing conditions that define the behavior of Page states. It includes major tools such as the States Area, Saved Conditions Area, Schema Editor, and JSON Editor, each designed to facilitate specific aspects of condition management.

States Area

The States section is organized with tabs for each available state, allowing straightforward navigation and modification of state conditions. The tab for the currently active state is highlighted to clearly indicate which state is being edited.

Saved Conditions Area

This area allows users to create, store, and manage conditions that can be reused across various states within the Page.

tip

The tab representing the condition currently being modified is distinctly highlighted, providing users with a clear visual indication of the active condition.

Adding a new saved condition involves clicking the button, which initializes it with a generic name.

Schema Area

The Schema Editor is introduced here as a central tool for visualizing and editing the logical connections between conditions. For detailed information on utilizing this tool, see the Schema Editor section.

JSON Area

The JSON Editor is an advanced tool for those who need to directly manipulate the condition's properties in JSON format. For more details on how to use this feature, refer to the JSON Editor section.

Conditions Schema Editor

At the core of the Conditions Interface is the Schema Editor, a dynamic visualization tool essential for mapping out and manipulating condition logic in a flowchart-like format. This interface allows for intuitive operations such as:

Default Options

If no conditions are pre-set for the selected state, the Schema Editor provides an Add condition button by default, facilitating quick starts in condition creation.

Saved Condition Integration

Users can integrate a Saved Condition into the current state's logic by clicking and dragging from the Saved Conditions Section directly into the schema.

tip

Ensure proper placement by dragging the Saved condition to the ellipsis icon , which represents the condition's specific level within the schema. Dropping it elsewhere might not integrate the condition correctly.

When multiple conditions are present, dropping it onto the connecting logical operator square will integrate it as well.

Logical Condition Combination

Link conditions with visual connectors representing logical operators. Use the & operator for combined fulfillment, or the | operator for partial fulfillment.

Comprehensive View Controls

Facilitate a switch between detailed and overview modes by using the global expand/collapse button , accessible via the designated button in the schema header .

Condition Configuration Card

Each condition card within the schema serves as an access point for configuring the specific properties of a condition. When a card is collapsed, it displays essential information at a glance, such as the condition's type and the qodlysource it is connected to.

info

For additional details, please refer to the Condition Types section.

Condition Actions

Every condition card is equipped with a set of actions, facilitating modifications like renaming or deleting the condition.

For additional details, please refer to the Conditions Actions section.

Condition Types

Each condition within the schema is represented by an interactive card, providing a user-friendly interface for configuring specific properties. These cards can be expanded or collapsed to display key details and settings.

Qodly Source

Name	Icon	Description	Available Operators
Qodly Source		Evaluates data from a specified qodlysource.	=, !=, >, >=, <, <=, in, not in, regex

Comparators vary depending on the qodlysource type:

String:

• EQUAL: hardcoded value or qodlysource
• DIFFERENT: hardcoded value or qodlysource
• CONTAINS: hardcoded value or qodlysource
• STARTSWITH: hardcoded value or qodlysource
• IN (value1, value2, ...): hardcoded values or qodlysources
• ISNULL
• REGEX: hardcoded value only

Number, Dates, Duration:

• GREATER THAN: hardcoded value or qodlysource
• GREATER THAN OR EQUAL: hardcoded value or qodlysource
• LOWER THAN: hardcoded value or qodlysource
• LOWER THAN OR EQUAL: hardcoded value or qodlysource
• BETWEEN (value1, value2): hardcoded values or qodlysources
• ISNULL

Boolean:

• ISTRUE
• ISFALSE
• ISNULL
• EQUALS (qodlysource): another boolean qodlysource

Example

Visual Representation

Json Code

{
  "type": "combination",
  "id": "auto_generated_unique_identifier_1",
  "op": "and",
  "conditions": [
    {
      "type": "qodlysource",
      "id": "auto_generated_unique_identifier_2",
      "name": "Age over 25",
      "path": "employee.age",
      "op": "gt",
      "value": 25
    },
    {
      "type": "qodlysource",
      "id": "auto_generated_unique_identifier_3",
      "name": "Lastname starts with D",
      "path": "employee.lastname",
      "op": "regex",
      "value": "^D"
    }
  ]
}

Current State Condition

Name	Icon	Description	Available Operators
Current State		Evaluates the state of the current element.	=, !=, regex

Example

Visual Representation

Json Code

{
  "type": "combination",
  "id": "auto_generated_unique_identifier_13",
  "op": "and",
  "conditions": [
    {
      "type": "currentState",
      "id": "auto_generated_unique_identifier_14",
      "name": "Current state is State_1",
      "op": "eq",
      "value": "State_1"
    },
    {
      "type": "currentState",
      "id": "auto_generated_unique_identifier_15",
      "name": "Current state matches regex",
      "op": "regex",
      "value": "^State"
    }
  ]
}

Parent State Condition

Name	Icon	Description	Available Operators
Parent State		Evaluates the state of a parent element.	=, !=, regex

Example

Visual Representation

Json Code

{
  "type": "combination",
  "id": "auto_generated_unique_identifier_10",
  "op": "and",
  "conditions": [
    {
      "type": "parentState",
      "id": "auto_generated_unique_identifier_11",
      "name": "Parent state is Active",
      "op": "eq",
      "value": "Active"
    },
    {
      "type": "parentState",
      "id": "auto_generated_unique_identifier_12",
      "name": "Parent state starts with A",
      "op": "regex",
      "value": "^A"
    }
  ]
}

Privilege Condition

Name	Icon	Description	Available Operators
Privilege		Evaluates the user's privilege level.	=, !=, regex

Handling Privilege Changes with Conditional States

A conditional state on a privilege evaluates whether the privileges have changed on the server. The front end requests the current session privileges from the server if the privileges stamp has changed. This ensures that any changes in privileges are accurately reflected in the application's state.

Example

Visual Representation

Json Code

{
  "type": "combination",
  "id": "auto_generated_unique_identifier_7",
  "op": "and",
  "conditions": [
    {
      "type": "privilege",
      "id": "auto_generated_unique_identifier_8",
      "name": "User is guest",
      "op": "eq",
      "value": "guest"
    },
    {
      "type": "privilege",
      "id": "auto_generated_unique_identifier_9",
      "name": "Not restricted",
      "op": "neq",
      "value": "restricted"
    }
  ]
}

Saved Condition

Name	Icon	Description	Available Operators
Saved Condition		References a pre-defined condition stored in the Saved Conditions area, allowing for reuse across different states.	N/A

Example

Visual Representation

Json Code

{
  "type": "combination",
  "id": "iiq55CwnDbkEbqtZ46HmuN",
  "op": "or",
  "conditions": [
    {
      "type": "reference",
      "id": "auto_generated_unique_identifier_5",
      "name": "Condition 2",
      "ref": "7EhcZvWyNCr6AqPqS139Mz"
    },
    {
      "type": "reference",
      "id": "auto_generated_unique_identifier_6",
      "name": "Condition 3",
      "ref": "7ymDgJc1iL6ca1Q8WzL43z"
    }
  ]
}

Condition Management

Add Condition (Local)

Local Conditions are specific to the currently active state and allow for state-specific conditions customization. To add a Local Condition to your state:

• From the Schema Window: If no conditions are currently set up, simply click the Add condition button in the schema window to insert a new condition at the base level of the state’s logic hierarchy.

• Using the Side Menu: For contextual additions within a specific logic level, select the Add condition option from the side menu. This will introduce a new condition card at the same hierarchical level as the location where you invoked the command.

  info

  For instance, in the visual example provided, if Add condition is selected from the side menu at the position of conditions c1 and c2, the new condition will be placed on the same level as these conditions.

  

  It ensures that your new condition is logically organized within the same group, maintaining the consistency and flow of the state's configuration.

  

Duplicate Condition

The Duplicate condition option allows users to create an exact copy of an existing condition or groups of conditions, preserving all configurations.

Rename Condition

To better reflect a condition's role within the Page, the Rename condition option enables users to change its default name.

Alternatively, users can click on the button next to the condition's name to initiate renaming


Upon initiating renaming, the condition name switches to an editable input field.

Save Condition

Using the Save condition option, conditions or groups of conditions can be stored as saved conditions accessible in the Saved States area.


Upon saving, a prompt will appear requesting a name for the saved condition.

Remove Condition

The Remove condition option is available for users needing to clear out unused or unwanted conditions from the schema. This tool helps declutter the configuration space by removing selected conditions or groups of conditions.


Upon initiating deletion, a confirmation popup will appear, requiring user confirmation to proceed.

Conditions JSON Editor

Accessing the JSON Editor

The JSON Editor can be accessed through the Conditions Interface by clicking on the JSON Editor button. This opens a dedicated editing area where users can view and edit the JSON representation of their conditions.

Initial JSON Blueprint

Upon addition, each condition's initial JSON structure appears in the editor as follows:

{
  "id": "auto_generated_unique_identifier",
  "name": "default_condition_name",
  "type": "unspecified"
}

This initial blueprint provides a template that users can modify to fit the specific requirements of their Page conditions.

Common JSON Fields

When working with conditions in the JSON Editor, users will encounter several common fields:

• id: A unique identifier for the condition (type: string).
• name: The name of the condition (type: string).
• type: Specifies the type of condition (e.g., qodlysource, privilege, parentState, reference, combination).
• path: The data path within the qodlysource (for qodlysource conditions).
• value: The value to compare against, which can be of various types (number, string, boolean, object, array, or null).
• op: The operator for comparison (e.g., eq, neq, regex, in, nin, gt, gte, lt, lte).

Conditional State Lifecycle

Conditional states are primarily applied during the Rendering and Post-Render Updates phases of the Page/Renderer lifecycle:

1. Rendering Phase:

   • The page renders its initial state, often defaulting to the Base state. This is when the initial content, styles, and layouts are displayed to the user.

2. Post-Render Updates Phase:

   • Based on the evaluated conditions and fetched qodly sources, the page updates its state. Conditional states modify the Base state to reflect user-specific configurations.

   • Users interact with the page, which might trigger further state changes and updates.

Preventing Base State Visibility

The Base state might be visible initially due to the timing of data fetching and condition evaluation relative to the rendering process. The page initializes its structure and components, then renders the Base state, which contains all potential elements and components.

To ensure the Base state is not visible before the correct state is applied, follow these steps:

1. Use the onInit Event:

   • Utilize the onInit event to set up all necessary qodly sources and conditions before the page is rendered.

   • This event runs before the rendering phase, allowing you to prepare the page state in advance.

2. Initialize Qodly Sources Early:

   • Ensure that all required qodly sources are fetched and available during the onInit event.

   • This ensures that the data needed for conditional states is ready before rendering.

3. Evaluate Conditions Pre-render:

   • Evaluate all conditions necessary to determine the user-specific state within the onInit event.

   • This includes checking priviliges and other relevant criteria.

Singleton Properties's Impact on State

Singleton computed properties are used to manage and return objects stored in Qodly Sources. These properties are typically invoked to refresh data or trigger server-side processes. However, their interaction with a state can lead to significant implications:

• State Dependency: When a singleton computed property updates a Qodly Source that is bound to a state condition on the Qodly Page, any change in this source can trigger a state change.

• Deserialize and Re-rendering: Clicking a button that invokes a singleton computed property can cause a state change. This triggers Qodly to deserialize and re-render the page to update the internal state of CraftJS, which can result in an entire page reload.

To illustrate, consider the following sequence of events:

1. Initial Action: A button with an onClick event calls a singleton computed property that returns an object and stores it in a Qodly Source. Clicking this button alone works as expected without reloading the page.

2. Triggering a Server-side Process: Another action triggers a server-side process through the singleton computed property.

3. Subsequent Action: Clicking the initial button again causes the page to reload. This happens because the Qodly Source used in the state condition is updated, triggering a state change. Qodly then deserializes and re-renders the page through CraftJS, leading to a full page reload.

To avoid unintended page reloads when using singleton computed properties, consider the following strategies:

• Minimize State Changes: Avoid binding state conditions to Qodly Sources that are frequently updated by singleton computed properties. This helps reduce unnecessary re-renders.

• Proper Navigation Handling: If you use a qodly source for navigation purposes, ensure its value is correctly updated during navigation events. This prevents unintended reloads due to outdated qodly source values.