Rendering Data Design

Rendering Data Design turns a reusable Data Design and a set of values into visible content on a Page.

A Data Design defines what one item looks like. Its placeholders identify the values that can change, and a rendering workflow supplies those values and places the resulting content into a target area. The same design can be rendered once for a selected record or repeatedly for a list of records.

Use rendering for product catalogs, search results, profile directories, dashboard tiles, custom record lists, and other interfaces where Project data needs a presentation more flexible than a standard table.

This page focuses on the runtime workflow: preparing data, identifying rendered items, placing results, refreshing the display, and coordinating interactions. For the visual structure, see Creating Data Design. For dynamic fields, see Placeholders.

How Rendering Works

Rendering connects three parts of a Page:

Part	Purpose
Data Design	Defines the reusable visual structure for one item.
Rendering Data	Supplies values matching the design's placeholder Field Names.
Target Area	Receives the visible instance or repeated instances generated from the design.

For example:

Data Design (ProductCardDesign)
  Card
    Image             → ProductImage
    Heading           → ProductName
    Text              → ProductPrice
    Link Button       → DetailsUrl

            +

Product records prepared by Page Flow

            ↓

Container (ProductResults)
  Rendered card: Trail Backpack
  Rendered card: Rain Jacket
  Rendered card: Hiking Boots

The Data Design is the source pattern; ProductResults is an example target area. They serve different purposes, even when both are part of the same Page.

Adding a Data Design to the Page does not automatically retrieve or display records. Page Flow or another supported rendering mechanism must provide data and place the generated content in the target area.

Before You Render

Prepare the following parts before configuring the runtime workflow:

1. A Data Design: Create the visual layout for one item using supported Page Elements.
2. Placeholders: Configure Dynamic Content and Field Names for the element properties that should vary between items.
3. A target area: Add a suitable Container, Column, Section, Card Group, or other supported destination outside the Data Design.
4. A data source: Determine where the item values will come from, such as Project Database records, query results, an Integration, or values prepared by Page Flow.
5. A rendering workflow: Configure supported Page Flow behavior to supply the values and render them into the target area.
6. Record context, if needed: Identify how actions inside a rendered item will refer to the correct record.

Choose clear element Names for the Data Design, the target area, and any controls that the workflow will need to reference. Names help you maintain the Page; they are not substitutes for placeholder Field Names or rendered instance identifiers.

Rendering Lifecycle

A typical rendering sequence is:

1. Start the workflow. Page Flow responds to Page initialization, a user action, a filter change, or another supported event.
2. Obtain the data. The workflow retrieves permitted records or prepares the required values.
3. Prepare the values. Data fields are mapped and formatted to match the placeholder Field Names expected by the Data Design.
4. Select the design and target. The workflow identifies which reusable design to render and where the result should appear.
5. Render the items. Each supplied item produces a visible instance of the design, using its own values and, where configured, instance identifiers.
6. Place the results. The generated content appears in the target area according to the workflow's supported placement behavior.
7. Handle subsequent interactions. The workflow can respond to filtering, refreshing, or record-specific actions as configured.

This is a conceptual lifecycle, not a list of exact Page Flow block names. The available operations and inputs should be configured using the supported Page Flow tools for the Project.

For more about browser-side workflow configuration, see Page Flow.

Rendering One Item

Render one item when the Page needs a single record presented through a custom layout.

Common examples include:

• A featured product card.
• A selected customer or member profile.
• A detail panel for a chosen record.
• A dashboard summary tile.
• A preview of a record before an action.

For example, the Page Flow may prepare one product as:

{
  "ProductName": "Trail Backpack",
  "ProductPrice": "$89.00",
  "ProductImage": "/media/backpack.jpg",
  "DetailsUrl": "/products/trail-backpack"
}

If the Data Design has matching placeholders, these values populate the corresponding supported element properties in the rendered instance.

The workflow then places that instance into a chosen target area, such as a FeaturedProduct Container.

If the selected record changes, determine whether the existing content should be replaced or updated through the available rendering behavior. Otherwise, the old record may remain visible alongside the new one.

The JSON example illustrates a set of placeholder values; it is not a Page Flow API call or a required data-object format.

Rendering Many Items

Render multiple items when the same structure should appear for a list of records.

Common uses include:

• Product catalogs.
• Search results.
• Member directories.
• Event listings.
• Custom record rows.
• Dashboard collections.

