Design Pages

Each page in your application is composed of various artifacts. When you open a page, there are various editors for examining and modifying the artifacts used in the page.

Use the Page Designer

The Page Designer provides an editor, a Components palette, and a Structure view for designing the layout of a page.

When editing a page's layout, you use the Properties pane in the Page Designer to modify component properties and also to open any Quick Starts that can be used with the component selected in the editor.


Description of page-designer-overview.png follows
Description of the illustration page-designer-overview.png

The Page Designer Toolbar

When a page artifact is open in the Page Designer, the toolbar provides tools for modifying the Page Designer's behavior and appearance.

Toolbar Item Description
Components

Toggles the Component palette

Structure

Toggles the Structure view

Reload Page icon

Reloads the page

Page Input Parameters icon

Opens a dialog box for entering input parameters for the page.

Who Am I icon

Opens a dialog for selecting the user roles that are used when previewing pages in Live mode.

Device selector icon

Opens a menu for selecting the screen size represented by the canvas. This menu includes the default Fit to Canvas option that resizes the canvas to always take up all available space between the left and right panes. You can also use the Custom option to set the minimum and maximum values for viewport resolution and resize the canvas to whatever size you want.

Show/hide bezel icon Shows or hides a mobile device's bezel (the border between a device's screen and its frame).
Zoom Canvas icon

Opens a dialog box for changing the magnification of the canvas.

Live/Design/Code toggle icon

Toggles between the Live, Design, and Code modes of the page editor. You can also hold the Ctrl key (Cmd on Mac) to momentarily switch between modes, for example, to check the values in a drop-down menu by holding the Ctrl key and clicking the menu on the canvas.

Properties

Toggles the Properties pane in the Page Designer.

The Page Editor

The Page Designer contains an editor that you use to design, view, and edit your application's pages. The editor has three modes: Live, Design, and Code. You switch between the modes using the mode toggle in the Page Designer's toolbar.

When editing a page, you use the following modes of the page editor to navigate the pages in your application and edit a page's layout and code:

  • Live mode: Displays the page as it appears when published, and the elements in the page also behave as they do when published. You use Live mode to interact with the pages in your application to navigate to different pages, create and modify business objects, and confirm that your application is behaving as you expect.
  • Design mode: Contains a canvas area that you use to place and position components in the page. You can hold down the Ctrl key to temporarily switch between Live mode and Design mode.
    Description of page-designer-canvas.png follows
    Description of the illustration page-designer-canvas.png
  • Code mode: Contains an editor that you use to edit the page's code. In Code mode, you can drag components from the Components palette and drop them directly into valid places in the code in the editor. When you use the Structure view to edit and reposition elements, the changes are automatically reflected in the code.

The Components palette, Structure view, and the Properties pane can be used the same way in each mode. When you select an item in one mode, the item remains selected when you switch to a different mode. For example, when you switch from Design to Code mode, the source code of a component selected on the canvas will be highlighted in the code editor. All the modes are synchronized, so that changes you make in the Properties pane or Structure view are visible when you switch to a different mode.

The Components Palette

The Components palette contains UI components and organizational elements that you use to build your pages.

You add an element to a page by dragging it from the palette onto the canvas. Click Components to toggle the display of the palette.


Description of page-designer-palette.png follows
Description of the illustration page-designer-palette.png

The Structure View

The Structure view provides a structural view of the components on the canvas. You can use the Structure view to easily see the layout of components used in the page and the components that they contain, and to reposition components within the page's structure.

Click Structure in the Page Designer to show or hide the Structure view. When you select a component in the Structure view, the component is also selected on the canvas and its properties are displayed in the Properties pane. You can organize and re-position components in the page by dragging them into position in the Structure view and by dragging them directly onto the canvas. You can select multiple components to simultaneously re-position them in the Structure view, for example, to move them into a new container.



You can also drag components from the Components palette or canvas into the Structure view to add them to the page. When you hover your cursor over a component in the Structure view, a tooltip appears displaying details about the component, for example, its id, classes or hints about its content. Right-clicking a component opens a popup menu with actions you can perform on the component, including deleting it, surrounding it or to selecting its parent component.

You can use the Structure view's options menu to display the component's details You can also enable Show empty slots in the menu to display the location of empty slots. When the empty slots are visible, you can easily locate the slot where you want to drop a component. Even when they are not visible, you can easily locate available slots by pausing over a component node when you are dragging a component into the Structure view. If the component node has slots, a popup menu opens that lists the available slots; you can then drop your component into the desired slot in the popup menu.



The Properties Pane

The Properties pane displays the properties of the component that is currently selected on the canvas or in the code editor.

Depending on the component that is selected, the Properties pane might have additional tabs for modifying the component’s attributes or its behavior. When you add a collection component, such as a table or list to the canvas, the Properties' Quick Start tab contains a list of Quick Start wizards that can help you add some actions and components that are typically associated with the component, such as mapping the collection to data and adding Create and Detail pages. You can use the toggle button in the toolbar to hide or show the Properties pane.

Activate Role-Based Application Preview

Application roles can be used to secure access to components and data in your application. You can preview how the role-based security settings of your application will affect the layout of pages and the behavior of your application.

Role-based security enables you to configure the data and pages that are accessible to users based on the user’s role. The security settings for your components and business objects will determine the components and data that are visible to users, how users can navigate between the pages and the layout of the pages in your application. See Allow Anonymous Access.

When viewing pages in the Page Designer, by default the pages that you see are not affected by the security settings. To see how your security settings will affect your application, click Who am I? in the Page Designer toolbar to open the Who am I? role selector.


Description of page-designer-whoami-toolbar.png follows
Description of the illustration page-designer-whoami-toolbar.png

The Who am I? role selector displays a list of the application roles defined in the application. By default, all the pages and data are accessible because all roles are selected and active. You use the Who am I? role selector to select the roles that are currently active.



Multiple roles can be active simultaneously, but at least one role must always be active. For a more accurate representation of how your application will look and behave for a specific role, you might want to deactivate all the roles except the one you are interested in. For example, if Anonymous User and Authenticated User are both active, you are seeing the application as it appears to users that are signed in and to users that are not signed in. By deactivating the Authenticated User role you will see and experience the application as an Anonymous User would see it. An anonymous user that was not granted rights to view data in a business object would not see any data if they visited the collection page for the object. Additionally, if View access was not granted, links in the UI to the collection page would be hidden from the anonymous user.

Use the Diagram View

As your application takes shape in the Page Designer, you can use the Diagram view for a visual representation of how your application is structured.

The Diagram view, shown only for application and flow artifacts, displays an application's root pages, flows, and pages within flows. It's a handy tool that lets you view default pages, navigation flows, even audit status at a glance.

When you open an application artifact, the Diagram view displays the application's root page as well as a hierarchical view of the artifact's flows and subflows. When you open a flow artifact, the Diagram view displays the pages contained in the flow. Here's an example of what you might see when you click the Diagram tab for an application:
Description of diagram.png follows
Description of the illustration diagram.png

You can expand or collapse a flow to show or hide its pages (and optionally, sub-flows). Click a page to view its navigation flow. For example, clicking the customer-start page shows navigation icons (Navigation icon Navigation icon) on the accounts and contacts page, indicating that you can navigate from customer-start to those pages and back. When navigation is one way, meaning you can go from one page to another but not navigate back, you'll only see the Navigation icon icon, as shown on the side-banner-start page. Notice how flows or pages that don't have any relationship with the selected page fade into the background.

The Diagram view also flags pages with audit issues (Audit warning icon or Audit error icon). These issues also show at the flow level, a useful indicator when the flow is collapsed that audit issues exist in the flow's pages.

Simply double-click an artifact (a root page, a flow, or a page) to open up the artifact's editor and make changes as required.

Use Keyboard Shortcuts

While in the Page Designer, you can use these keyboard shortcuts to help you move around quickly:

To do this: Use this on Mac: Use this on Windows:

Find and open a file in a web or mobile app

Command-P

Ctrl+P

Find a given string in a file (or in the Code editor)

Command-Shift-F

Ctrl+F

Undo/redo

Command-Shift-Z

Ctrl+Z

Except for common Windows shortcuts such as cut, copy, and paste, Visual Builder does not support shortcuts like the ones described here.

You can also use shortcuts when working with code editors in the Designer (HTML, JSON, JavaScript, and Code view in the Page Designer). See Work with Code Editors.

Work with Pages and Page Layouts

You create new pages in the Navigator and then use the Page Designer to edit the pages.

All the pages in your application are created within one of the flows in your app, with the exception of root pages. A root page is a special type of page which provides the entry point for your app, and contains the app's header and footer elements, and a container for the app's flows. You set the app's default root page in the General Settings tab in the app artifact's Settings editor, and the root page's default flow in the General Settings tab in the root page's Settings editor.

Create Pages

You create new pages using the Create Page dialog box that you open from the Navigator.

To create a page, you click Create Page ( Create Page icon ) next to the flow artifact or root pages node in the Navigator.

To create a new page in a flow:

  1. Open a web or mobile application in the Navigator and expand the app node.
  2. Expand the flow where you want to create the page.

    Your app contains one or more flows that are created by default when you create the app. You can expand a flow node to see the pages in the flow.


    Description of artifact-browser-create-page.png follows
    Description of the illustration artifact-browser-create-page.png
  3. Click the Create Root Page icon ( Create Page icon ) next to the flow where you want to create the page, then select Create Page.
  4. Enter the name of the new page in the Id field of the Create Page dialog box. Click Create.

After a page is created, you can change the page title in the page's Settings editor. You can also click Rename by double-clicking the page in the Navigation.

Edit the App Header and Footer

You can edit your app's header and footer elements by modifying the root page in the Page Designer.

The default entry page for you app is a root page that contains a header, a footer, and a flow container where a flow is embedded. A root page named shell is created by default when you create the app, and the main flow is set as the default flow displayed in the flow container in the root page.

To edit the app's header and footer:

  1. Select the page under the root pages node in the Navigator to open it in the Page Designer. The default root page is named shell.
  2. In the Design view of the Page Designer, select the component in the header or footer that you want to edit.
    You can select the component on the canvas or in the Structure view.
  3. Edit the component's properties in the Properties pane.

About Containers and Layout Components in Pages

You design and edit your app's pages in the Page Designer. Each page has a preferred layout, and you can add other layout components to the page to help you organize the components when designing pages.

Every page you create has a preferred page layout: Grid (default), Flex, or Block. When you select the entire page, you can choose which layout you want to use in the Properties pane. Here's an overview of each layout:
Preferred Page Layout Description
Flex The Flex layout allows you to add components in rows of any size. In a flex layout, you can lay out the children of a flex container in any direction, and the children will grow to fill unused space or shrink to avoid overflowing the parent. You can also nest boxes (for example, horizontal inside vertical or vertical inside horizontal) to build layouts in two dimensions.

The Flex layout provides the most flexibility and you can adjust several properties for alignment, justification, and so on in the Properties pane.

Grid (default) The Grid layout builds on the Flex layout, but adds a 12-column grid and rows that make it easier to align elements when you position them. The pages in your application incorporate responsive design to resize gracefully based on the size of the display area of the device.
Block The Block layout displays components that you drop on a page as blocks; each component starts on a new line and takes up as much horizontal space as it can. This layout is useful when your app already includes hand-coded pages, or when you want to drop a few components on a new page and manually adjust the layout.

Every component that you add to your page is placed in a row in the page's Grid or Flex layout, or in a layout component that you've placed in the page layout. You can add layout containers and components to rows to help organize components in the page. You can place multiple containers within a single row, or automatically create a new row by placing a container or layout component above or below an existing row. For each row in a Grid or Flex layout, you can modify its display settings in the Properties pane to control the layout of the components within the row. Components dropped on the page that uses the Block layout aren't automatically wrapped in Grid or Flex rows.

Containers and layout components can be nested to organize components and to position them precisely.



You add layout containers and components to a page by dragging them from the Layout category in the Components palette and placing them on the canvas or in the Structure view. The Layout category has various types of containers and layout components, and some are specifically designed to help you with common design styles, such as different ways to display navigation links or data.



