3 Customize Dynamic Tables and Forms

When you want to modify how a dynamic table or form looks and behaves, you configure its rule set. A rule set defines the display logic and layouts used by a specific dynamic form or table.

To open a rule set, you can select the dynamic form or table in the Page Designer and open it's rule set from the Property Inspector, or, if you know the name of the dynamic UI artifact, you can select the artifact in the Application Extensions panel in the Navigator.

By default, a dynamic component is rendered according to what is specified in the built-in rule and accompanying built-in layout, but you can customize how the page appears by configuring the rule set with your own display logic and layouts.



The fields you can display in a layout are determined by the fields available from the Dynamic UI artifact's data resource, which is defined in the base app. For example, the base app might define five fields that you can use in a dynamic component. You can choose which of these five fields (and also other fields defined in the same artifact) that you want to display in the component—and the order in which they should appear—but you can't include fields from other data resources.

You can, however, make some modifications to the fields you use in your layouts by changing a field's properties (for example, making a field Read Only or Required) and by creating custom fields that combine data from multiple fields or variables. For example, you could create a custom field full.name that combines the fields first.name and last.name and add the custom field to your layout.

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 Rule Sets tab. Suppose you want to configure a dynamic table so that certain columns are hidden and others are added when the user viewing the page is in Canada. You’d then create a rule that checks for the user’s location and, if the user is indeed in Canada, apply the layout you’ve created that contains the desired columns. All non-Canadians would see the page with the default layout applied.

You can have more than one rule for a given component, and the order in which they appear in the display logic tree is important. 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 in Canada—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.

When you select a dynamic UI artifact in the Application Extensions pane, then open the dynamic UI's Rule Sets tab, you'll see a list of the dynamic components using the fields defined in that artifact. For example, suppose there’s a dynamic form bound to the ProfileOrgCardLayout dynamic UI artifact. When you open the artifact's window, in the Rule Sets tab you’ll see the name of the rule set (Organization Card) listed under Dynamic Form:



You would see more names in the Rule Sets tab if other dynamic forms or tables used fields defined in the same dynamic UI artifact. You click a rule set's name to open it in the Rule Set editor.

To set the display logic for a component:

  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 Property Inspector.
  2. Click Open Rule Set Editor in the Property Inspector for the form or table .


    In this image of the Property Inspector, you can see the name of the dynamic component's rule set (Organization Card).

  3. In the Rule Set editor, click Duplicate Rule and give it a name, preferably something meaningful. For example, to create a layout that displays only when the user is in Canada, you might call the rule inCanada.

    The rule set for a dynamic component always contains a default rule that is set by the base application. You can't change this rule, but you can copy it to use it as the basis for your own rules, or you can create a rule from scratch.



    If you want to also create a copy of the layout to use as a starting point, make sure that check box is selected in the Duplicate Rule dialog box.

  4. In your new rule, click Click to add condition, then select an Attribute and Operator from the dropdown lists, and enter a Value to create a condition. Click Done.

    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 manager role. You would then create a rule with two conditions, and select Match All to require that both conditions are true.



    If you select Match Any, then the rule will be evaluated as true if any of the conditions in the rule are true.

  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.

  6. Click Rule to add another rule.
  7. 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.

Create Conditions Based on User and Device

When creating rules in your rule sets, the condition builder has an Attributes list for selecting variables you can use when creating conditions. By default, the list includes some variables storing details about the current user and the device they're using. You can use them, for example, to create a condition that displays a layout only to authenticated users viewing the page on a tablet-sized screen or larger:



In addition to data fields retrieved from the Oracle Cloud Application (for example, record.NoteTxt), you can also select default variables that are determined by the app extension's context (for example, user.email). Two kinds of app extension context ($context) variables are available: user and responsive. The values for the user variables are determined by the current user, and the responsive variables are determined by the screen size of the device the app extension is currently displayed on (for example, a tablet).

If you click Display codeand look at the code for the rule above, you'd see the following expression: $responsive.mdUp === true && $user.isAuthenticated === true ? 'isDefault_copy' : null

The following user variables are added to the $context available in layout expressions:

  • $context.user.userId
  • $context.user.longId
  • $context.user.fullName
  • $context.user.email
  • $context.user.roles
  • $context.user.isAdmin
  • $context.user.isAuthenticated

