Dynamic Refresh

Dynamic Refresh loads or swaps content inside a Panel component without reloading the entire page. It is a setting on the Panel component and uses a Plug-In component API call to pull component definitions from another module at runtime.

Benefits

• Seamless content delivery: Bring content into a Panel component without a full page reload, keeping the experience smooth for end-users.
• Improved performance: Logic and UI components are not loaded into a Panel component until they are needed.
• Improved reusability: Components can be reused across modules, reducing module size and improving maintainability.
• Reduced configuration bloat: Mimic to stay under the 16 MB module size limit in Express View.
• Conditional module imports: Use a business condition to determine which component content to load into the module.

Use Cases

• Contextual UI: Load rich, selection-specific content into a Panel based on end-user input. For example, clicking a See Details button displays account information in a side panel.
• Path-dependent questionnaires: Drive which questions appear next based on previous answers, replacing complex Navigation component configurations.
• Progressive loading: Trigger multiple Dynamic Refresh operations in sequence to render content in order of importance, mimicking an asynchronous load experience.
• Single-page applications: Use sidebar or top-level navigation to refresh the page's core content into a single dynamically refreshable Panel component.

How Dynamic Refresh Works

Dynamic Refresh separates two tasks: fetching component definitions (component JSON) and rendering them inside a Panel component.

A Dynamic Refresh operation occurs in two steps:

1. Fetch component definitions using a Plug-In component and the Get Module Components API.
2. Render the fetched components inside a Panel component using the dynamicRefresh Type.

Fetching Component Definitions

Use a Plug-In component with the Get Module Components API to fetch definitions from another module:

/fbu/uapi/modules/{{data.moduleID}}/components

The syntax {{data.moduleID}} references a Hidden component holding the module ID value. This lets Creators dynamically control which module content to load based on end-user input or submission data.

Component definitions can also be pre-fetched into submission data and rendered later, which is useful when content displays based on end-user interaction.

Rendering Inside a Panel

After the Panel component receives new components, it clears its existing components and renders the incoming ones. A single Panel component can be refreshed multiple times in a single session. Incoming components behave the same as components already in the module, including Panel settings, logic compatibility, and validations.

To remove all components from a Panel component, send an empty array ([]) to it using the dynamicRefresh Output Type.

Setting Up a Simple Dynamic Refresh

The UnqorkAI Build Agent can configure this setup automatically. Use the following prompt:

"Set up a simple Dynamic Refresh configuration. Add a Panel component with Property ID panelDisplay and Enable Dynamic Refresh set to ON. Add a Plug-In component with Property ID pluginGetComponent using the Get Module Components service, with an output that maps to panelDisplay using the dynamicRefresh option. Add a Button component with Property ID btnFireRefresh that fires pluginGetComponent on click."

To configure it manually or verify the settings, follow the steps below.

1. Configure the Panel Component

1. In the Module Builder, drag a Panel component onto the canvas.
2. In the Property ID field, enter panelDisplay.
3. Under Imported and Dynamic Content, set Enable Dynamic Refresh to ON.

2. Configure the Plug-In Component

1. Drag a Plug-In component onto the canvas, below the Panel component.
2. In the Property ID and Canvas Label Text fields, enter pluginGetComponent.
3. From Internal Services, select Get Module Components.
4. In Data Source URL, replace {moduleId} with the ID of the module containing the components to import.

   If the Express Role performing the API request does not have access to the module, the request fails.

5. In the Outputs table, add the following row:

   Property ID	Mapping	Option	Header
   panelDisplay	components	dynamicRefresh ▾	☐

6. Apply the settings.

3. Configure the Button Component

1. Drag a Button component onto the canvas, below the Plug-In component.
2. In the Property ID field, enter btnFireRefresh.
3. In Label Text, enter Call Components.
4. Under Actions Settings, in On Click, enter pluginGetComponent.
5. Save the module.

Compatibility

Panel Settings

Dynamic Refresh is compatible with all Panel settings except Enable Scrollspy. This includes the following:

• Panels configured to import a module at load and then refresh at runtime
• Panels configured as a modal and then refreshed at runtime

Logic Components

Logic components work the same way with dynamically refreshed components, provided the refreshed component exists when the logic executes. Supported behaviors include the following:

• Reference or target refreshed components as an or Output in a logic component, regardless of that component's position in the module.
• Use a Watch Trigger Type to watch refreshed component data. This only fires when the component changes the submission data value.
• Refreshed components can trigger or be triggered by other logic components.
• Logic components themselves can be refreshed into a Panel, acting as a mini page-load. For example, an Initializer component set to the New Submission Event Type fires when its conditions are met after refresh.

Validation

Refreshed components validate the same way as components already in the module. Dynamically refreshed components inherit their validation state from the module they refresh into.

Submission Data

• Component data: Incoming refreshed components automatically bind to corresponding keys in submission data. For example, if textField: Qorky exists in submission data and a component with Property ID textField refreshes into the module, the refreshed component displays Qorky.
• Submissions: The submission's module ID always corresponds to the module containing the refreshed Panel component, not the source module.

Limitations

• Unsupported components: The Advanced Datagrid component cannot be refreshed. The Advanced Datagrid, Data Grid, Freeform Grid, Repeater, and Uniform Grid components cannot be a parent of a Panel component being refreshed.
• Duplicate Property IDs: Modules cannot have multiple components with the same Property ID. Duplicate incoming components are rejected and logged in DevTools Console.
• Custom component definitions: Only Module Builder component definitions are supported. Direct manipulation of component definitions is not supported.
• Store Data in Database: To retain data in a submission, Store Data in Database must be set to ON on the component. The component must also be inside or linked to the application where the submission request originates.
• Server-side execution: Dynamic Refresh is not supported when executing a module server-side.
• Performance: Application performance varies with the number, size, and complexity of refreshed components. Limit a single Dynamic Refresh to 250 components and 2.5 MB of component definitions for optimal performance.

Best Practices

General

• Tag modules intended for Dynamic Refresh using the dynamic-refresh tag.
• Store module IDs for all modules that might be refreshed into the main module in a Data Table or Data Collection component.

Debugging

Set Display Errors in the Panel to ON to display Dynamic Refresh error messages inside the Panel component. Errors are always logged in DevTools Console regardless of this setting.

The following error types may occur:

• Duplicate Components Error: An incoming component has a Property ID matching an existing component. The refresh completes but excludes and logs duplicates.
• Unsupported Component Type Error: An incoming component is of an unsupported type. The refresh completes but excludes and logs unsupported components.
• Unsupported Parent Component Error: A parent of the Panel component being refreshed is of an unsupported type. The entire refresh is halted.
• Components Definition Error: The component definition sent to the Panel is not a valid Unqork definition. The entire refresh is halted.

Performance

• Limit a single Dynamic Refresh to 250 components and 2.5 MB of definitions.
• Pre-fetch component definitions into submission data before they are needed, then render on demand.
• Refresh away unused components by sending an empty array ([]) to the Panel component using the dynamicRefresh Output Type.

Logic

• Use Post Refresh Trigger to sequence logic after all incoming components have loaded and rendered.
• Prevent duplicate refresh operations from running simultaneously to reduce unnecessary API calls. Use a Button component with Restrict to Single Click set to ON, re-enabling it using logic after the refresh completes. Alternatively, use a Decisions, Initializer, Plug-In, or Data Workflow component with a Watch Trigger Type and Set Debounce greater than 100ms.
• Perform the Dynamic Refresh first and confirm it is complete before populating refreshed components with data or firing downstream logic.