You can use the Structure view in the Page Designer to see the components in each row in your page and to reposition them. When you select a component in the Structure view, it is also selected on the canvas and its properties are displayed in the Properties pane. You can also drag components from the Components palette directly into the Structure view.



Layout components are predefined Oracle JET components and styles that can be applied to page elements. You can modify the properties of each component in the Properties pane. The following table describes some of the commonly used containers and layout components available in the Components palette. For examples of how they look and can be used, see the Layout & Nav section in the Oracle JET Developer Cookbook.

Container Components Description
Flex Container The flex container is a flexible container which is useful for responsive designs that optimize the use of the available space.
Grid Container The grid container is a 12-column grid that is useful when you want to align components precisely according to the grid.
Bar Container The bar container is a three-section layout containing a start and end section sized to its content and a middle section that stretches.
Form Layout The form layout is optimized to display the label and input pairs commonly used in forms.
Masonry Layout The masonry layout is a responsive grid of tiles containing arbitrary content. You can specify the size of each tile in the Properties pane.

Add a Container or Layout Component to a Page

You add a layout to a page by dragging it from the Layout category in the Components palette and placing it on the canvas or into the Structure view.

You use the Properties pane to select the type of layout used to position components on the page and within page rows. Pages can have a Flex layout, a Grid layout, or a Block layout. You can combine layout types in your page by creating new rows in the page, placing multiple layouts within rows and by nesting layouts. Each row in a page can have a Flex, Grid, or Bar container. When you drag an element onto the canvas, some elements will expand to fit all the available columns in the row. Other elements have a default column span that you can adjust.

To add a container or layout component to a page:

  1. Drag the container or layout component from the Components palette and place it on the canvas.

    When a container is dragged onto the canvas, the locations where the component can be placed are highlighted on the canvas. If you do not place the component in an existing row, a new row containing the component is created when you place it on the page. For example, here's what your canvas might look when you're dragging a Flex container on a Grid layout:



    If you were dragging the same components on a page that uses the Block layout, your view might be something like this:
    Description of page-designer-components-blocklayout.png follows
    Description of the illustration page-designer-components-blocklayout.png

    Notice how the components in the Structure view aren't automatically enclosed in rows.

  2. Select the component and modify its properties in the Properties pane. You can select components on the canvas or in the Structure view.
You can drag additional components into the container, or place them above or below an existing row to create new rows.

Add Components to Pages

You build pages in the Designer by dragging components from the Components palette and positioning them on the canvas. After you position a component on the canvas, you use the Properties pane to edit its properties.

About Page Components

You use page components to build the layout of your pages and to add elements that can be used to display content or accept input from a user.

The elements in the Components palette are organized by type. For each type, there are some rules that determine where they can be used on the canvas, as well as the types of pages where they can be placed. An error message is displayed when you try to place a component on the canvas where the component is not allowed.

The following table describes the types of components in the palette and provides some rules governing their placement.

Component Type Description

Common

The components in the Common category are basic page elements for displaying content and providing navigation. You can use these components for many uses, including to display static content or values from variables, and trigger action chains.

Field

The components in the Field category are used for building forms, for example, a page for editing a business object. Field elements must be associated with a business object and positioned within a form page. When you add a field to a form you can choose to create a new field in the associated business object or you can reference an existing field in the business object.

Collection

The components in the Collection category are used to displaying data from business objects, for example, a table with a row for each business object. To display data in a collection component you need to bind the collection to an endpoint.

Layout

The components in the Layout category are containers for organizing elements on the page, for example, to create panels and to align components. Layout components can be placed on any type of page.

Chart

The components in the Chart category are used to generate charts that visually represent business object data. Charts can be added to any page. When you add a chart to a page, you select the business object that you want the chart to represent. You can choose any of your business objects. The charts are independent of the business object associated with a page.

Gauge

The components in the Gauge category are used to add a visual representation of a single value in a business object. You can add a gauge to any page. Gauge components can be interactive and can be used in an Edit or Create page to update the data for a field.

Picker

The components in the Picker category are used to add UI elements that can be used to select dates, times and for choosing colors.

Custom

The Custom category contains web components that you have imported into your application. When you drag the component onto the canvas, you can use the Properties pane to specify the component’s properties. Web components might have properties that are specific to the component.

If your instance is associated with the Component Exchange, you can locate components in the exchange and add them to the palette.

Use the Properties pane to configure properties when a component is selected. Component properties are organized in tabs in the Properties pane. The properties depend on the type of component.

Component Properties Description
General

The General tab is used to edit the most important properties of the selected component, such as layout properties. The properties vary according to the component.

Data

The Data tab is used to edit the properties which are expected to be bound to data. The General tab and All tab also contain properties that can be bound to variables and expressions.

Events

The Events tab is used to bind a component’s events to trigger action chains

All

The All tab is used to edit more advanced component properties.

Quick Starts

The Quick Starts tab displays a list of Quick Start wizards available for the component.

Add a Component From the Components Palette

You add a component to a page by dragging it from the Components palette and dropping it onto the canvas or into the Structure view.

The Components palette in the Page Designer contains many of the Oracle JET components that you can add to your page. After adding a component, you can define the component’s behavior by editing its properties. The properties will vary according to the type of component.

To add a component from the Components palette:

  1. Open the page in the Page Designer and confirm you are in Design mode.

    In Design mode, the window contains a canvas displaying the page’s layout, a Components palette containing a list of components, and a Structure view that displays a structural view of the page’s components.

  2. Drag the component from the Components palette and drop it into position on the canvas or in the Structure view.

After you add the component to the page, the component name and properties are added to the page’s HTML file. You can edit its properties in the Properties pane when the component is selected, or in the HTML file in Code mode. It is sometimes easier to locate, select, and position components in the Structure view.

You can define the component's behavior (for example, to open a URL when a button is clicked) by adding events to the component, then selecting action chains that are triggered by the event. See Start an Action Chain From a Component.

Add a Component Using Code Completion in the Code Editor

For components not contained in the palette, you can open the page in Code view and use code completion to select an Oracle JET component and define its properties.

Use Code view in the Page Designer to edit the page’s HTML source and add the component to your page. The code editor provides code completion that can help you locate JET components and view details about each component’s properties.

To add a component to a page in the Code editor:

  1. Open the page in the Page Designer.
  2. Click Code to open the page in the code editor.
  3. Insert your cursor in the code where you want to add the component.
  4. Start typing the tag for the component you want to add and use the editor’s code completion to help you add the tag for the component.

    For example, when you start typing <oj in the editor, the code completion window appears with a list of component tags that match the text you type:


    Description of page-designer-component-add-codemode.png follows
    Description of the illustration page-designer-component-add-codemode.png
  5. Select the component in the list. Press Enter on your keyboard to add the tag.
Once the component tag is added to the HTML code, you can define its properties using code completion in the editor or using the Properties pane.

Manage Component Visibility Using Conditions

You can use an oj-bind-if component to conditionally show or hide UI components in your visual application. Use oj-bind-if to surround other components and set conditions to determine whether the components should be displayed on a page.

Let's say you have a form for users to submit expense reports with fields like Country and Amount (in US currency). When users from countries other than the United States submit expenses, we want to show additional fields like Exchange Rate and Amount in USD. In other words, we want these fields to show only when the country selected is not United States. You can do this by surrounding these fields in an oj-bind-if component (available as If in the Components palette).

When you add an oj-bind-if component, you also set the conditions under which the component should be displayed by entering an expression in its Test property in the Properties pane. For example, you can use an expression that evaluates if the value of a page variable does not equal a predefined value. The surrounded content is displayed if the values are not equal (the expression is true), and hidden if the values are equal.

In our example, we’ll build an expression using variables to show the surrounded content when the value selected for Country is something other than United States and to hide these fields when the selected Country is United States.

You can also use oj-bind-if to dynamically control what components a user sees based on the user's role, for example, to hide buttons or navigational elements, by using $application.user.roles.role_name in the expression. You can set restrictions on entire pages, or just on certain components in a page. The visibility of components based on roles is only enforced on the client, and the value of the role could be changed in the client. For this reason, in addition to hiding components, you should also use role-based security to secure the application and the data in a page.

To use an oj-bind-if component to control when a component is displayed in a page:

  1. In Design mode, locate the component that you want to control dynamically.
  2. Right-click the component on the canvas or in the Structure view and select Surround > If in the popup menu. In our example, we’ll select the two oj-input-number components for the Exchange Rate and Amount in USD fields that we want to control dynamically.


    In the Structure view, you'll see the components that are surrounded by a Bind If component. (In Code mode, you'll see oj-bind-if.)
    Description of page-designer-pagestructure-bind.png follows
    Description of the illustration page-designer-pagestructure-bind.png

  3. Select the Bind If component on the canvas or in the Structure view and open the Properties pane.

    You’ll see the Test property which you use to set the condition. The default expression is [[True]].



  4. Enter the condition that controls the component’s visibility. You can enter the condition in the Test field, or use the Expression Editor to build an expression using available variables, as shown here:


    In our example where the country variable is of type number, the above expression is used to hide the Exchange Rate and Amount in USD fields when the Country field's value is United States. If you want those fields to be hidden even when the Country field is empty, you can extend your expression as follows:
    [[ $variables.expenseReport.country !== 1 &&
        $variables.expenseReport.country]]

    If the variable type is not a number, remember to use quotation marks (' ') around the value in the Expression Editor.

  5. Optional: In the Properties pane, use the Temporary Override property to temporarily set the result of the test condition to True or False. For example, when designing your page, if some content is hidden on the canvas because the test condition result is False, you can set Temporary Override to True so the content is visible on the canvas, or select Off to temporarily disable the test. This setting is temporary and will revert to Off when you reload the page.

    You can set the Temporary Override in the Properties pane or in the component's popup menu in the Structure view or on the canvas.

  6. Test your application in Live mode. Here’s what our example form looks like with dynamic UI controls enabled:

    Example

Add Dynamic Components to Pages

You can add dynamic components, such as a table, form, or container, to your visual application's pages to define rules that control what's displayed at runtime to the user. Dynamic components help to show different fields in an UI based on conditions in a rule. For example, you might configure a dynamic table so that certain columns are hidden and others are added when the user viewing the page is a manager. Or show a particular layout only when users viewing the page are on a tablet-sized screen or larger.

Note:

Dynamic components (oj-dynamic-*) and the If component (oj-bind-if) both use conditions to determine what's displayed on a page. While you can use oj-bind-if with JavaScript functions to do this, dynamic components provide a more declarative approach, making it easy for you to create dynamic UIs and to maintain and modify them after they've been created.
What are Dynamic Components?

A dynamic component, such as a form or table, does not render static content. Instead, it uses rule sets with display logic to determine what fields should be displayed on the UI. Display logic is simply a set of conditions that you define. At runtime, the conditions are evaluated based on the viewer’s current circumstances (for example, the user's role) or the current data context (for example, the value of a field) to determine what is displayed.

You have two main objectives when creating UIs using dynamic components: one, to configure the component's content the way you want it using layouts and templates, and two, to define the display logic that determines the layout and templates displayed in the component. In most cases you define the logic first, then configure the content that will be used in your logic.

There are three types of dynamic components that can be used in visual applications: tables, forms, and containers. What is displayed in a component and how you customize it depends on what type of component it is:

Dynamic Component Description
Dynamic table, dynamic form In dynamic tables and forms, you customize which fields are displayed and how they are rendered. In most cases, you can hide, show, or re-order these fields, and can even create new fields based on existing ones. You can also apply field templates to control how certain fields are rendered at runtime.
Dynamic container Dynamic containers are predefined areas in a page that can be used to display various types of content. Unlike a dynamic table or form, which can appear on multiple pages, a dynamic container is scoped to the page and can only ever appear on that page.
How to Create Dynamic UIs With Dynamic Components

Dynamic components provide a declarative way for you to bind a component's content to fields from your data sources. They serve as the building blocks for UIs that dynamically change what content is shown and how it is presented based on rules that you define.

Before you can get started with dynamic UIs, you'll need to install dynamic components from your Visual Builder instance's Component Exchange, as described in Get Components From the Component Exchange. Once installed, the component becomes available to you in the Components palette under Dynamic Components. You'll also see a new Dynamic UIs tab (Dynamic UIs icon) in the Navigator.
Description of dynamic-components-installed.png follows
Description of the illustration dynamic-components-installed.png

You have the option of creating a dynamic UI from scratch on the Dynamic UIs tab, where you choose the data source for your dynamic UI, create a rule set with your own layouts and display logic, then associate the rule set with a dynamic form or table. It's simpler though to start by adding a dynamic form or table to a page, then using quick starts to walk you through the basics.

Because a dynamic UI represents a set of data fields that can appear in one or more related dynamic components, you'll need to have your component's data source ready before you can work with dynamic UIs. Your data source can be a business object that stores your app's data or a service connection that receives data from REST APIs.

Here are the high-level steps you need to take to create a simple dynamic UI using a dynamic form or table:
To perform this action: See this:
1. Add a dynamic form or table to a visual application's page
2. Configure the rule set's display logic and layouts.

For each dynamic component, you usually have a default rule and an accompanying layout that displays if none of the conditions you've defined are met. This default set is created for you when you configure a dynamic component on a page using a Quick Start (or, when you create a rule set on the Dynamic UIs' Rule Sets tab). You can then add additional rules (with matching layouts) to cover other scenarios.