Note:

Depending on your Oracle Cloud Application, when using $context.user.roles in a condition or display properties, the list of values might contain the app's pre-defined roles (for example, $context.user.roles.manager). If the Attributes list displays roles as a property, in your rule you would specify the Value as true or false. If the roles are not listed you should type the role name.

The following responsive variables are added to the $context available in layout expressions:

  • $context.responsive.smUp
  • $context.responsive.mdUp
  • $context.responsive.lgUp
  • $context.responsive.xlUp
  • $context.responsive.smOnly
  • $context.responsive.mdOnly
  • $context.responsive.lgOnly

Note:

If you are editing expressions and want to use these variables, you should note that the responsive variables are wrapped with an accessor, so parentheses are not used in expressions (for example, $context.responsive.mdUp === true ?).

Create a Layout for a Dynamic Form or Table

A layout defines the fields that are displayed in a dynamic component at runtime. 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 one layout that shows certain fields in a dynamic form when the user is a manager, and another layout for non-managers. 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 user is a manager—then the layout you selected for that rule is applied to the component and the user will see the fields he needs in the form. Non-managers will see a different layout.

Each rule set contains a default layout that is seeded for you. You can't edit the default layout, but you can duplicate it and use it as the basis for a new layout. The default layout is always used in the last rule of the display logic tree.