Suppose a Page has three product records. The workflow prepares the values for each record and uses the same Data Design for every item.

Product records
  Record A: Trail Backpack
  Record B: Rain Jacket
  Record C: Hiking Boots

          ↓

ProductCardDesign applied to each record

          ↓

ProductResults
  [Trail Backpack card]
  [Rain Jacket card]
  [Hiking Boots card]

Each instance uses the same visual structure but receives its own image, name, price, and link destination.

The Page's target area and surrounding Layout Elements determine how the repeated items are arranged. Do not assume that rendering automatically creates a grid, paginates results, or adds filtering controls.

Rendering Order and Record Count

Consider the order in which records should appear, the number of items rendered, and the space available on the Page.

For example:

• A search page may display matching records in a selected order.
• A product catalog may render a limited group initially, then offer a Load More action.
• A dashboard may display only the most relevant summary items.

Sorting, limiting, paging, and additional loading must be implemented through the supported data and Page Flow capabilities appropriate to the application. They are not automatic features of a Data Design.

Target Areas

Rendered content requires a destination on the Page. The target area defines where the generated items appear and often provides the surrounding layout, alignment, spacing, and overflow behavior.

Target Area	Typical Use
Section	A full-width results or listing region.
Column	Results within one part of a larger layout.
Container	A group of repeated cards, tiles, or custom rows.
Card Group	A card-oriented collection where the selected structure is supported.
Content Area	A defined region for generated content within a larger interface.

The appropriate target depends on the element structure and the rendering operations available in the current Page editing context.

Preparing a Target Area

1. Add the supported layout element that will hold the rendered items.
2. Give it a clear Name, such as ProductResults or MemberDirectoryResults.
3. Place it where visitors should see the results, separately from the source Data Design.
4. Configure width, spacing, alignment, and responsive layout using the available Element Settings.
5. Configure Page Flow to use the intended target.
6. Preview the results with one item and several items.

For example:

Page
  Data Design (ProductCardDesign)
    Card
      Image
      Heading
      Text
      Link Button

  Container (ProductResults)
    [Rendered instances appear here]

The visual layout of one item belongs in ProductCardDesign. The overall arrangement of multiple cards belongs to ProductResults and its surrounding layout.

Avoid Mixing Unrelated Content

A target area intended for refreshed results is easier to manage when it contains only the output that the workflow needs to replace or update.

If the area also contains permanent headings, help text, or filters, clearing the results could unintentionally remove those elements. Keep persistent Page content in a separate surrounding area when appropriate.

For example:

Section (Catalog)
  Heading (Products)
  Filter Controls
  Container (ProductResults)
    [Rendered results only]

Preparing Data for Rendering

Data may originate from:

• Project Database tables or supported queries.
• Results of a permitted Cloud Flow operation.
• Integration data available to the Project.
• Values calculated or prepared by Page Flow.
• A combination of supported Project data sources.

The rendering workflow must supply values that correspond to the Field Names configured in the Data Design's placeholders.

For example:

Source Field	Placeholder Field Name	Prepared Value
name	ProductName	Trail Backpack
price	ProductPrice	$89.00
image_url	ProductImage	/media/backpack.jpg
product_slug	DetailsUrl	/products/trail-backpack

The mapping between differently named source fields and placeholder Field Names must be handled by the appropriate workflow. Do not assume that the renderer automatically performs this mapping or applies display formatting.

Matching Placeholder Values

A product-card design might expect these Field Names:

• ProductName
• ProductDescription
• ProductPrice
• ProductImage
• Availability
• DetailsUrl

Prepare the relevant value for each record before rendering. Use supported image locations and valid destinations for image and link properties.

For example, a numeric database price may need to be formatted as $89.00 rather than displayed as 89. Similarly, a record ID may need to be used to prepare the correct details URL.

For the detailed rules around Field Names, supported properties, and missing data, see Placeholders.

ID and ID2

Rendered Data Design instances can use an ID and an optional ID2 to distinguish one item from another.

These identifiers are useful when several copies of the same design appear on a Page, particularly if a rendered item contains an action or control that needs to operate on the corresponding record.

Examples of possible identifiers include:

Identifier Choice	Example Use
Record ID	Identify a customer or order.
Product ID	Identify a product card.
User ID	Identify a member profile.
Category ID and Product ID	Distinguish products within a category-oriented display.
Parent ID and Child ID	Identify a child record in the context of its parent.

Using ID and ID2 Together