Besides layouts that control what's displayed on a page, you can control how something's displayed by using templates to visually design the field's area in a dynamic form or table. You can also set fields to be read-only for specific users and updatable for others.

In addition to rule sets, fields, and templates, the Dynamic UIs tab provides access to variables, actions, events, and event listeners, much like what's available when you add standard components to a page:
Description of dynamicui-editors.png follows
Description of the illustration dynamicui-editors.png

You can use these dynamic component editors just as you would use the editors for standard components, for example, to define events that you can hook action chains to.

Add a Dynamic Table to a Page

Add a dynamic table component to your application's page when you want to display data in a table and use conditions to determine what's displayed to your users. Once you add a dynamic table to a page, you can use the Quick Start to create a rule set that you can configure with your own layouts and display logic.

Before you begin:

To add a dynamic table component to a page:

  1. With your page open in the Page Designer, drag the JET Dynamic Table from the Components palette onto your canvas.
  2. Click the Configure Dynamic UI Quick Start in the Properties pane.
  3. In the wizard's Locate Data page, select the data source to bind to the dynamic component. Click Next.

    This example uses the Employee business object as the data source:



  4. In the Select Rule Set page, click + New Rule Set to associate the dynamic table with a rule set.

    Let's say you want to show one layout with some employee fields (for example, salary) when the user is a manager, and another layout (without the Salary field) for all other users. To do this, you'd start by creating a rule set (labeled RoleBasedTable for example), then select the fields you want to show by default for all users. This set of fields will be added to your initial layout (labeled default).

    The Fields palette lists all the fields and objects you can add to your layout. You can add a field or object by selecting its check box in the Fields palette or by dragging it from the palette onto the drop target area on the right. The columns appear in the order selected; use the handles to the left of each field if you want to re-order them. You can also remove a field by clicking its Delete icon, as shown here:



    When you are done, click Next.

  5. To limit the number of records returned, define a query on the Define Query page, then click Finish.

The dynamic table is created to use the layout with the fields you selected. You'll also see the newly created rule set under the General tab in the table's Properties pane.
Description of dynamic-components-table-pi.png follows
Description of the illustration dynamic-components-table-pi.png

You can configure the dynamic table's properties much like you would a standard table. For example, you can enable a single table row to be selected and set up an event that triggers an action chain to fetch the data of the selected row.

Click Go to Rule Set to open the rule set in the Dynamic UI's Rule Sets tab and configure it with your own display logic and layouts. For example, you might configure the display logic to show the default layout when the user has the Employee role. You could then add another rule to show a different layout when the user has the Manager role. See Add Display Logic to Determine What's Displayed at Runtime.

Add a Dynamic Form to a Page

Add a dynamic form component to your application's page when you want to display data in a form and use conditions to determine what's displayed to your users. Once you add a dynamic form to a page, you can use Quick Starts to create a rule set that you can configure with your own layouts and display logic.

Before you begin:

To add a dynamic form component to a page:

  1. With your page open in the Page Designer, drag the JET Dynamic Form from the Components palette onto your canvas.
  2. Select the Quick Start you want to use for the dynamic form in the Properties pane.
    • Click Configure as Create Form to create a form that interacts with the CREATE endpoint to create a new field in the data source.
    • Click Configure as Edit Form to create a form that interacts with the GET and UPDATE endpoints to edit a field's details in the data source.
    • Click Configure as Detail Form to create a form that interacts with the GET ONE endpoint to view details of a selected field.

    If you plan to the use the Configure as Edit Form and Configure as Detail Form quick starts, you'll be prompted to provide endpoint parameters to be able to fetch and update a specific record. Make sure you create variables that you can map to these parameters before you use the quick start.

  3. Follow the quick start prompts to associate the dynamic form with a data source and a rule set. Depending on the quick start you selected, you might have additional steps to complete.

    This example shows the Configure as Detail Form quick start with fields selected from an Employee business object. These fields are added to the form's default layout. The form is also configured to fetch the data of a particular row in the form.
    Description of dynamic-components-form-1.png follows
    Description of the illustration dynamic-components-form-1.png

    Click Finish when you are done.

The dynamic form is created with the fields you selected. You'll also see the newly created rule set under the General tab in the Properties pane.
Description of dynamic-components-form-pi.png follows
Description of the illustration dynamic-components-form-pi.png

Click Go to Rule Set to open the rule set in the Dynamic UI's Rule Sets tab. From here, you can configure your form's display logic and layouts; for example to show employee data to authenticated users viewing the page on a tablet-sized screen or larger.

Add Display Logic to Determine What's Displayed at Runtime

You control what’s displayed at runtime on a page through the use of display logic, which you configure on the Dynamic UI's Rule Sets tab.