To create a new layout:

  1. Open the rule set you want to edit.
  2. Click New in the rule set's Layouts column and type a name for the new layout, or click Duplicate in an existing layout to use it as a starting point.
  3. Click the new layout to open the dynamic UI layout editor.

    The editor lists the fields that will be displayed in the layout and the templates that are applied to the layout and fields.

  4. In the Fields palette of the editor, select the checkbox for the fields you want to add to the layout. You can remove fields from the layout by clicking its Delete icon in the center pane.

    You can also drag fields from the Fields palette directly onto the drop target in the center pane containing the added fields.

    When editing a form layout that uses a template, if you add a field that is already referenced in the template, the field will appear twice in your layout, but they might be rendered differently depending on the component used in the form template.

  5. To edit the properties of a field, select it in the center pane, then edit its properties in the Property Inspector.

    Note:

    If you want the field to have the same property in all layouts—for example, if you want it always to be Read Only—you should select the field in the Fields tab and set the property in the Property Inspector. (If the property you want to affect is not available to edit in the Property Inspector, you can create a custom field and set the property for it. Then any layout using that field will have the property set as you've defined it.)

    In the Property Inspector, you can set properties and create expressions that control the behavior of the selected field, as well as how it is displayed:



    For example, the default value for the Show Field property is Always, but you can change that by clicking Always, then setting the conditions under which you want this field to display:



  6. Change the order that fields are displayed in the component by dragging fields into a different position within the fields column.
  7. Define how the field is rendered by selecting a template from the Template dropdown list.

    Some field templates are defined in the base app, but you can also create your own.



    Some fields might already have a field template applied to them (you'll see the template name next to the field name). To use a different template for these fields, select the field and click Override in the Property Inspector, then select the template you want to apply, or choose None to not use one.



    If you want to re-apply the default template to the field, click Reset.

  8. If you're customizing a dynamic form, you can apply a form template to a layout to change the fields specified in the layout and how the layout is rendered.

    When working with dynamic forms, if you duplicate an existing layout your new layout might already list some fields, or have templates already applied to the form or to fields. You can replace or remove the layout's default form template using the Form Template dropdown list in the Property Inspector, which lists the available templates.



    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. You can't edit the fields defined in layout templates defined in the base app. If you want to use a different set of fields, or change how they are rendered, you'll need to select a different template or choose 'None' from the Form Template dropdown list.

    For greater control over form layouts, you can create your own form templates and apply it to layouts. For more on using templates with a form layout, see Control How a Form Layout is Rendered.

After a layout is created, you can include it in a display logic rule, as described in Determine What's Displayed at Runtime. You can use the same layout in multiple rules.

Preview Different Dynamic Layouts

To preview how different layouts will look when applied to your page, use the Layout Preview in the Property Inspector. Layout Preview forces the Page Designer to use the layout you select and ignore the rules in the rule set. For example, if you created a layout that only managers can see, you won't see it in the Page Designer if you're not logged in as a manager. You use Layout Preview in the Property Inspector to override the display logic and render the page using the layout you select.

To preview a dynamic component layout:

  1. Open the page in the Page Designer and select the dynamic table or form you want to work with.

    The Layout Preview drop-down list displays all the layouts that have been defined for this component's rule set.

  2. Select a layout in the Layout Preview dropdown list:


    In this image the inCanada layout is selected in Layout Preview and is being displayed in the dynamic form. To open the layout in the editor, click Configure Layout.

  3. Click Reset to return to the default "Resolved by display logic" option.

Customizing Dynamic Form Layouts

In the dynamic UI layout editor, you can customize how a dynamic form's layout is rendered on the page by grouping the fields together and by applying templates to the form layout and fields.

Control How a Field is Rendered on the Page

You can customize how a field is rendered in a layout for a dynamic form (not table) through the use of field templates. A field template can define the field's properties, such as styling details, but it can also contain other UI components. Components in a template can access the variables, constants, actions and event listeners defined in the dynamic UI artifact.

Editing a layout, you can apply a field template to any of the form's fields. The template can be one of the built-in templates defined in the base app, or it could be your own custom field template. A field template can be used in any layout used in a dynamic form, but templates can't be shared between dynamic UI artifacts.

The base app might define default templates that are applied to each field in a rule set, which means the templates would be applied to the fields in every layout in the rule set. You can override a field's default template to apply a different one in specific layouts, or specify a new default template for the field in all layouts in the rule set.

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

  1. In the dynamic UI layout editor, select the field that you want to customize.
    Alternatively, you can open the Templates tab of the dynamic UI artifact and click Template to create a field template from scratch or duplicate a template you've created.
  2. In the Property Inspector, click Override, then click Create to open the dialog box for creating the new template that you want to apply to the field instead of the current template.
  3. Type an ID and label for the new template in the dialog box. Click Create.
    The new template opens in the template editor.
  4. In the template editor, drag the components you want to add from the Components palette onto the canvas. If you created the template based on a field in your layout, the template will already contain a field component, otherwise you'll want to add a field component to the template.

    For example, you could add an icon component that you want to appear next to the field:



  5. Select a component on the canvas or in Structure View, then edit its properties in the Property Inspector.

    Just like when you are working in the Page Designer, the Property Inspector contains several tabs for editing a component's properties. For example, if you added an icon component to your template, you could 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.

    <template id="jobNameLayoutTemplate">
      <oj-input-text value="{{ $currentField.value }}"></oj-input-text>
      <span class="vb-icon vb-icon-compass"></span>
    </template>
  6. Click Return to layout when you are finished editing the template. The template is automatically applied to the field.

    By default, when you apply a template to a field, it's only applied to the field in the current layout. If you want the template applied to the field in every layout in the rule set, click Set as rule set default in the Property Inspector.



After creating your template, it is added to the list of field templates in the Templates tab. In the Templates tab, you can open and duplicate templates you've created.

Control How a Form Layout is Rendered

In the dynamic UI layout editor, you can apply a form template to layouts to control how a layout is 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 to display a detail view that includes contact details, and you want the fields for the contact details grouped and displayed in a specific way instead of the default layout used for form fields. You could create a 'Contact Details' template that specifies the fields you want to include and how they are rendered in the layout. In the template designer you select the fields to include and then bind them to components in your template. You can then re-use this template in multiple form layouts.

You apply a form template to a form layout in the dynamic UI layout editor. The template can be one of the built-in templates defined in the base app, or it could be your own custom form template. A form template can be applied to any layout used in a dynamic form, but templates can't be shared between dynamic UI artifacts.

To create a form template for a dynamic form:

  1. Open the dynamic UI artifact's Templates tab.

    The Templates tab displays a list of field and form templates that are already defined for the artifact. Templates defined in the base app are marked with base icon .



  2. Click Create Template and select Form in the dialog.
  3. Specify the Label and ID. Click Create.

    Your new form template opens in the template designer. The template designer contains a Components palette, Structure view, canvas and Property Inspector.

    Your new form template has Bind For Each components containing read-only template field iterators ($fields.$display, $fields.$remainingRequired) that are generated automatically. These are used for displaying the data and display names for the fields defined in the layout. When you're creating a template, you can add page components above or below the read-only template fields.



  4. In the Properties Inspector, click Add item in the Extras section and add the fields that you want to include in your template.

    You add the field to the template and then map it to a component. This image shows the Property Inspector after adding the Score field to the template as an Extra.



  5. 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 generated Bind For Each components, but not within them. In this Structure view of the template, you can see a component that was positioned above the top Bind For Each component.



  6. While the component is selected on the canvas or in the Structure view, open the component's Data tab in the Property Inspector and bind the component to the reference field.

    You can click fx iconto open the Expression Editor to help you select the reference field.



After you've added the components and fields to your form template, you can apply the template to a layout in the dynamic UI layout editor. When your form is selected in the dynamic UI layout editor, you can select your new template in the Form Template dropdown list in the Property Inspector.



After applying the template, in the layout's header you'll see the name of the template that'll be used to render the layout and the fields referenced by the template. Fields in the template are rendered using the component bound to the field in the template.

Add and Group Fields in Dynamic Form Layouts

When creating a layout for a dynamic form on the Rule Sets tab, you can group fields so that they are displayed together in a layout, and so you can treat them as a single entity. For example, you can create an address group that contains the fields (for example, name, address, city, state, country and post code) that you want to be displayed as a group in your layout. 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.

    Select a dynamic UI under Application Extensions on the left, then choose the dynamic form; click the form on a rendered page in the canvas area; or select it from the Property Inspector.



  2. Open the form you want to edit.

    You can use buttons in the toolbar to duplicate the current layout (Duplicate layout button), to copy selected fields in your current layout to another layout (Copy selected fields to another layout button), and to copy fields from another layout into the current one (Copy fields from another 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 Property Inspector, or Group Fields in the toolbar.
  5. Type a name for the new group by naming the folder in the layout diagram. Click Save to save the group name.
  6. Optionally, use the Property Inspector 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.

Create a Custom Field in Your Dynamic Form or Table

You create a custom field (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. Suppose your data source has separate fields for the first name and last name. You could create a custom field that combines the separate fields into a field fullName, and use it in your layouts instead.

You can give custom fields a default value, modify labels and set read-only and required properties. A custom field can be used in any layout in dynamic components that use the same service endpoint and fields. Like other fields, you can use built-in and custom validators and converters with custom fields.

To create a custom field:

  1. Open the dynamic table or form you want to work with, then click the Fields tab:
  2. Click Custom Field.
  3. Type a label for the field (the field's display name) and select a type. When you type in the label field, a suggested ID is generated for you. The ID can't be changed later.
  4. In the Property Inspector, optionally set the Read Only, Required, and Default Value fields.
    For any field defined in the dynamic UI artifact, you can override properties such as "Read Only" and "Required" to set them to True by enabling the property in the Property Inspector. You can't set them to False (disabled) if they are already set to True in the dynamic UI artifact.
  5. If you want to use a field from the data resource, click Referenced Field, then select a field in the list. Click Add to add it.

    Add each referenced fields that you want to use in your custom field. After adding a referenced field, you can add an expression in the custom field's Value property. If you add one or more referenced fields, you won't see the Default Value property in the Property Inspector because the Value property now specifies the expression with the referenced fields.

  6. Supply a value such as a variable or expression for the Value property.

    If you want to use a single variable, you can click the arrow to open the Variables picker.



    if you want to use an expression, you can clickfxto 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.



    The expression you create in the editor is added to the Value field, for example, [[ 'Member of ' + $fields.departmentName.value() + $fields.JobName.value() ]].



  7. Optionally, you can click Add to add converters and validators to the field.

    You can 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, as shown below.

Custom fields, and any fields that you have modified (for example, in the Property Inspector), are indicated by a gray bar to the left of the field name. In this screenshot, you can see the gray bar next to MemberOfDepartment.



Add Converters and Validators to Fields

You can add converters and validators to fields, including some built-in ones provided by Oracle JET. For details and examples of how to use the built-in Oracle JET converters and validators, see the converters and validators sections 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 edit.
  2. In the Property Inspector, click Add next to Converter or Validators, then select one from the list.
  3. Click Add Validator or Add Converter.
  4. Click Edit to edit the validator or converter.

    Place your cursor over the name to display the Edit and Delete icons.



  5. 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 their 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.