For example, suppose a Page displays items related to orders:

Rendered item
  ID  = Order123
  ID2 = Line04

The two values can provide the workflow with context for the specific rendered instance, when supported by the action being configured.

ID and ID2 are not placeholder Field Names. They are used to identify rendered instances, while Field Names identify the values used to populate the design.

Identifier	Purpose	Example
Element Name	Identifies an element in the editor or a supported workflow.	DetailsButton
Placeholder Field Name	Identifies a value supplied during rendering.	ProductName
ID	Identifies a rendered instance or its record context.	Product102
ID2	Supplies an optional second identifier when needed by the supported workflow.	Variant03

An underlying Database record ID may be a good choice for ID, but the relationship should be configured intentionally rather than assumed automatically.

Choosing Stable Identifiers

Prefer identifiers derived from stable record keys when later actions must refer to a specific item.

• A stable record ID remains meaningful even when the display order changes.
• A row number can be useful for presentation, but may change after sorting or filtering.
• When the same record can appear in more than one context, consider what additional context a second identifier may need to represent.
• Test item-specific actions after the list is reordered, filtered, or refreshed.

The exact manner in which a Page Flow operation accepts or exposes ID and ID2 depends on that supported operation. This page does not prescribe an undocumented syntax or assume that identifiers are automatically passed to every Button or control.

Interactions with Rendered Items

Rendered items can include supported interactive elements, such as Links, Buttons, inputs, toggles, and collapsible areas.

For example:

• View Details: Open a record-specific destination prepared as a link placeholder.
• Select Product: Capture the intended item's identifier for a subsequent Page Flow step.
• Toggle Favorite: Coordinate an item-specific state change or permitted data operation.
• Edit Record: Open a Form or other supported editing experience for the selected record.
• Expand Details: Reveal additional content for the intended item.

The visual presence of a control does not automatically configure its runtime action or associate it with a particular record. The relevant Page Flow or supported element action must establish that behavior.

Example: Selecting a Product

A product-card Data Design includes a View Details button.

For direct navigation, the design can use a supported dynamic link destination, such as DetailsUrl, so each rendered card opens the corresponding product.

If selecting the product instead needs to save a selection, open a modal, or call Cloud Flow, coordinate the Button with Page Flow and the appropriate item context. Use ID or ID2 where supported to distinguish instances.

A record-specific interaction should be tested against multiple rendered items. Do not assume that the first instance's values or hard-coded destination will be correct for every item.

Replacing, Appending, Prepending, and Updating Results

Choose how the visible target area should change when new data is rendered. Different workflows need different behavior.

Display Strategy	Typical Use	What to Consider
Replace	Search results, filter changes, refreshed dashboards.	Old results should no longer remain in the target.
Append	Load More and incremental lists.	Existing items remain while new items are added after them.
Prepend	Activity feeds or newest-first views.	New items appear before the existing items.
Update in place	A record's status or summary changes.	Only the intended item should be updated, if supported.

These are application display strategies, not a promise that the Page Flow toolbox provides a separate operation for each strategy. Implement them using the supported rendering and element operations available in ioLoop.

Replacing Results

Replacing is appropriate when an earlier set of results is no longer valid.

For example, if a visitor searches for backpack and then searches for jacket, the Page should not normally retain the old backpack cards below the jacket results.

A typical workflow is:

1. Receive the new search or filter value.
2. Retrieve or prepare the matching records.
3. Remove or replace the previous rendered results through supported behavior.
4. Render the new items into the target.
5. Show an appropriate empty state if there are no matches.

Appending Results

Appending is useful when a visitor requests more of the same results.

For a Load More experience, the workflow can preserve the existing rendered items and add the next group when supported. It should also track which records have already been displayed to avoid accidental duplicates.

The Data Design itself does not provide pagination or Load More controls automatically. Those behaviors must be configured separately.

Prepending and Updating Individual Items

An activity feed may need newer items at the start of the list. A card may need its status changed after an action. Where supported, Page Flow can coordinate these behaviors with the target content and item identifiers.

If the current rendering mechanism does not support directly updating an individual item, an alternative may be to prepare the updated data and re-render the relevant results area. Choose the approach supported by the Project's Page Flow capabilities and the expected user experience.

Page Flow and Rendering

Page Flow is commonly used to coordinate Data Design rendering with events, data retrieval, user input, and other Page behavior.

Examples include:

• Rendering catalog items when a Page starts.
• Updating search results after a visitor submits a query.
• Refreshing cards after a Form changes a record.
• Rendering records related to a selected customer or order.
• Displaying results returned by Cloud Flow.
• Handling actions within individual rendered items.

Page Flow runs in the browser. It can interact with permitted Project data interfaces and invoke Cloud Flow when protected server-side processing is required.

Example: Product Catalog with Search

Consider a Project Page that displays a product catalog.

Page structure:

Page
  Search Input
  Search Button
  Data Design (ProductCardDesign)
    Card
      Image               → ProductImage
      Heading             → ProductName
      Text                → ProductPrice
      Link Button         → DetailsUrl
  Container (ProductResults)
    [Rendered cards]
  Text (NoResultsMessage)

Workflow:

1. Prepare the design. Configure the product card and its placeholder Field Names.
2. Prepare the target. Name the destination ProductResults and configure its layout.
3. Start the search. Respond to Page initialization or a visitor's search action through Page Flow.
4. Get records. Retrieve the products the current visitor is allowed to see.
5. Apply the search. Use the relevant query or supported filtering logic to obtain matching items.
6. Prepare values. Map each record to the expected placeholder names, including display-ready prices and valid image and details locations.
7. Replace earlier results. Ensure the previous search results do not remain mixed with the new results.
8. Render the cards. Use the Data Design and supported rendering behavior to populate ProductResults.
9. Handle no matches. Show a meaningful message if no products match the search.
10. Test interactions. Verify that View Details opens the correct product from each card.

This example explains the intended application workflow. It does not imply a particular Page Flow block name, query syntax, or automatically available search feature.

Loading, Empty, and Error States

A rendered interface should distinguish between a workflow that has not finished, a valid empty result, and an operation that failed.

State	Recommended User Experience
Loading	Indicate that results are being prepared, especially for slower operations.
No records	Display a clear empty-state message such as No matching products found.
Error	Show an understandable message and an appropriate retry option where useful.
Successful results	Display the rendered items and any relevant result information.
Refreshing	Avoid leaving users uncertain whether a filter or refresh action took effect.

These states can be implemented through supported Page Elements and Page Flow behavior; they are not automatically provided by every Data Design.

Consider what happens if a visitor changes a filter or starts another search before an earlier request completes. The Page should not leave results from the wrong request visible as though they matched the latest selection. Coordinate request handling and rendering through the available Page Flow logic.

Responsive Layout and Performance

The Data Design controls the structure of one item. The target area's layout determines how repeated instances fit into the Page.

For responsive layouts:

• Test the rendered list at desktop, tablet, and mobile widths.
• Keep text and images readable with long or missing values.
• Confirm that Buttons, Links, and toggles remain usable on narrow screens.
• Review the spacing between items, not only the spacing within the original design.
• Avoid relying on a wide multi-column arrangement for essential information.

For longer lists, consider whether the application should render every item at once or load a manageable set of results. The appropriate approach depends on record counts, data retrieval, Page Flow behavior, and the complexity of the individual design.

Do not assume that Data Design automatically provides virtualization, lazy loading, pagination, or infinite scrolling.

For layout configuration, see Layout Elements and Element Settings.

Data Access and Security

Data Design renders information in the browser. It is a presentation mechanism, not an authorization system.

When showing protected records or providing record-changing actions:

• Retrieve only data that the current Project User is permitted to access.
• Apply the appropriate Project Database access controls.
• Use trusted Backend logic, such as Cloud Flow, for operations requiring protected credentials or centrally enforced authorization.
• Validate permissions for record-changing actions independently of what the Page displays.
• Do not rely on a hidden item, a filtered result list, or a missing Button to prevent unauthorized access.

Filtering a rendered list changes what users see; it is not a substitute for enforcing which records they may retrieve or modify. Page Flow coordinates the browser-side interface, while protected operations require the relevant Database or Backend security controls.

For more information, see Page Flow and Cloud Flow.

Previewing and Testing

Save the Page and use Preview to test the complete rendering workflow, not only the source design with example content.

Test Case	What to Check
No records	The target and empty-state message behave as intended.
One record	One complete instance appears in the correct location.
Many records	Items remain readable and the Page stays usable.
Different records	Each instance shows its own values, images, and links.
Missing fields	Prepared fallbacks or supported empty-value behavior work correctly.
Long values	The design handles large titles and descriptions without breaking the layout.
Search or filter change	Earlier results do not remain mixed with the new results.
Repeated refresh	Results are not duplicated unintentionally.
ID and ID2	Item-specific actions refer to the intended record context.
Mobile layout	Items fit the available width and controls remain accessible.
Access restrictions	Users see only the records and actions they are authorized to use.
Errors	The Page handles failed data retrieval or rendering in a clear way.

Preview uses the Project's development context. Be mindful that permitted Database, Cloud Flow, or Integration operations initiated during testing may have effects beyond visual preview.

Saving does not by itself publish Page changes. When ready, use the Project's publishing workflow and verify the published application.

For more information, see Previewing.

Troubleshooting Rendering

Symptom	What to Check
Nothing appears	Confirm that the rendering workflow runs, has data, selects the intended Data Design, and points to a valid target.
Only the source design is visible	Confirm that the workflow actually creates rendered instances rather than relying on the source design alone.
Text or image values are missing	Check Dynamic Content, Field Names, and the values supplied for each record.
Values appear in the wrong places	Review the mapping between the prepared data and placeholder Field Names.
All items show the same record	Review how the rendering workflow supplies item-specific values.
Old results remain after filtering	Review the target's replacement or clearing behavior.
Repeated items appear after refresh	Check whether the workflow appends when it should replace, or processes the same records more than once.
A Button affects the wrong record	Verify item identifiers, available record context, and Page Flow action configuration.
Items overlap or overflow	Review the target area's layout and responsive settings.
The Page becomes slow with many items	Review record count, data retrieval, item complexity, and whether incremental display is appropriate.

When to Use a Data Table Widget Instead

Use a Data Table Widget when a standard record-oriented table is the better experience.

Requirement	Recommended Approach
Standard record columns and rows	Data Table Widget
Built-in record table controls	Data Table Widget
Search, pagination, and table row actions	Data Table Widget
Custom product cards or rich search tiles	Data Design
Profile or directory blocks with custom layouts	Data Design
Repeated branded content with custom structure	Data Design
Custom record actions within a repeated visual design	Data Design with supported Page Flow behavior

Data Design provides visual flexibility; it does not automatically replace the Data Table Widget's built-in record-oriented features.

Good Practices

• Keep source and target separate. The Data Design defines one item; the target holds rendered instances.
• Prepare matching data. Align supplied values with placeholder Field Names and format them for display.
• Use stable IDs. Prefer record identifiers that continue to identify the same item after sorting or filtering.
• Choose the right update strategy. Replace results for new searches; append only when additional items should remain alongside existing ones.
• Keep targets focused. Avoid clearing permanent Page content along with refreshed results.
• Handle empty and error states. Make it clear when no records match or a request fails.
• Test item-specific actions. Verify that every Button or Link uses the intended record or destination.
• Design for responsive repetition. Inspect several rendered items at different viewport sizes.
• Keep data access controlled. Enforce permissions through the applicable Database and Backend capabilities.
• Use Data Table Widget where appropriate. Choose the ready-made table when its built-in record interface better fits the task.

Common Mistakes

Avoid these patterns:

• Assuming that adding a Data Design automatically displays records.
• Rendering into the source Data Design instead of the intended target area.
• Using Field Names that do not match the prepared rendering values.
• Assuming that design-time sample content is a guaranteed fallback for missing fields.
• Using row position as a permanent identifier for records that can be reordered.
• Assigning the same hard-coded destination or record context to every rendered item.
• Appending new search results without removing obsolete results.
• Clearing the entire Page section when only the results container should be refreshed.
• Expecting Data Design to provide built-in search, paging, or record actions without additional configuration.
• Testing only one ideal record instead of multiple, empty, and incomplete results.
• Treating browser-side filtering or hidden controls as authorization.

Rendering Data Design is most effective when the source layout, placeholder values, target area, and record-specific behavior are deliberately coordinated. That separation makes it possible to use one visual design for many records while keeping the resulting Page maintainable.

Technical Reference

Use the Programming Guide for exact block names, inputs, and client API signatures; use this product guide for workflow, concepts, and authoring guidance.

• Content from Data Design block
• Set Content block
• Set Content in Data Design block
• $io.content.fromDataDesign
• $io.dom.dataDesignElementSel
• $io.dom.setHtml

Related Topics

• Data Design
• Creating Data Design
• Placeholders
• Data Table Widget
• Tables and Cards
• Layout Elements
• Element Settings
• Page Flow
• Cloud Flow
• Previewing