Suppose you want to show employee data (say, an employee's salary) only when the user viewing the page is a manager. You'd then create a dynamic table or form and associate it with a rule set that checks the user's role. If the user has the Manager role, the page shows the layout that includes the Salary field. All other users would see the page with the default layout.

You can have more than one rule for a given component, and the rules are listed in a display logic tree when you select the dynamic form or table in the Rule Sets tab. The order in which they appear in the display logic tree is important because at runtime the rules are evaluated from top to bottom. The first rule where all the conditions are met—in this case, the user is a manager—is the one that's used, and the associated layout is applied to the component. No other rules are tested. Keep this in mind as you’re working in the Rule Sets tab.

To configure the display logic for a dynamic component:

  1. From a dynamic table or form's Properties pane, click Go to Rule Set to open the component's rule set in the Dynamic UI's Rule Sets tab.
  2. In the Rule Set editor, create a rule by clicking + Rule to and giving it a name.

    The rule set for a dynamic component always contains a default rule. You can choose to edit it, copy it and use it as the basis for your own rules, or you can create a rule from scratch.

    Tip:

    It's helpful to give your rules meaningful names. For example, to show a particular layout only when the user is in Canada, you might call the rule inCanada. To edit a rule's name, hover near the name, then click Edit icon, and click Save iconwhen you are done.
    1. In your new or default rule, click Click to add condition.
    2. Select an Attribute and Operator from the drop-down lists, and select or enter a Value.

      The Attributes drop-down list contains the fields and variables that you can use in your layout, and the Operators list contains the operators (for example, '=' and '<=') that are valid for the attribute you select. The Values list contains values already defined for the attribute (for example, 'true' and 'false'), if any, but you can also enter your own value.

      You can select built-in variables that refer to the context the component is rendered in. For example, you can check the size of the device accessing your app, or information about the user using the app such as their role or email. Two types of built-in context variables are available:
      • user variables determined by the current user. For example, the user.isAuthenticated variable's value is True if the current user is an authenticated user. Or the user.roles or user.email variables to check the user using the app such as their role or email
      • responsive variables determined by the screen size of the device the visual app is currently displayed on. For example, the responsive.mdUp variable's value is True if the current user is using a device where the screen width is 768 pixels or more, such as a tablet.

      You can also define your own variables for the components' context.

      Here's the condition to check whether the current user has the Employee role:
      Description of dynamic-components-table-condition.png follows
      Description of the illustration dynamic-components-table-condition.png

    3. You can add more conditions and group conditions if you want to use more attributes to make the rule more precise. For example, you may want to use a layout that displays an extra column if the user is in Canada AND has the Employee role. You would then create a rule with two conditions, and select Match All to require that both conditions are true.
    4. Click Done.
    5. In the return field, select the layout you want to apply when the rule is true.

      If you created a copy of a layout when you created the rule, it is selected by default in the return field. You can use the same layout with multiple rules.

  3. Create more rules as required, for example, to display a Manager layout only to authenticated users who have the Manager role:
    1. Click the Duplicate icon (Duplicate icon), then enter a name for the new rule in the Duplicate Rule dialog box.

      To also create a copy of the layout to use as a starting point, make sure that check box is selected. Click Duplicate.

    2. Edit the new rule and define its conditions. To continue our example, you might set the rule to show the Manager layout when the current user's role is Manager and extend it to show only to authenticated users:


      If you click Display code, you can open an editor to see and edit the expression for the rule. For the rule above, you'd see the following expression:
      $user.roles.includes('Manager') && $user.isAuthenticated === true ? 'Manager' : null
    3. Use the Move Up and Move Down buttons to make sure you have the rules in the order you want them evaluated.


      The order and precision of your rules is important. The rules are evaluated from the top down, so the first rule evaluated as true will determine the layout that is used. When configuring the display logic, it's not a problem if there are rules that will never be used or evaluated.

      The default layout is usually the last rule in the display logic tree and is displayed if none of the conditions you've defined are met.

    4. As part of configuring the new rule, click the newly created layout in the Layouts tab (Manager, in our example), then select the fields you want to show when the user is a manager (for example, the fields you included in the default layout plus salary):
  4. Test your application to preview it in different roles (for example, as Employee and Manager). See Activate Role-Based Application Preview.

    Here’s an example of a dynamic table with role-based logic enabled. On the left is what a user with the Employee role sees; on the right is what's shown to a user with the Manager role:
    Description of dynamictable-example.png follows
    Description of the illustration dynamictable-example.png

Responsive App Display Logic Example

The following example shows how to configure display logic for responsive apps. Suppose you want a dynamic component that shows different fields based on the device's screen size, say, small, medium, and large screens. You’d then create a rule that checks the current user's device screen size and applies the layout that contains the desired fields for that screen size.

To illustrate, consider a dynamic form that displays the following employee fields in the default layout: Id, Name, Department, Email, and Hire Date. If the user's device screen is small, you might want the page to show a particular layout (say, the SmallScreen layout) with only the Name and Email fields. If the user's device screen is medium, you might want the page to show another layout (for example, the MediumScreen layout) with the Name, Department, and Email fields. If the user's device screen is large, you might show the default layout.

To configure a rule set for responsive logic:

  1. Update the default rule to show the default layout when the device's screen size is large:
    1. In the Rule Set's Display Logic section, click Click to add condition.
    2. Choose $responsive.lgOnly from the Attributes drop-down list, select === from the Operators list, then remove one of the equal signs, and select true as the Value.
    3. Click Done.
  2. Duplicate the existing rule as required and use it as the basis to create more rules, in our case, the MediumScreen and SmallScreen rules. During this step, you have the option of creating copies of a particular layout which you can then update to show the fields you want when the device screen is small and when it is medium.
    1. Click the Duplicate icon (Duplicate icon), then enter a name for the new rule in the Duplicate Rule dialog box.

      To also create a copy of the layout to use as a starting point, make sure that check box is selected. Click Duplicate.

    2. Edit the new rule and define its conditions. To continue our example, you might use the $responsive.mdOnly attribute to show the MediumScreen layout when the current user's screen size is medium and the $responsive.smOnly attribute to show the SmallScreen layout when the current user's screen size is small.
    3. As part of configuring the new rules, click the newly created layouts in the Layouts tab (MediumScreen and SmallScreen), then select the fields you want to show when the device screen is small (Name and Email) and when it is medium (Name, Department, and Email).
  3. Use the Move Up and Move Down buttons to make sure you have the rules in the order you want them evaluated.
  4. Test your application using different screen sizes in the Page Designer toolbar. For example, use iPhone to test the display logic on a small screen, iPad to test a medium-sized screen's display, and desktop to test a large screen's display.
Create a Layout for a Dynamic Table or Form

A layout defines the fields that are displayed in a dynamic component at runtime. You create and configure the layouts for a component's rule set in the Dynamic UI's Rule Sets tab.

You can create multiple layouts for a single component, but only the layout associated with the rule that is found to be true first is the one applied to the component. For example, you might have three layouts that show different fields in a dynamic form based on a device's screen size. At runtime, the rules associated with the component are evaluated in the order they appear to see if the conditions set in that rule are met. If the condition is true—say, the current device's screen size is small—then the layout you selected for that rule is applied to the component and the user will only see the fields he needs in the form.

The fields you can display in a layout are determined by the fields available from a Dynamic UI artifact's data source, say, a business object that has five fields. You can choose which of these five fields that you want to display in the dynamic component—and the order in which they should appear—but you can't include fields from other data sources.

To create a new layout:

  1. When your page is open in the Page Designer, click the dynamic form or table you want to work with in the canvas area, or select it in the Properties pane.
  2. Click Go to Rule Set in the Properties pane for the dynamic form or table:
  3. Click Layout iconin the rule set's Layouts pane, then enter a name for the new layout.


    To illustrate, consider a dynamic form that's set up to show employee data displays the following fields in the default layout: Id, Name, Department, Email, and Hire Date. Now, say we want the form to show data based on screen size. To do this, we'll create three different layouts:
    • A SmallScreen layout configured to show Name and Email
    • A MediumScreen layout configured to show Name, Department, and Email
    • A LargeScreen layout configured to show Name, Department, Email, and Hire Date.
  4. Click the new layout name to open the layout editor.
  5. Add fields from the Fields palette to the layout.

    The Fields palette lists all the fields and objects you can add to your layout. You can add a field or object by selecting its check box in the Fields palette or by dragging it from the palette onto the drop target area on the right. The columns appear in the order selected; use the handles to the left of each field if you want to re-order them. You can also remove a field by clicking its Delete icon.

    For example, here's what our SmallScreen layout looks like:
    Description of layouts_smallscreen.png follows
    Description of the illustration layouts_smallscreen.png

  6. Return to the component's rule set and repeat the steps as required to create additional layouts, in our case, the MediumScreen and LargeScreen layouts.

After a layout is created, you can include it in a display logic rule. You can use the same layout in multiple rule sets.

Use Field and Form Templates

You can customize how a dynamic component is rendered on the page by editing layouts to group fields together and to apply templates to the layout and fields.

Control How a Field is Rendered with Field Templates

You can customize how a field is rendered in a layout for a dynamic form or table by applying a field template. A field template contains UI components, for example, text fields or images, and defines their properties, such as styling details. Components in a template can access the variables, constants, action chains, and event listeners defined in the dynamic UI.

You might define a default template for a field, which is then applied to the field in every layout. You can override the default template if you want to apply your own template. Suppose the visual app has applied a template called BoldType to the Update field. The Update field will have the BoldType template applied in every layout where it appears. However, you can create a field template called Italics and override the BoldType template, either in specific layouts or across all the layouts that you create. You can apply your Italics template to multiple fields, as long as they are part of the same dynamic UI.

To create a field template for a field in a dynamic form or table:

  1. Open the dynamic UI's Templates tab.

    The Templates tab displays a list of field and form templates that are already defined for the artifact.

  2. Click + Template. Select Field, specify the Label (the ID is generated for you), and click Create.


    The new field template opens in the template editor, which contains a Components palette, Structure view, canvas, and a Properties pane.
    Description of template-field-editor.png follows
    Description of the illustration template-field-editor.png

    If you were to click the Structure view, you'll see that your new field template has an Input Text component that is generated automatically. This is used to display the data and display name when you apply the template to a field in the layout.
    Description of template-field-inputtext.png follows
    Description of the illustration template-field-inputtext.png

  3. In the Templates editor, add any other UI components you want to display in the template by dragging them from the Components palette onto the canvas or the Structure view.

    You can add more UI components above or below the Input Text component, or replace the Input Text component with a different one, for example, to render a field using a Rating Gauge component instead of an Input Text component.

    In this image, you can see in the Structure view that the template contains an Icon component and an Input Text component:
    Description of template-field-adduicomps.png follows
    Description of the illustration template-field-adduicomps.png

  4. Select a component on the canvas or in the Structure view, then edit its properties in the Properties pane.

    Just like when you are working in the Page Designer, the Properties pane might contain several tabs for editing the component's properties. For example, if you added an icon component to your template, you might decide to also create an event in the Events tab. If you did this, an event listener and action chain would be created for you, and you would then need to edit the action chain to define the behavior.

    Alternatively, you can edit the field template's code directly in the Code editor, and use the editor's code completion to help you. For example:
    <!-- Contains Dynamic UI layout templates -->
    <template id="emailTemplate">
      <span class="vb-icon vb-icon-envelope"></span>
      <oj-input-text value="{{ $value }}" label-hint="[[ $metadata.labelHint ]]"></oj-input-text>
    </template>

After you've created the template, click < Templates to view your template added to the list of field templates in the Templates tab. From here, you can open and duplicate the templates you've created.

Apply a Template to a Field

Once you've defined a field template, you can apply it to a field in a dynamic form or table's layout, making it the default template applied to that field in every layout in that rule set.

To apply a template to a field in a layout:

  1. In the rule set editor, click the name of the layout name you want to work on.

    The center pane of the layout editor lists the fields that will be displayed in the layout and any templates that are applied to them (as shown in the image for the phoneNumber field). If you duplicated an existing layout, your new layout might already list some fields, or have templates already applied to fields.
    Description of template-field-apply.png follows
    Description of the illustration template-field-apply.png

  2. Select the field you want to apply a template to.
  3. In the field's Properties pane, select a template from the Template drop-down list.

    If no template has been applied to the field, you can select a template in the list (as in this image):
    Description of template-field-apply-template.png follows
    Description of the illustration template-field-apply-template.png

    If the field already has a field template applied to it (you'll see the template name next to the field name), you'll see a notification in the Properties pane that a default template has been defined for the field:
    Description of template-field-default.png follows
    Description of the illustration template-field-default.png

    If you want to change the field's template only in the current layout, click Override in the Properties pane, then select another template from the drop-down list. Or, click Create to define a new template.Description of template-field-default-override.png follows
    Description of the illustration template-field-default-override.png

    If you want the changed template applied to the field in every layout in the rule set, click Set as rule set default in the Properties pane. You can click Reset at any time to re-apply the default template.

Start an Action Chain from a Field

You can start an action chain when an event occurs in a field by adding a component event to the field in a field template.

For example, you might want to display some additional details or options when someone changes the value in one of your form fields. You can add an event that's triggered when the value changes, and start an action chain that retrieves the data and displays it in your page. The Quick Start option in the component's Properties pane can help you quickly create the event, event listener, and action chain. You can also use the event to start action chains that are already defined in the dynamic UI.

When creating an action chain, you can use variables and constants defined in your dynamic UI, and create new ones if you need them.

To start an action chain from a field:

  1. Open the Templates editor of your Dynamic UI and click the field template you want to edit.

    The field template opens in the Template editor.

  2. Select the text field, then open the Events tab in the Properties pane.
  3. Click + New Event and select the Quick Start option in the drop-down list.


    The Quick Start defines the event suggested for your component. In the case of a text field, the suggested event is value, which is triggered when the text field's value changes, for example, when someone types in the field. If you don't want to use the suggested event, you can select New Custom Event in the drop-down list and select a different event.

    When you select the Quick Start option:
    • an event is defined for the text field
    • a new action chain is created
    • an event listener is created that will trigger the new action chain when the event occurs
    • you are navigated to the new action chain in the Action Chain editor.
  4. In the Action Chain editor, define the action chain's properties in the Properties pane. You can edit the default ID, add a description, and configure the action chain's input parameters and return type.
  5. Create the action chain by adding actions from the palette. Depending on the actions you add, you might also need to create variables used in the action chain or layout and define other properties for the actions.

If you navigate back to the template editor, you'll see the event details in the field's Events tab in the Properties pane. You can add more action chains that will be triggered by the same event, or you can add different events to the same component.
Description of template-field-addevent-result.png follows
Description of the illustration template-field-addevent-result.png

Control How a Form Layout is Rendered

You can apply a form template to layouts to control how it's rendered, including which fields you want the layout to contain and how they are displayed in the layout.

For example, you might have a page that uses a dynamic form (not table) to display a detail view that includes sales figures, and you want the form to always display a Rating Gauge component, regardless of which fields are defined in the layout. You could create a 'Sales' form template that includes the Rating Gauge component, and then apply the template to the form. You can re-use the template in multiple form layouts in the same dynamic UI, but templates can't be shared between dynamic UIs.

To create a form template for a dynamic form:

  1. Open the dynamic UI's Templates tab.

    The Templates tab displays a list of field and form templates that are already defined for the artifact.

  2. Click + Template. Select Form, specify the Label (the ID is generated for you), and click Create.


    The form template opens in the template editor, which contains a Components palette, Structure view, canvas, and a Properties pane.

    In this image, you can see that the canvas has two read-only template fields that are generated automatically: Additional Fields and Remaining Required Fields. These fields are used to display the data and display names for the fields defined in the layout. These template fields render all the fields in the layout, so you don't need to modify the template each time you change a layout.
    Description of template-form-editor.png follows
    Description of the illustration template-form-editor.png

  3. While Form Template is selected in the editor, click Add item in the Extra section in the Properties pane. Extra fields are those defined in the template, not in the layout. Each field you add in the Extra section is displayed in the form when the template is applied, and can't be removed in the layout.

    Each Extra field must be mapped to a component to if you want it to appear in the form. This image shows the Properties pane after adding the certifications field to the template as an Extra.
    Description of template-form-extra.png follows
    Description of the illustration template-form-extra.png

  4. Drag the component you want to add from the Components palette and position it in the Structure view or on the canvas.


    You can add components above and below the read-only template fields, but not within them. In the Structure view of this template, you can see an Input Text component that was positioned above the Additional Fields template in the Form Layout.
    Description of template-form-component-structureview.png follows
    Description of the illustration template-form-component-structureview.png

  5. While the component is selected on the canvas or in the Structure view, open the component's Data tab in the Properties pane and bind the component to the Extra reference field.

    To help you select the reference field, you can click fx iconto open the Expression Editor, or Select Variable to open the Variables picker.
    Description of template-form-component-bind.png follows
    Description of the illustration template-form-component-bind.png

After you've added the components and fields to your form template, you can apply the template when you edit a layout in the Rule Sets editor.

Apply a Template to a Form
To apply a form template to a dynamic form:
  1. In the rule set editor, click the name of the layout name you want to work on.
  2. While the form is selected, select the template you want to apply in the Form Template drop-down list in the Properties pane. Or click Create to create a new form template.

When a template is applied to a form layout, the template name and the fields defined in the template are displayed above the list of fields in the layout. In this image of the layout editor, you can see the header displays the name of the template applied to the form layout (Certification Template) and the fields defined by the template (certifications).
Description of template-form-result.png follows
Description of the illustration template-form-result.png

If the template contains a field you don't want to appear in your form, you'll need to select a different template, or choose None from the Form Template drop-down list to remove the template.

Add and Group Fields in Dynamic Form Layouts

When creating a layout for a dynamic form, you can group the form's fields so that they are displayed together as a single entity in the layout.

For example, you might create an address group that contains the name, address, city, state, country, and postal code fields. You can then apply conditions to the group that control when the group is displayed. A group also makes it easy to add several fields to a different layout in one step, rather than adding them individually.

You can define properties for a group (for example, a group label) and for individual fields in a group (for example, to specify column spans for fields to create complex dynamic form layouts).

To group fields in a dynamic form layout:

  1. Open the Rule Sets tab for the dynamic form you want to work with. You can select a standalone dynamic form or one that's part of a dynamic container.

    To do this, select a dynamic UI in the Navigator's Dynamic UIs tab, then find the dynamic form in the Rule Sets tab (as shown here); click the form on a rendered page in the canvas area; or select the form from the Properties pane.
    Description of employee-ruleset-standalone.png follows
    Description of the illustration employee-ruleset-standalone.png

  2. Open the form you want to edit.

    Use the Duplicate icon icon in the toolbar if you want to duplicate the current layout.

  3. In the layout diagram, select the fields that you want to group together, either by holding down the CMD key (on macOS) or the Ctrl key (on Windows).
  4. Click Group Fields in the Properties pane, or Group Fields icon in the toolbar.


    The selected fields are grouped under a new folder in the layout diagram:
    Description of group_fields_name.png follows
    Description of the illustration group_fields_name.png

  5. Enter a name for the new group. Click Check mark icon to save the group name.
  6. Optionally, use the Properties pane to set properties for the group. You might even click the Always link to set conditions that determine when the group is displayed in a layout. The default setting is to always display the group.

After a group is created, you can still use the handles for fields to drag them into and out of a group.

Edit a Field's Properties

When you edit a field's properties in a layout, your changes only apply to the field in the current layout. You might want to do this to override a field's properties in a specific layout, for example, to mark a field as Read Only.

If you want to edit a property so that it's the same in all layouts—for example, if you want it to be Read Only always— you should edit the field's properties in the Fields tab. The Required property applies to all layouts and can only be set from the Fields tab.

Set a Field to be Read Only

You can set a field to be Read Only when you don't want its value to be changed by everybody. For example, you might want only managers to be able to change an employee's hire date. You would then set the field to be Read Only in all layouts, except the one seen by managers.

The Read Only property might not be editable if you select a field that has a template applied to it. In this case, you might need to remove the template if you want to edit the property in the layout.

To edit a field's Read Only property in a layout:

  1. In the Rule Set editor, open the layout and select the field in the center pane.
  2. Edit the field's Read Only property in the Properties pane.


    If the field's Read Only property was set in the Fields editor to apply to all layouts, you would see a warning as shown here when you try to edit the property in a particular layout:
    Description of readonly-override.png follows
    Description of the illustration readonly-override.png

Use Conditions to Show or Hide Fields in a Layout

Fields in the active layout are displayed by default, but if you want to hide a field or group in a layout in some cases, for example, to hide it from everyone except managers, you can use the field's Show Field property to set conditions that determine when it is displayed. When you add conditions, the field is displayed only when the conditions you set are true. The conditions are only applied to the field in the layout you are editing.

To set display settings for a field in a layout:

  1. In the Rule Set editor, open the layout and select the field in the center pane.

    When you select the field, you can see the field's properties in the Properties pane. By default, the Show Field property is set to Always, so the field is always displayed.



  2. In the Properties pane, click Always under the Show Field property to open the Edit Show Field Condition dialog box.
  3. Define the field's conditions by selecting attributes, operators, and values in the condition builder in the dialog box. Click Save.

    You can add more conditions and group conditions to make the rule more precise. For example, you may want to display an extra field if the user has the manager role AND is based in Canada. You would then create a rule with two conditions, and select Match All to require that both conditions are true.
    Description of showfield_condition.png follows
    Description of the illustration showfield_condition.png

Add Converters and Validators to a Field

You can add converters and validators to a field, including some built-in ones provided by Oracle JET. You might want to add a convertor to a field to change how the field's data is displayed in your page, for example, to display a date as month, day, and year instead of numerically. You might want to add a validator to a field to check if a value entered in a field is valid, for example, to check if a date is not earlier than the current date.

You can find details and examples in the Oracle JET Developer Cookbook:

To add a converter or validator to a field:

  1. In the Fields tab, select the field you want to work with.
  2. In the Properties pane, click Add next to Converter or Validators, then select one from the list.
  3. Click Add Validator or Add Converter.
  4. In the Options text area, type the options required by the validator or converter.

    The options you'll need to enter will depend on the validators or converters you use, so you might need to consult the samples and documentation for the specific options. For the Length Validator in this screenshot, the options specify how to count the characters and the minimum and maximum string lengths allowed:
    Description of field-validator-example.png follows
    Description of the illustration field-validator-example.png

Add a Dynamic Container to a Page

A dynamic container lets you display content in individual sections, or logical regions of the page based on conditions that are evaluated at runtime. Each section maps to a template, which defines the content displayed within that section.

The display logic for determining what's displayed in a dynamic container is defined using cases. A case is similar to the rule set layouts used in dynamic forms and tables, but instead of selecting which fields to display, you select which UI elements or components to display. When you define a case, you specify the conditions for the case, and the templates you want displayed in the container when that condition is met. The template defines the content you want to display. Each template in a case is rendered as a section in the container, so if a case defined two templates, you’d see two sections in the container.

The easiest way to learn how to configure a dynamic container is to examine a real use case. Let's say you want to create a page that lets users toggle two layouts, one showing employee data in a form and another in a table. To do this, you'd create a dynamic container with two templates: one for a dynamic form and another for a dynamic table. You'd then add a button that the user can click to toggle the templates in the dynamic container.

Before you begin:

To add a dynamic container component to a page:

  1. With your page open in the Page Designer, drag the JET Dynamic Container from the Components palette onto your canvas.
  2. Create templates for the dynamic container. In our example, we'll create two templates, one for a dynamic form and another for a dynamic table.
    1. Click the Templates tab in the Properties pane, then click + Template to create a new template.
    2. In the Create Template dialog box, give the template a name (for example, DynamicFormTemplate) and select <Any Rule Set> in the Rule Set drop-down list. Click Create.

      If you select a rule set in the dialog box, you can use the new template only in the container that uses that rule set. Select <Any Rule Set> if you want to use the template in any container in the page.
      Description of dynamic-container-template.png follows
      Description of the illustration dynamic-container-template.png

    3. When the new template opens in the template designer, drag the JET Dynamic Form from the Components palette onto the template in your canvas.
    4. Select the Quick Start you want to use for the dynamic form in the Properties pane, then follow the prompts to associate the form with a data source and a rule set. When you are done, click Finish.

      You won't actually see your newly created dynamic form in the template. That's because the template isn't bound to a data source, so the form doesn't have any data to render on the page. But you can use the Structure view to see the dynamic form component.

    5. From the templates drop-down list, select Create Template to create more templates; in our case, a template for a dynamic table.
    6. In the Create Template dialog box, give the template a name (for example, DynamicTableTemplate) and select <Any Rule Set> in the Rule Set drop-down list. Click Create.
    7. Drag the JET Dynamic Table from the Components palette onto the template.
    8. Click the Configure Dynamic UI in the Properties pane and follow the wizard to complete the setup. When you are done, click Finish.

      Again, because a template isn't bound to a data source, your dynamic table won't have any data to actually render on the page. But you can use the Structure view to see the dynamic table component.

    9. After you've created the templates, click Return to page to go to the Page Designer.
  3. Set up the UI component and add the case logic to display your templates. Here, we'll add a Button component and a page variable to toggle the templates in the dynamic container.
    1. In the Variables tab, create a variable that you can use in your conditions. For example, a Boolean-type variable called layoutFlag, with the default value set to true.
    2. In the Page Designer tab, drag a Button component from the Components palette and drop it just above the dynamic container.
    3. In the Button's Events tab, add an ojAction event for the Button component.
    4. Set the name of the new action chain as Toggle Layout, then add the following actions:
      • An If action, with its Condition set to [[ $page.variables.layoutFlag == true ]] in the Properties pane.
      • In the true branch, add an Assign Variables action and assign the Target value of the layoutFlag variable to false.
      • In the false branch, add an Assign Variables action and assign the Target value of the layoutFlag variable to true.


    5. In the Page Designer tab, click Return to Page and select the Dynamic Container component to view its properties in the Properties pane.
    6. In the container's General tab, click + next to Display Templates and select the templates you want to display (DynamicFormTemplate and DynamicTableTemplate in our example):
    7. Click + Case to create another display logic condition, called Case 2. You can use Edit icon to update the name as required.
    8. Click + next to Display Templates and select the DynamicTableTemplate and DynamicFormTemplate (in that order).
    9. In the Condition field for case1, click Expression Editor icon to open the Expression Editor and enter $variables.layoutFlag == true as the expression. In the Condition field for case2, enter $variables.layoutFlag == false:
  4. Preview how the different templates in your dynamic container will look using Layout Preview. Layout Preview forces the Page Designer to use the condition you've defined for testing purposes.
    1. Click the Preview Layout iconicon for a case in the Display Logic section:
    2. Click Reset Override (or Preview Layout iconagain) to remove the preview.
Re-Order a Dynamic Container's Content

Besides defining new cases and templates for a container, you can also change the order the templates are displayed in the container. Just use the Move Up and Move Down arrows in the Display Templates section for a case:



You can also use the Remove item icon to remove a template from a case. Once removed from a particular case, the template is still available to use in other cases for dynamic containers in the page.

Guidelines for Working with Display Templates

Here are some things to keep in mind while working with display templates:

  • A section created by a template is the full width of the container. That is, while you can't have two templates side-by-side, the container can stretch to any height required to accommodate all the templates you define.
  • In addition to simple components like text fields and images, you can also add more complex components to your display templates. For example, you might include fields for displaying data from a service, or a button that starts an action chain in your visual app.
  • A template can be used in any container in a page if you select <Any Rule Set> when you create the template. To limit a template to a specific container, select the container's rule set when you create the template.
  • Components in a display template can access variables and constants, and trigger events to start action chains.
  • When working with templates, sometimes it’s easier to work in the Structure view, which helps you more readily visualize the position of components. You can also drag components within the Structure view to reorganize them.
Create Custom Fields

If you'd like to use a field in your layout that isn't defined in your data source (either a business object or a service definition), you can create custom fields that you can set to variables, or to expressions that reference other fields.

If the existing fields don't meet your needs, you could create calculated fields or virtual fields. You would use a calculated field when you want to use an expression, set a default value, modify labels, and set read-only and required properties. You would use a virtual field if you want a field that has editable sub-fields.

Custom fields are only used in your layouts; creating a custom field doesn't create a field in your business object or change the service definition.

Create a Custom Calculated Field

You can use a calculated field when you want to have a single field in your layout that, for example, contains some static string or an expression that is computed from the values of other referenced fields or objects.

Suppose your data source has separate fields for a user's first name and last name. You could create a custom field that combines these fields into a single field called fullName and use that in your layouts instead. The value of this new field is calculated using an expression like [[ 'Name: ' + $fields.firstName.value() + $fields.lastName.value() ]]. In a calculated field, referenced fields defined in the expression are read-only, so they can't be edited in a layout.

To create a calculated field:

  1. Open the dynamic table or form you want to work with in the Dynamic UIs tab.
  2. Click the Fields tab, then + Custom Field.
  3. Enter a label for the field (the field's display name). When you enter the label, a suggested ID is generated for you. The ID can't be changed later.
  4. Select the field type. When selecting a type for a calculated field, you should consider the types of the referenced fields you'll include in the expression.
  5. If you want to create an expression and use an existing field, click Add next to Referenced Fields, then select a field in the list. Click Add Field to add it.
  6. Define an expression in the Value property.

    The expression can include variables, static strings, and referenced fields. If you want to use a single variable, you can click the arrow to open the Variables picker.
    Description of custom_field_variablepicker.png follows
    Description of the illustration custom_field_variablepicker.png

    If you want to use an expression, you can click Expression Editor icon to open the Expression Editor. In the Expression Editor, you can select field variables in the Variables pane to add them to your expression. You can also add text strings to your expression by typing in the editor. Click Save.

    For example, here's an expression that combines the firstName and lastName fields:
    Description of custom_field_fx.png follows
    Description of the illustration custom_field_fx.png

    The expression you create in the editor is added to the Value field, for example:
    [[$fields.firstName.value() + ' ' + $fields.lastName.value()]]
  7. Optionally, you can click Add next to Converter and Validator to add suitable built-in convertors or validators, or create a custom one. If you're using a referenced field, you might want to add converters or validators so that, for example, dates are formatted the way you want, or to make sure a string in a field is not too long.

Your custom fields (and any fields that you have modified, for example, in the Properties pane) are indicated by a gray bar to the left of the field name. In this screenshot, you can see the gray bar next to fullName:
Description of custom_field.png follows
Description of the illustration custom_field.png

Create a Custom Virtual Field

You might want to create a virtual field if you would like to combine multiple fields together into a single field that you can add to your layouts. For example, you can create a single field that combines several contact details stored in different fields in the dynamic UI. A virtual field is similar to a calculated field, except:

  • the referenced fields can be edited in the layout; and
  • the virtual field is rendered using a field template.

When you add a virtual field to a layout, you'll define a field template to display it. You'll need to create the field template if it doesn't exist. The template will contain components for each of the referenced fields that you want to display in the layout.

To create a custom virtual field:

  1. Open the dynamic table or form you want to work with in the Dynamic UIs tab.
  2. Click the Fields tab, then + Custom Field.
  3. Enter a label for the field (the field's display name) and select the Object (Virtual Field) type. Click Create.
  4. In the Properties pane, click Add next to Fields and select the fields you want to include as reference fields. You can add any field in your dynamic UI as a reference field, including sub-fields of objects.
  5. In the Rule Sets tab of your dynamic UI, open the layout in the dynamic component where you want to add your field.
  6. Add the virtual field to the layout. You can drag it from the Fields palette into the center pane, or select it in the list and then adjust its position in the center pane.
  7. While your virtual field is selected, define a field template for the virtual field when you add it to a layout.

    If a suitable field template for the virtual field already exists, you can select it in the Template drop-down list in the Properties pane. If no template exists, click Create and enter a name for the template in the Label field. Click Create to open the new template in the editor.
    Description of custom_field_virtual_template.png follows
    Description of the illustration custom_field_virtual_template.png

  8. In the template editor, add a component and define the properties for each referenced field in the virtual field that you want the template to display.
  9. Click Return to layout when you're finished.

    The new template is applied to your virtual field.

You can add the virtual field to other layouts in the dynamic UI and apply the same field template, or create other field templates that you apply to the virtual field.

Add an Image to a Page

To add an image to a page, you position an image component on the canvas and specify the path to the image in the Properties pane. You can select an existing image in the Image Gallery or import a new image from your local system. Use the tabs in the Properties pane to specify the image’s display properties, the path to the image source, and any component events for triggering action chains.

The images used in pages in your app are stored in an images resource folder. The app contains a default images resource folder, and each flow in your app can also contain an images resource folder. When adding an image to a page, you can use the Image Gallery to select an image that was already imported, or add a new image to the Image Gallery directly from the component’s Data tab in the Properties pane. When you add an image to the Image Gallery, you can choose to import an image as an application resource or a flow resource. If you want to select an image that was already imported into the app, you can click the Image Gallery button in the Data tab and use the Image Gallery dialog box to locate and select the image. When you select images from the Image Gallery, you can select application resources or flow resources.

When you drag an image into the drop target area in the Data tab, the image is imported into the images folder for the flow, and the path to the image location is added to the Source URL field. For example, the path to an image stored in a flow’s images folder will be similar to the following:{{ $flow.path + 'resources/images/myimage.png' }}.

To ensure that the relative path to the image resource is built correctly when the app is staged and published, the path to the image in the Source URL field needs to include the builtin variable $flow.path or $application.path to identify the location of the resource folder. You can use Audits window to help you locate image paths in your app that might not be formed correctly.

To add an image to a page:

  1. Open the page in the Page Designer and drag an image component from the Components palette onto the canvas.
  2. Open the component’s General tab in the Properties pane and specify the height, width and alt text for the image.
  3. Open the component’s Data tab in the Properties pane.

    The Data tab contains a Source URL field that contains the path to the image. You can use a string or a variable to specify the path to the image source.


    Description of page-designer-inspector-newimage.png follows
    Description of the illustration page-designer-inspector-newimage.png
  4. Drag your image into the drop target area in the Data tab.
  5. Open the component’s All tab in the Properties pane to view and edit all of the component’s attributes.

Add an Icon Component to a Page

Visual Builder includes a set of icons that you can add to your pages using the Icon component in the Components palette.

After adding the Icon component to the canvas, you use the Properties pane to select an icon from the Icon Gallery, specify the display properties of the icon and configure any component events for triggering action chains.

To set the display size of the icon, you apply inline CSS styles to the component by specifying values in the component's style field in the Properties pane. To set the size you must explicitly set the width, height and font-size to the same pixel value (for example, width:50px; height:50px; font-size:50px ).

To add an Icon component to a page:

  1. Open the page in the Page Designer and drag an Icon component from the Components palette onto the canvas.
  2. Select the component on the canvas and click the Image button ( Image button ) in the General tab of the Properties pane.
  3. Select the icon in the Icon Gallery window. Click Select.
  4. Specify the size of the icon in the style property in the All tab of the Properties pane.
  5. Specify additional properties or component events in the Properties pane.

Add a Camera Component to a Page

When you want your application to access the camera capabilities of the devices on which it is installed, you can add the camera component to your application’s page for users to take a photo or a video from the device's camera.

The camera capture works only on physical devices that actually support media captures. On other devices (like desktops), it works as a regular file picker that lets users select files from the device's storage.

Note:

You cannot use the camera component if you're deploying a hybrid app to Android. On Android hybrid apps, the camera component works only as a file picker, enabling the user to choose files but not actually take a photo or video. In this case, you can use the Take Photo action in the action chain to take or select photos/videos.
  1. Open the page in the Page Designer and drag the camera component from the Components palette onto the page canvas:
  2. In the General tab of the Properties pane, configure the component's properties for your use case:
    1. Use the Camera capture property to launch the camera on the user's device in a preferred camera mode:
      • To let the user take a selfie photo or video, select Front (Selfie). This option will directly launch the front-facing camera on the user's device.
      • To let the user take a photo or video of their environment, select Rear. This option will directly launch the rear-facing camera on the user's device.
      • To enable the device's default behavior for the preferred camera mode, select Default. This option will directly launch the camera on the user's device in the default camera mode, which on iOS devices (for example) is to open the rear camera.
      • To provide the user with choices, say, choose from the photo library or take a photo or video (instead of directly launching the camera), select None.
    2. Set the Accept property to the file types you want to accept from the device: photos, videos, or both. By default, both Photos and Videos are selected to provide the user with options to take either a photo or a video once the camera is launched.
    3. Optional: The camera component is preconfigured to use a Take Photo/Video button. This button acts both as a clickable control to activate the camera component and as a file drop zone for devices that support drag and drop. You can customize this button or replace it with other trigger components.
      To replace the default Take Photo/Video trigger button, click + for trigger in the Slot section and select an option:

      • To add an Upload button that users click to upload files, select 'Upload' Button.
      • To add a placeholder for an image that users click to upload images, select Image.
      • To create a basic drop zone/trigger that can be further customized with other components, select Custom Drop Zone.

      Remember to delete the original Take Photo/Video trigger button:
      Icon showing the delete icon highlighted for the default Take Photo/Video button

  3. In the Events tab of the Properties pane, configure the camera component's ojSelect event to trigger an action chain when a user selects the camera component. Make sure to select the Camera (File Picker) component, not the button component within the camera component.
    1. Click + New Event, and select Quick Start: 'ojSelect':
      This creates the CameraFilePickerSelectChain action chain, which receives the files taken from the device. You can configure the action chain to upload the files to a server (via user-created JavaScript) or assign it to a variable, as we'll do next.
    2. Drag and drop the Assign Variables action to the + sign under Start on the canvas, then click Assign to assign the file list to a variable:
    3. In the Assign Variables dialog, use an existing variable or create a new variable (for example, the FileArrayADP of type Array Data Provider).

      Note:

      The items in the array are of type File (https://developer.mozilla.org/en-US/docs/Web/API/File). Each file is itself a Blob for the image or video, with properties such as name, size, and type. In Visual Builder, the files are passed to the action chain as an Array of type Object. When assigning to another variable, it is important that the type isn't changed to a custom type; otherwise, Blob data may be lost.
    4. Draw a connection from the files node under Sources to the FileArrayADP node's data property under Target, then click Save:
    5. Click the Page Designer tab to confirm that the array of files taken from the device is mapped to the CameraFilePickerSelectChain action chain:
  4. Click Preview to test the camera functionality.

Filter Data Displayed in a Component

When you bind a component to an endpoint, you can filter the data displayed in the component by defining filter expressions in the Service Data Provider used to retrieve the data. You can use expressions and static content to set the filter criteria values and Oracle JET operators to define the logic.

To display data in a collection component such as a list or table, you usually bind the component to an endpoint using a variable that is assigned the built-in Service Data Provider (SDP) type. This variable is created for you when you use the Add Data Quick Start to bind the component to an endpoint. The SDP type manages requesting and receiving data from an endpoint, and supports a filterCriterion property that can be configured to filter the data stored in the variable and displayed in the component. The filterCriterion structure can be used to express many of the filter expressions you might want to use when retrieving data. For more details, see Service Data Provider.

Note:

For more advanced filtering you can write JavaScript filtering functions that you can call from an action chain. See Work with the JavaScript Editor and Add a Call Function Action.

You build a filter expression by defining the properties of the three filterCriterion attributes (attribute, op, value). The filter expression is converted into an appropriate "q" query string when sent to the endpoint. You can make complex filters by combining multiple filter expressions. You can create a filter expression using the Assign Variables window of an action, or you can edit the JSON file where the action is defined (for example, main-start-page.json). The following table describes the filterCriterion attributes that you define in a filter expression.

Attributes Description

attribute

Name of the attribute. Typically this is the name of the field that the filter will process.

op

Supported Oracle JET operator. Common operators are, for example, $co (The entire operator value must be a substring of the attribute value for a match.), $eq (The attribute and operator values must be identical for a match.) and $ne (The attribute and operator values are not identical.). The operator $regex is not supported.

For a list of Oracle JET operators, see Oracle JavaScript Extension Toolkit (JET) API Reference.

value

Value of the attribute. This is the value that is used to filter the request. This value can be mapped to an expression (for example, a page variable) or a static value (for example, a string or number).

You can define filterCriterion attributes by editing the SDP properties in the Variables editor, or you can build a filter function in the page using variables, components and action chains. For example, you can create a filter for a collection such as a table using filterCriterion and use a page variable to store a string that a user enters in an input field. When the SDP sends a request to the endpoint, the filter processes the request and only the records that meet the filter criteria are returned and displayed.

Create a Filter for Component Data

You filter the data displayed in a component by defining the filterCriterion property used when calling the Service Data Provider to retrieve the data. You can use the Filter Builder to help define the filter criteria values and Oracle JET operators used to define the logic of the filter.

When you use the Add Data Quick Start to bind a collection component to a data source, you can use the Filter Builder in the Define Query step to filter data that you do not need to retrieve. For example, you can build a filter to only retrieve the business objects where the value of a field named "Active" equals "true", or equals some page variable.

To assign a page variable as a filter criterion in an action chain:

  1. Create a page variable (for example, filterVar) to store the filter string.

    The value of the page variable can be predefined (for example, an input parameter), or you can bind it to a page component such as an Input Text or Combobox component to allow users to enter text strings, numbers, or select from a list.


    Description of filter-input-variable.png follows
    Description of the illustration filter-input-variable.png
  2. Create an action chain or open an existing action chain.

    The action chain will use the Assign Variables action to map a page variable to the value attribute in the filter expression. The action chain can be triggered by a component event or a page event.

    Tip:

    To create a filter using an Input Text component, you could use the Quick Start in the component’s Events tab to add a Property Change event to the component. The Quick Start will automatically create a new action chain that is triggered by the event.


    Description of filter-input-event.png follows
    Description of the illustration filter-input-event.png
  3. Add the Assign Variables action to the chain.

    You configure the Assign Variables action to assign values to each of the attributes of the filter expression.
    Description of filter-action-assignvariable.png follows
    Description of the illustration filter-action-assignvariable.png

  4. Click Assign in the action properties pane to open the Assign Variables window.
  5. Expand the Service Data Provider in the Target pane and select filterCriterion to open the Filter Builder.

    The Filter Builder contains a Builder tab where you build expressions with the help of drop-down lists, and a Code tab where you build or edit them in a code editor.



    Alternatively, you can expand the filterCriterion node in the Target pane and build your filter by specifying values for attribute, op, and value individually.

  6. In the Filter Builder, create a condition by specifying the Attribute, Operator, and Value.

    When you create a filter in the Builder tab, you create one or more filter conditions by selecting items in the Attribute, Operator and Value drop-down lists. You can add more conditions to build more complex filters.



    You can use the Code tab to view and edit the filter. After defining a condition in the Builder tab, in the Code tab you will see that it contains an attribute,op and value. For example, your definition of filterCriterion might have two conditions and be similar to the following:

    {
     "op": "$and",
     "criteria": [
      {
       "op": "$eq",
       "attribute": "name",
       "value": "{{ $page.variables.filterVar }}"
      },
      {
       "op": "$eq",
       "attribute": "id",
       "value": "{{ $page.variables.idVar }}"
      }
     ]
    }

    In this example, the value attribute ($page.variables.customerListSDP.filterCriterion.criteria[0].value) is mapped to a page variable expression ($page.variables.filterVar), the Oracle JET operator is "$eq" (it must include the dollar sign (“$”)), and the attribute value is the name of the field that you want to filter on.

Filter Component Data by Text

When you want user-specified text to filter results shown in a list component like Select Single, you can configure the TextFilterAttributes property on the Service Data Provider (SDP) used to retrieve the list's data. The TextFilterAttributes property lets you specify data fields whose values you want to search for the text a user enters. Only values that match the user's text in each of those fields will be shown in the list.

Say you've set up a Select Single component to display employee data in a list and you'd like the user to filter the data as they enter some text string in the Select Employee field:
Description of text-filter-attributes-data.png follows
Description of the illustration text-filter-attributes-data.png

To achieve this, you need to configure the TextFilterAttributes property on the SDP variable used to bind the component to an endpoint. For example, your Select Single component might use the employeeListSDP variable to request and receive data from the getall_Employees endpoint. This variable is usually created for you when you use the Add Data Quick Start to bind a component to an endpoint and can be found on the page's Variables tab. Update the variable's TextFilterAttributes property to specify one or more data fields, for example, name and country:
Description of text-filter-attributes.png follows
Description of the illustration text-filter-attributes.png

A list that's based on an SDP doesn't hold a client-side array of data, so filtering is done by sending a "q" query string to the endpoint. The endpoint returns the matching values to the client, populating the SDP. So now if the user were to enter us in the Select Employee field, Visual Builder searches for values in the Name and Country fields that match us. The results (as shown here) include three employees who belong to the Country USA as well as one employee whose name includes those letters:
Description of text-filter-attributes-result.png follows
Description of the illustration text-filter-attributes-result.png

You can also include data fields that don't display to the user—as long as those fields are included in the SDP's definition. For example, if you selected salary and phoneNumber as the text filter attributes, a user who entered 50 would see three results because the text matches the Salary field of John Doe and Shelley White as well as the phone number of Albert Cain, although Phone Number isn't displayed as a column in the list.

Quick Starts

The behavior of pages is determined by the actions chains and events associated with pages and page elements. For common use cases, Quick Starts can help you create the artifacts, such as variables and action chains that are used to build functionality in pages.

Add Page Functionality Using Quick Starts

A Quick Start is a tool to help you create artifacts and action chains needed to add runtime functionality to an application.

A variety of Quick Starts are available to help you perform some of the tasks required to add common application functions and behavior, for example, mapping a list to a data source or adding a page for creating new records. To add functionality, you need to create the artifacts that perform that function. And depending on how complex the behavior is, adding a functionality might involve creating several variables, types, action chains, and page events. If there's a Quick Start for your task, you can use it to quickly create many of the artifacts for you.

When you are designing pages in the Designer, the Quick Start tab in the Properties pane will display a list of Quick Start tasks that are typically used to add functionality or behavior to the selected component and the type of application that you are creating. The Quick Start tasks are based on common tasks that developers need to perform when creating applications.


Description of page-designer-quickstarts.png follows
Description of the illustration page-designer-quickstarts.png

Control the Layout

It's possible to customize the fields you want to show as part of a component on a page. The steps to customize fields in a layout are the same, whether you’re selecting endpoint attributes from a service connection or a business object in your application.

When you use collection components such as a table or list view to display data, you're binding the component to an endpoint, exposed by a service connection or a business object. The easiest way to do this is by using quick starts—and if you’re looking to customize the layout, you can use the Bind Data page of the wizard to select only the fields you want to display.

Here's an example of what you’ll see in a quick start when you’ve got business objects and a service connection as the source of your data. When you bind data, you’ll see the attributes of the source you select – this is where you can customize your collection component’s layout:
Description of custom_layout.png follows
Description of the illustration custom_layout.png

Quick starts automatically create the variables and types you need for a particular functionality, but if you decide to add an endpoint attribute that you didn't include originally, you'll need to modify the type (using the Edit From Endpoint link next to the type on the Types tab), then modify the UI. In this case, it might be simpler to delete the table or list view and start over with the quick start.

Add Data to a Table or List

Use the Add Data Quick Start to populate a table or list in a page with data from a business object.

When a page with a collection component loads, a request to get data is automatically sent to an endpoint, and the response is mapped to the fields in the collection component. You will typically choose a data source that provides a GET MANY endpoint.

The Add Data Quick Start does the following for you.

  • The Quick Start automatically modifies the collection component to add the fields necessary to display the fields in the data source that you selected. Each field is mapped to the corresponding attribute of the variable bound to the component.

  • The Quick Start creates a variable that is bound to the collection component. For the business object Contact, a new page-scoped variable named contactListSDP that stores details about the endpoint, the request, and the response type. When the collection is selected on the canvas, you can see the variable bound to the component in the Data field of the Data tab of the Properties pane:


    Description of page-collection-data-variable.png follows
    Description of the illustration page-collection-data-variable.png

    You can see the details of the new variable if you open the Variables editor of the page. In the General tab of the Properties pane, you can see the ID of the variable, the type, and the endpoint that is called. The variable’s type is Service Data Provider, a specific type that is designed for variables that are used to send a request to an endpoint.


    Description of var-page-servicedata-general.png follows
    Description of the illustration var-page-servicedata-general.png
  • The Quick Start creates a page-scoped type that describes the data structure of the response. The fields in the response are mapped to the field in the component. When you select the new variable in the Variables editor, in the Properties pane you can see that the type for the response is a new custom type named getallContactResponse. The data structure defined by the type is based on the fields in the endpoint that you selected in the Quick Start.

    The new custom type is added to the list of types available in the page. You can see the details of the new type in the Types tab of the page’s Types editor.

Use the Add Data Quick Start

To use the Quick Start, you must first add an endpoint for a service connection or business object to your visual application. After adding the endpoint, you can step through the Add Data Quick Start to quickly create the artifacts needed to bind a table or list to the endpoint. The Quick Start will create a page variable for storing the data and a custom type that defines the data structure of the response to the request.

To bind an endpoint to a collection component:

  1. Drag a table or list component from the palette onto the canvas.
  2. Select the component and click Add Data in the list of Quick Starts.
  3. Select the data source that you want to bind to the collection. Click Next.
  4. Drag the fields you want to retrieve from the Endpoint Structure into the columns or template fields in your collection component.

    If you are binding data to a List component, you select a list template before binding the data from the endpoint to the fields.

  5. Select the field to use as the Primary Key. Typically this is the Id field. Click Next.
  6. Define the parameters for querying the endpoint. Click Finish.
The collection is now bound to the endpoint you selected.

Add a Create Page With a Quick Start

Use the Add Create Page Quick Start to create a new page with a form that interacts with an endpoint to create a new object.

The Add Create Page Quick Start adds a Create button to the page with the collection. Clicking the Create button starts an action chain that navigates to a Create page containing a form for adding data. Clicking the Save button in the Create page starts an action chain that sends a request to the CREATE endpoint of the data source. The data in the page’s fields are stored in a variable that is mapped to the parameters of the request. If the request is successful, the user is navigated back to the page with the collection.

In the page with the collection component, the Quick Start does the following:

  • Creates an action chain for navigating to a page.

  • Adds a button component with an ojAction event that starts the action chain.

In the new Create page, the Quick Start does the following:

  • Creates a page variable for storing the data for the new business object. The variable’s attributes are mapped to the parameters that are included in the request to the endpoint.

  • Creates a variable type for defining the data structure of the variable.

  • Adds a form with field components for the fields in the new business object. The fields are bound to fields in the new variable.

  • Adds a Save button and Cancel button with ojAction events that start action chains.

  • Creates an action chain to create the new business object. The action chain is started when the Save button is clicked.

    The action chain sends a request to the CREATE endpoint of the business object. The data stored in the page variable is mapped to parameters that are sent as a request to the endpoint. The action chain includes actions that navigate to the previous page if the request is success or displays a warning if the request fails.


    Description of action-chain-call-rest.png follows
    Description of the illustration action-chain-call-rest.png
  • Creates an action chain to navigate back to the previous page when the Cancel button is clicked.

Use the Create Page Quick Start

To use the Add Create Page Quick Start, you start from a page where a table or list is already bound to an endpoint. As you step through the Quick Start, you select the fields that you want to include in the Create page when you create the new object. The Quick Start will add a button to navigate to a Create page with a form for adding data to create a new object.

When you create a new object, you will use a data source endpoint with a POST method. The source will already be preselected in the Quick Start based on the source bound to the collection.

To add a page to create a new business object:

  1. In the page containing the collection component, select the component on the canvas and open the Quick Start tab in the Properties pane.
  2. Click Add Create Page.
  3. Select the data source where you want to create a row. Click Next.
  4. Drag the fields you want to add from the Endpoint Structure into the columns or template fields in your collection component. The Create page will include these fields in the form.
  5. Modify the label for the button, the page title and the page name, if desired. Click Finish.

A new page is created with a form for creating a new business object.

Add an Edit Page With the Quick Start

Use the Add Edit Page Quick Start to create a page for editing the details of an object.

Selecting an object in the component triggers a component event that stores the id of the selected object in a page variable. Clicking the Edit button triggers an action chain that navigates to an Edit page, and the id value stored in the variable is passed as an input parameter to the page. When the Edit page is loaded, a page event triggers an action chain that sends a request to the endpoint to get the data from the source, and the input parameter passed to the page is mapped to the input parameter required by the request. The response is mapped to a variable that is bound to the components in the page for editing the data.

Clicking the Save button in the Edit page starts an action chain that sends a request to the Update endpoint of the data source. The data in the page’s fields is stored in a variable and mapped to the parameters of the request sent to the Update endpoint.

In addition to creating the Edit page with a form containing the fields, the Quick Start creates various variables for the data and action chains to navigate to the page and call endpoints.

The Quick Start does the following in the page containing the collection:

  • Adds a button to the page. An ojAction event is added to trigger an action chain.

  • Adds a select event to the collection component that triggers an action chain.

  • Creates a variable to store the id of the selected object.

  • Creates an action chain that assigns the id of the selected object to a variable.

  • Creates an action chain to navigate to the Edit page. The action chain passes the object id as an input parameter. Creates an action chain for navigating to a page.

The Quick Start does the following in the Edit page.

  • Adds a form with fields bound to a variable.

  • Adds a Back button. A click event is added to trigger an action chain.

  • Creates an action chain that navigates back to the previous page triggered by an event on the Back button.

  • Creates a page variable to store the object id as an input parameter.

  • Creates a page variable to store the response from the endpoint. The Quick Start also creates a new Type that defines the structure of the variable.

  • Creates an action chain that calls an endpoint when the page is loading and assign the response to a page variable. The action chain has an input parameter mapped to a page variable

  • Creates an action chain to update the business object. The action chain is started when the Save button is clicked.

    The action chain sends a request to the Update endpoint of the data source. The action chain includes actions that displays a message if the request succeeds or a warning if the request fails.


    Description of quickstart-edit-action-update.png follows
    Description of the illustration quickstart-edit-action-update.png

    The data stored in the page variable is mapped to parameters that are sent as a request to the endpoint.


    Description of quickstart-edit-action-mapvariables.png follows
    Description of the illustration quickstart-edit-action-mapvariables.png
Use the Add Edit Page Quick Start

When you have a page with a table or list component, you can use the Add Edit Page Quick Start to add an Edit button to the page that is enabled when you select an object in the table or list. Clicking the Edit button opens a page that displays a form with fields for editing the selected object.

You can open the Add Edit Page Quick Start from pages that use a table or list component to display a collection. The Quick Start is listed in the Quick Start tab in the Properties pane when you select the component on the canvas. As you step through the Quick Start, you select the endpoint with the GET method (Get One) to request the data to display in the Edit page, and then the endpoint with thePATCH method (Update) where the request to update the data is sent. You also select the fields that you want to display in the Edit page.

To create an Edit page:

  1. Select the table or list on the canvas.
  2. Open the Quick Start tab in the Properties pane, if not already open.
  3. Click Add Edit Page.
  4. Select the data source containing the GET endpoint to get the data you want to edit. Click Next.
  5. Select the data source containing the UPDATE endpoint to send a request to update the selected record.
  6. Drag the fields you want to include in the Edit page from the Endpoint Structure into the columns or template fields.
  7. Specify the name of the button that will open the Edit page, and the title and name of the new page. Click Finish.

The page now has a new button that will navigate to a page that contains a form for editing the data of the object that is selected in the collection.

Add a Details Page With the Quick Start

Use the Add Detail Page Quick Start to create a page that displays the details of an object selected in a table or list.

After you use the Quick Start to add the Detail page, clicking the Details button opens a page that displays details of the selected object. Selecting an object in the component triggers a component event that stores the id of the selected object in a page variable. Clicking the Details button triggers an action chain that navigates to the Detail page, and the id value stored in the variable is passed as an input parameter to the page.

When the Detail page is loaded, a page event triggers an action chain that sends a request to the endpoint to get the data, and the input parameter passed to the page is mapped to the input parameter required by the request. The response from calling the endpoint is mapped to a variable that is bound to the components in the page that display the data.

In addition to creating the details page with a form containing the fields, the Quick Start creates various variables for the data and action chains to navigate to the page and call the endpoint.

The Quick Start does the following in the page containing the collection.

  • Adds a button to the page. An ojAction event is added to trigger an action chain.

  • Adds a select event to the collection component that triggers an action chain.

  • Creates a variable to store the id of the selected object.

  • Creates an action chain that saves the id of the selected object in a variable.

  • Creates an action chain to navigate to the Detail page. The action chain passes the object id as an input parameter.

The Quick Start does the following in the Detail page.

  • Adds a form with fields bound to a variable.

  • Adds a Back button. An ojAction event is added to trigger an action chain.

  • Creates an action chain that navigates back to the previous page triggered by an event on the Back button.

  • Creates a page variable to store the object id as an input parameter.

  • Creates a page variable to store the response from the endpoint. The Quick Start also creates a new Type that defines the structure of the variable.

  • Creates an action chain that calls an endpoint when the page is loading and assigns the response to a page variable. The action chain has an input parameter mapped to a page variable.

Use the Add Detail Page Quick Start

When you have a page with a table or list component, you can use the Add Detail Page Quick Start to create a Detail page for a record and add a Details button to open the new page. The button is enabled when you select an object in the table or list.

You can open the Add Details Page Quick Start from pages that use a table or list component to display a collection. The Quick Start is listed in the Quick Start tab in the Properties pane when you select the component on the canvas. As you step through the Quick Start, you select the endpoint for the business object and the business object’s fields that you want to display in the details page.

To create a Detail page:

  1. Select the table or list on the canvas.
  2. Open the Quick Start tab in the Properties pane, if not already open.
  3. Click Add Detail Page.
  4. Select the data source containing the Get One endpoint to get the data you want to display in the Detail page. Click Next.
  5. Drag the fields you want to include in the Detail page from the Endpoint Structure into the columns or template fields.
  6. Specify the name of the button that will open the Detail page, and the title and name of the new page. Click Finish.

The page now has a new button that will navigate to a page that shows details of the selected object.

Quick Starts for Dynamic Forms and Tables

When you add a dynamic form or table to a page, you have access to quick starts that help you configure data connections and layouts to dynamically display content based on rules that you've defined.

The quick starts for dynamic components walk you through similar steps as those for a standard component. For example, a dynamic table's Configure Dynamic UI quick start prompts you to select a data source and define parameters to query an endpoint, much like a standard table's Add Data quick start. Though instead of selecting fields to bind to the table collection component, you'll need to define a rule set to show fields in the dynamic table's layout based on conditions.

Here are the dynamic component quick starts that with the exception of rule sets, provide functionality similar to that of standard components:
Dynamic component Associated Quick Start Similar to:
Dynamic table Configure Dynamic UI Add Data
Dynamic form Configure as Create Form Add Create Page
Configure as Edit Form Add Edit Page
Configure as Detail Form Add Detail Page

When working with either set of quick starts, keep one key difference in mind: standard component quick starts add pages to your visual application (for example, the Add Edit Page quick start creates a separate page for editing an object's details); dynamic component quick starts configure an existing form or table on the current page.

Work with Code Editors

Most application development in Visual Builder is visual and declarative. Sometimes though you might want to update your application's source code or add custom code to make your application richer—and code editors in the Designer let you do just that.

The HTML, JSON, JavaScript, and Code view editors give you direct access to the code created by visual tools when you develop your application. For example, when designing a page, you can choose to directly edit the source code of the HTML, JavaScript, and JSON files used to describe the page's layout and behavior. See What is the Designer? for what you can view and edit in each editor.

Visual Builder's code editors are based on Monaco, a JavaScript library bundled from the Visual Studio Code source, which provides a variety of code-editing features, including tooltips and hints, parameter information, and code completion.

Trigger Code Insight

When working with code editors, you can invoke insights either by pressing Ctrl+Space or by entering a trigger character such as the dot (.) in the JavaScript editor. Here's how you can use insights in the different editors:
Editor Use this to trigger insight:
HTML
  • Enter the left-angle bracket (<) to trigger HTML tag insight.

  • Press Ctrl+Space to trigger HTML attribute name insight. Insight automatically kicks in after you enter two characters from the attribute name.

  • Press Ctrl+Space to trigger attribute value insight inside an HTML attribute value, double brackets ([[ ]]), or double braces ({{ }}).

    If the HTML is well formed, insight kicks in after you enter two characters of the expression. For example, entering <div title="[[ $a ]]"> triggers attribute value insight for expressions after $a, as shown here:


    Image showing attribute value insight triggered triggered for expressions after $a when you enter <div title="[[ $a ]]".

  • Enter any character to trigger insight in CSS files.

JSON

Enter any character to trigger insight based on the file's associated JSON schema.

JavaScript

Enter any character to trigger insight. URL selector and standard imports for a module are not supported.

Keyboard Shortcuts for Code Editors

To help you work efficiently, Visual Builder supports the following keyboard shortcuts in code editors:
To do this: Use this on Mac: Use this on Windows:
Show Command Palette F1 F1
Save Command-S Ctrl+S
Basic Editing
Cut line if there is no selection; cut selection if there is one Command-X Ctrl+X
Copy line if there is no selection; copy selection if there is one Command-C Ctrl+C
Move line up Option-Up Alt+Up
Move line down Option-Down Alt+Down
Copy line up Shift-Option-Up Shift+Alt+Up
Copy line down Shift-Option-Down Shift+Alt+Down
Delete line Shift-Command-K Ctrl+Shift+K
Insert line below Command-Enter Ctrl+Enter
Insert line above Shift-Command-Enter Ctrl+Shift+Enter
Jump to matching bracket Shift-Command-\ Ctrl+Shift+\
Indent line Command-] Ctrl+]
Outdent line Command-[ Ctrl+[
Go to beginning of line Home or Fn-Left Home
Go to end of line End or Fn-Right End
Go to beginning of file Command-Home Ctrl+Home
Go to end of file Command-End Ctrl+End
Scroll line up Command-Up Ctrl+Up
Scroll line down Command-Down Ctrl+Down
Scroll page up Option-PgUp Alt+PgUp
Scroll page down Option-PgDn Alt+PgDn
Fold (collapse) region Command-Shift-[ Ctrl+Shift+[
Unfold region Command-Shift-] Ctrl+Shift+]
Toggle line comment Command-/ Ctrl+/
Toggle block comment Shift-Option-A Shift+Alt+A
Toggle word wrap Option-Z Alt+Z
Navigation
Go to line ... Command-G Ctrl+G
Go to symbol ... Shift-Command-O Ctrl+Shift+O
Go to next error or warning F8 F8
Go to previous error or warning Shift+F8 Shift+F8
Go back Control-- Alt+Left
Go forward Control-Shift-- Alt+Right
Search and Replace
Find Command-F Ctrl+F
Replace Option-Command-F Ctrl+H
Find next Command-G F3
Find previous Shift-Command-G Shift+F3
Select all occurrences of Find match Option-Enter Alt+Enter
Add selection to find matches Command-D Ctrl+D
Multi-cursor and Selection
Insert cursor Option-Click Alt+Click
Insert cursor above Option-Command-Up Ctrl+Alt+Up
Insert cursor below Option-Command-Down Ctrl+Alt+Down
Undo last cursor operation Command-U Ctrl+U
Insert cursor at end of each line selected Shift-Option-I Shift+Alt+I
Select current line Command-L Ctrl+L
Select all occurrences of current selection Shift-Command-L Ctrl+Shift+L
Select all occurrences of current word Command-F2 Ctrl+F2
Expand selection Control-Shift-Command-Right Shift+Alt+Right
Shrink selection Control-Shift-Command-Left Shift+Alt+Left
Column (box) selection Shift-Option- (drag mouse) Shift+Alt + (drag mouse)
Ctrl+Shift+Alt+(arrow key)
Column (box) selection page up Shift-Option-Command-PgUp Ctrl+Shift+Alt+PgUp
Column (box) selection page down Shift-Option-Command-PgDn Ctrl+Shift+Alt+PgDn
Rich Languages Editing
Trigger suggestion Command-Space Ctrl+Space
Format document Shift-Option-F Shift+Alt+F
Go to definition F12 F12
Peek definition Option-F12 Alt+F12
Show references Shift+F12 Shift+F12
Rename symbol F2 F2

Work with the JavaScript Editor

You use the JavaScript editor to add custom JavaScript functions that can be called from within your page, flow, or application.

Any JavaScript code that you add will have a defined scope based on the editor where you write the code. If your code will only be called from within a specific page, for example, to load some data when the page loads, you can write your code in the page artifact's JavaScript editor. If you want to use some JavaScript functions that will be used on multiple pages, for example, loading libraries for customizing navigation elements or custom web components, then you will probably want to open the JavaScript editor for a flow or the application.

The JavaScript editor for pages, flows, and application opens the JavaScript file of an artifact. Each app, flow, and page has a separate JavaScript file. For example, the main flow uses the main-flow.js and main-flow.json files to describe the artifact. You can open the JavaScript editor for the main flow by opening the artifact in the Designer and clicking the JavaScript tab, or by locating the JavaScript file in the Source view in the Navigator.


Description of page-functions-editor.png follows
Description of the illustration page-functions-editor.png

The editor provides code validation and identifies the lines that contain syntax warnings and errors in the right margin of the editor. A lightbulb in the left margin indicates a hint for correcting invalid JavaScript code.

Note:

The auto-save function will not save a JavaScript file that has invalid code.
You can use your custom JavaScript functions: