3 Customize Dynamic Tables and Forms

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

To open a rule set, you can select the dynamic form or table in the Page Designer and open its rule set from the Properties pane, or, if you know the name of the layout, you can select it in the Application Extensions panel in the Navigator.

Here's what a rule set looks like for the Organization Card dynamic form, with a rule to determine if the user's role includes the string 'Canada', and a layout used when that rule is true.

Description of the illustration dynamicui-rulesets.png

Create a Layout for a Dynamic Form or Table

A rule set's 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 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 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.

The fields you can display in a rule set's layout are determined by the fields available from a layout artifact's data resource, and this data resource is defined by the base app. For example, the base app might define a data resource that has five fields. You can choose which of these five fields (and also other custom fields defined in the same layout) 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 resources. For details on creating fields in layout artifacts, see Create Fields For a Layout.

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 Open Rule Set Editor in the Properties pane for the form or table.
   
   

   
   Description of the illustration designer-page-dyncomponent-properties.png

   
   

   In this image of the Properties pane, you can see the name of the dynamic component's rule set (Account Hierarchy Card Layout).

3. Click in the rule set's Layouts pane and type a name for the new layout, or click in an existing layout to use it as a starting point.
   
   

   
   Description of the illustration dynamicui-rulesets-layoutspane.png

   
   
4. Click the new layout name, then click Select fields to display to open it in the layout editor.
   
   

   
   Description of the illustration dynamicui-ruleset-selectfields.png

   
   

   When you create a layout and haven't selected any fields for it yet, you'll see the Select fields to display option when you open the layout. (You won't see this option if the layout is a duplicate.) You'll also see the templates that already exist in the rule set listed as layout options. Click a template name if you want apply the template to the layout, otherwise, click Select fields to display.

   If you create a new layout rather than duplicating one, the layout might already contain some fields before you've added any. Any fields that are marked as "Required" in the layout's Fields editor are automatically added when you create a new layout.

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 to a layout by selecting its checkbox in the Fields palette or by dragging it from the palette onto the drop target in the center pane. You can remove a field from the layout by clicking its Delete icon in the center pane.

   
   

   
   Description of the illustration dynamicui-rulesets-addfield.png

   
   

   To help you locate the fields you might want to add, the Fields palette might contain a Suggested Fields section at the top of the palette. This section lists the fields that have been identified as the most relevant or most important when building your layout, which are usually the custom object fields created in App Composer (which you can usually identify because _c is appended to the name) and the fields required by the layout (the fields where the "Required" property is set to "true" in the layout's Fields editor).

   You can also filter the list of fields by entering a string in the Filter field at the top of the Fields palette.

6. Change the order that fields are displayed in the component by dragging fields into position in the center pane.

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.

Edit a Field's Properties in a Layout

When you edit a field's properties in a rule set's 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 Required or Read Only. If you want to edit a property so that it's the same in all layouts—for example, if you want it always to be Read Only—you should edit the field's properties in the Fields editor.

To edit a field's properties:

1. In the Rule Set editor, open the layout and select the field in the center pane.
2. Set the Show Field property to control when the field is displayed.
   The default setting for this property is Always. For details on how to set the property, see Use Conditions to Hide and Show Fields in a Layout.
3. Edit the field's Read Only and Required properties in the Properties pane.

   If you are editing the properties of a field defined by the Oracle Cloud Application service, the image below shows the message you'll see in the Properties pane if the field has undergone a custom transformation, which may override any changes you make to the field's properties.

   
   

   
   Description of the illustration dynamicui-rulesets-layoutfields-message.png

   
   

   In the next image, you can see the warning that is displayed in the Properties pane when you try to edit a property that you might not be able to override because it was already set in the Fields editor. For example, you'll see this warning if a custom field's property is set to Read Only and you try to override it in your layout.

   
   

   
   Description of the illustration dynamicui-rulesets-layoutfields-warning.png

   
   

   The Read Only and Required properties might not be editable in the Properties pane 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 these properties in the layout. In the next image, you can see that a field template is already applied to the selected field. For details about using templates with fields, see Apply a Template to a Field.

   
   

   
   Description of the illustration dynamicui-rulesets-layoutfields.png

   
   

Use Conditions to Hide and Show 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.

   
   

   
   Description of the illustration dynamicui-rulesets-layoutfields-notemplate.png

   
   
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.

   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 shows values already defined for the attribute (for example, 'true' and 'false'), if any, but you can also enter your own value.

   The Attributes variables are grouped by context in the list. In addition to the $fields context, there are variables in other built-in contexts that provide a way to access various pieces of information when building conditions. 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. Context variables include:

   • $fields variables determined by the fields displayed in the Fields editor. For example, the $fields.firstName.value lets you access the value of the First Name field in your data source. Look for these variables under the Fields group in the condition builder.

     Note:

     For each field, regardless of type, you can choose $numberValue (for example, $fields.ConflictId.numberValue()) or $value ($fields.ConflictId.value()). You should use $numberValue when you know the field's value should contain a number. For example, if the ConflictId field's type is a string and you choose $numberValue, the field's value will be converted to a number, if possible. If the value can't be converted, the $numberValue will be NaN (Not a Number).

     The only limitation is that $numberValue is limited by the maximum precision allowed by the Number type in Javascript.

   • $responsive variables determined by the screen size of the device the 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. Look for these variables under the Responsive group in the condition builder.
   • $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. You can use the user.roles variable to check the role of the user using the app. Look for these variables under the User group in the condition builder.

     Note:

     When using user.roles, the Value drop-down lists the available Oracle Applications Cloud job and abstract roles. (The drop-down will not list any duty roles. If you want to specify a duty role, you can manually type the duty role name in the Value field.)

   
   

   
   Description of the illustration dynamicui-rulesets-showfieldcondition.png

   
   

Set How User Assistance is Rendered in a Layout

You use the User Assistance Density property to set how a field's user assistance text such as messages, help text and hints are displayed in the form.

To edit a field's User Assistance Density property in a layout:

1. In the Rule Set editor, open the layout and select the field in the center pane.
2. Select the field's User Assistance Density property from the dropdown list in the Properties pane.
   
   

   
   Description of the illustration field-user-assistance.png

   
   

   You can choose from three options:

   • compact - With this option, user assistance text is displayed so that the layout is more compact, such as using a popup for messages and a required icon to indicate a Required field.
   • efficient - With this option, any user assistance text is shown inline under the field. The form is rendered with space under the field for the user assistance text. This is the default option.
   • reflow - With this option, any user assistance text is shown inline under the field. The form is rendered with no space under the field for the user assistance text. The space below the field expands to display the user assisstance text when the insert cursor is in the field.

   This image of a form can help you visualize how these settings affect how fields are rendered:

   
   Description of the illustration form-ua-density.png

   In this form, the User Assistance Density property for the fields are set to different values:

   • the Name field is set to efficient,
   • the Job Title field is set to reflow,
   • the Last Updated By field is set to reflow, and
   • the Id field is set to compact.

   You can see that both the Job Title and Last Updated By fields are set to reflow, but that the space below the Last Updated By field, where the insert cursor is) has expanded so that the user assistance text can be rendered below it.

Configure How Columns Are Rendered in a Dynamic Table Layout

When editing the layout for a dynamic table, you can edit the fields in the Properties pane to configure the width of each column in the table, and if the table is sortable by any of the fields. When you set the properties for a field in a layout, the settings only apply to the current layout. The other layouts are not affected.

To configure the properties for columns in a table layout:

1. In the Rule Set editor, open the dynamic table's layout
2. Select the field in the center pane that you want to edit.

   When you select the field, you can see the field's properties in the Properties pane.

   
   
   
   Description of the illustration dynamicui-rulesets-layoutfields-tablefields.png
   
   

   For fields in a dynamic table's layout, the Properties pane contains some display properties to control how the field is rendered in the table:

   • Sortable: This property determines if the table is sortable on the selected field.
   • Width: This property sets the default width of the selected field column in the table.
   • Minimum Width: This property sets the minimum width of the selected field column when the table is first rendered on the page. A user can manually resize the column width to make it narrower.
   • Maximum Width: This property sets the maximum width of the selected field column when the table is first rendered on the page. A user can manually resize the column width to make it wider.

Set a Field to Display as a Text Area in a Form

If a field's value is a long string, for example, when a field is used to display a long description, you can configure the field so that it is rendered as a multi-line text area in forms instead of the default single-line text field.

• To set a field to display as a text area in all layouts:
  1. In the layout's Fields tab, select the field you want to work with.
  2. Set the Format property in the Properties pane to long-text.
     
     

     
     Description of the illustration dynamicform-fields-textarea.png

     
     

     Notice that the Format property now has a vertical gray bar next to it to indicate the property has been modified.

     When you switch the format to long-text, two additional properties are displayed in the Properties pane.

  3. Set the Rows property to the number of rows to display in the form by default.
  4. Set the Max Rows property to the maximum number of rows you want to be displayed in the form. The text area will expand to the Max Row number if needed. The maximum number of rows defaults to three if you don't set a number in the Max Rows property.
     
     

     
     Description of the illustration dynamicform-fields-maxrows.png

     
     
• To set a field to display as a text area in a particular form layout:
  1. In the Rule Set editor, open the layout and select the field in the center pane.
  2. Set the Rows property to the number of rows to display in the form by default.
  3. Set the Max Rows property to the maximum number of rows you want to be displayed in the form. The text area will expand to the Max Row number if needed. The maximum number of rows defaults to three if you don't set a number in the Max Rows property.
     
     

     
     Description of the illustration dynamicform-layout-textarea.png

     
     

Work with Polymorphic Objects in a Layout

When you are adding fields to your layout, the Fields palette might include polymorphic objects containing fields you can select. Polymorphic objects are defined by the service that your app extension uses, and define a set of fields rather than a single field. A polymorphic object can display different field subsets based on a pre-defined discriminator sub-type that is evaluated at runtime. The polymorphic object might have several sub-types for the discriminator field, each defining a different set of fields.

In the image below, ExpenseDff is a polymorphic object, and __FLEX_Context is the discriminator field.

Description of the illustration dynamicui-layout-editor-poly.png

An @all field is automatically added when you add a polymorphic object to a layout, but you can also explicitly add fields to the center pane. When the center pane contains the @all field, all the fields, as determined by the discriminator, will be displayed in the layout. You can control the order that fields are displayed in the polymorphic object by explicitly adding fields to the object in the center pane.

In the example above, the discriminator has a sub-type Lunch that determines the fields that will be displayed (ExpenseId, expenseLine1, lunch1, lunch2, lunch3). All of those fields will be displayed when the Lunch sub-type is applied at runtime because the polymorphic object in the center pane includes the @all field. If you remove the @all field from the center pane without explicitly adding any fields, no fields will be displayed in the layout.

By explicitly positioning some of the fields (lunch2, ExpenseId), as in the image below, you can control the display order of the fields.

Description of the illustration dynamicui-layout-editor-polylist.png

The fields will appear in the following order when the Lunch sub-type is applied to the discriminator:

1. lunch2 (added and positioned explicitly)
2. ExpenseId (added and positioned explicitly)
3. expenseLine1 (added using @all)
4. lunch1 (added using @all)
5. lunch3 (added using @all)

If the @all field is removed, only the fields added explicitly (lunch2, ExpenseId) will be displayed when the Lunch sub-type is applied.

If the wifi field was added explicitly to the object, it wouldn't be displayed when the Lunch sub-type is applied to the discriminator.

To add a polymorphic object to your layout:

1. In the Rule Set editor, open the layout you want to work on.
2. Select the polymorphic object in the Fields palette, or drag it from the palette into the list in the center pane.

   The Fields palette lists all the fields and objects you can add to your layout, including polymorphic objects. Polymorphic objects in the palette have a special object icon ( ). You can expand the object node in the palette to see the sub-fields that could potentially be displayed if you added the object to the layout.

   If you want to see which fields you can add to the center pane, for a specific sub-type:

   1. Expand the object node in the palette.
   2. Click Modify and select a sub-type from the list. You can also broaden the filter by selecting more than one sub-type.
   3. Click Filter to filter the fields displayed under the object node.

   
   

   
   Description of the illustration dynamicui-layout-editor-polyfilter.png

   
   

   In the image below, the sub-fields of the polymorphic object ExpenseDff are filtered by the Meal sub-type. Instead of listing all the object's sub-fields, only the sub-fields defined by the Meal sub-type (drink, ExpenseId, expenseLine1) are listed under the object node. These are the fields that will be displayed when the @all field is added to the center pane and the Meal sub-type is applied.

   
   

   
   Description of the illustration dynamicui-layout-editor-polyfields.png

   
   

   By seeing the fields defined for each sub-type, you can decide which fields you might want to add to the center pane, if any.

3. Arrange the order that fields are displayed in the component by dragging fields into position in the center pane.
   You can control the order that a polymorphic object's fields are displayed by adding them explicitly and positioning them where you want.

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 rules are listed in a display logic tree when you select a 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 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 layout in the Application Extensions pane, then open the layout's Rule Sets tab, you'll see a list of the rule sets defined in that layout. In this example, you can see that the layout called ProfileOrgCardLayout uses one dynamic form. You can also see that the name of the rule set governing the dynamic form's display is called Organization Card:

Description of the illustration dynamicui-rulesets-tab.png

You would see more names in the Rule Sets tab if the layout used other dynamic forms or table. You click a rule set's name to open it in the Rule Set editor.

To set the display logic in a rule set:

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 Open Rule Set Editor in the Properties pane for the form or table .
   
   

   
   Description of the illustration designer-page-dyncomponent-properties.png

   
   

   In this image of the Properties pane, you can see the name of the dynamic component's rule set (Account Hierarchy Card Layout).

3. In the Rule Set editor, create a rule by clicking and giving 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.

   
   

   
   Description of the illustration dynamicui-rulesets-duprule.png

   
   

   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 select or enter a Value. Click Done.

   The Attributes dropdown list contains the 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. You can set the Value by typing in the field or selecting a value in the dropdown list. If a list of valid values for the attribute can be determined from the data source, the values will be displayed in the Value dropdown list. For example, if the service definition contains an attribute (Status) that can have three valid values ('Not Started', 'In Progress', and 'Completed'), the dropdown list would display these values.

   The Attributes variables are grouped by context in the list. In addition to the $fields context, there are variables in other built-in contexts that provide a way to access various pieces of information when building conditions for a rule. 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. Context variables include:

   • $fields variables determined by the fields displayed in the Fields editor. For example, the $fields.firstName.value lets you access the value of the First Name field in your data source. Look for these variables under the Fields group in the condition builder.

     Note:

     For each field, regardless of type, you can choose $numberValue (for example, $fields.ConflictId.numberValue()) or $value ($fields.ConflictId.value()). You should use $numberValue when you know the field's value should contain a number. For example, if the ConflictId field's type is a string and you choose $numberValue, the field's value will be converted to a number, if possible. If the value can't be converted, the $numberValue will be NaN (Not a Number).

     The only limitation is that $numberValue is limited by the maximum precision allowed by the Number type in Javascript.

   • $responsive variables determined by the screen size of the device the 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. Look for these variables under the Responsive group in the condition builder.
   • $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. You can use the user.roles variable to check the role of the user using the app. Look for these variables under the User group in the condition builder.

     Note:

     When using user.roles, the Value drop-down lists the available Oracle Applications Cloud job and abstract roles. (The drop-down will not list any duty roles. If you want to specify a duty role, you can manually type the duty role name in the Value field.)

   
   

   
   Description of the illustration dynamicui-rulesets-attributelist.png

   
   

   Note:

   A rule condition can also specify a discriminator sub-type value when the attribute is a polymorphic object. When you open the layout associated with a rule which specifies a sub-type, the object's sub-fields in the Fields palette will be filtered using that sub-type. For example, if a condition requires the Meal sub-type, when you open the rule's layout, the object's sub-fields will be filtered for that sub-type.

   If you want to edit or remove the filter, click Modify under the object in the Fields palette. To re-apply the filter using the same sub-type, click Reset according to Display Logic rule.

   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.

   
   

   
   Description of the illustration dynamicui-rulesets-addcondition.png

   
   

   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.
   
   

   
   Description of the illustration dynamicui-rulesets-ruleorder.bmp

   
   

   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.

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 lgOnly under Responsive in 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.
   
   

   
   Description of the illustration responsive-lg.png

   
   
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 (), 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 mdOnly attribute to show the MediumScreen layout when the current user's screen size is medium and the 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).
   
   

   
   Description of the illustration responsive-all.png

   
   
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.

Use Application and Page Parameters in a Layout

When using a layout on your page, you can pass the layout a context, including:

• values produced by your application that come from outside your layouts, such as page variables,
• details from other parts of the application,
• other values that might be useful when extending the application.

The context you pass to the layout must adhere to a contract defined by the base layout developer at Oracle. The contract specifies the valid context parameters that can be passed to the layout.

If any of these parameters are exposed in your app extension, you can access them in the $componentContext in a dynamic component's Expression Editor and in the rule set condition builder. The parameters in a component's $componentContext are available in all the rule sets in the component.

For example, there might be some preferences defined by the app that could be useful when creating a condition in a rule set. When you create the condition, you can select the parameters in the $componentContext in the condition builder's Attributes dropdown list. As you can see in this image of the Attributes dropdown list, $componentContext is prepended before the parameter names.

Description of the illustration dynamicui-rulesets-conditioncontext.png

You can see the list of valid $componentContext parameters in the Parameters tab in the Properties panes of rule sets and in a layout's Fields editor. The Parameters tab shows the name and type of each parameter. To see a parameter's description and the valid values, move your cursor over the tooltip icon which is displayed when you hover over the parameter name.

Note:

If you enter an invalid parameter value in the Expression editor or condition builder, a warning will be displayed in the layout's JSON file.

In a rule set's Properties pane, the Parameters tab lists the parameters in the component context that you can use in the rule set.

Description of the illustration dynamicui-rulesets-parameters.png

If you don't see any parameters in the Parameters tab, this means that the base app has not defined any $componentContext parameters for the component.

Description of the illustration dynamicui-rulesets-noparameters.png

In a layout's Fields editor, the Parameters tab lists the parameters in the base component context that you can use in the layout. You can use parameters in the base component context to pass information to your layouts as well as to the service definition, for example, to add parameters to the query used to call your Cloud Application service.

The Parameters tab is displayed in the Fields editor's Properties pane when no field is selected, and will list the available base component context parameters.

Description of the illustration dynamicui-fieldseditor-parameters.png

Preview Different Dynamic Layouts

To preview how different layouts will look when applied to your page, use the Layout Preview in the Properties pane. 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 Properties pane 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 dropdown 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:
   
   

   
   Description of the illustration designerlayout-preview.png

   
   

   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.

Using Field and Form Templates

You can customize how a dynamic form is rendered on the page by editing form 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 layout.

The base app 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 base app has applied a template called BoldType to the Update field. If you do nothing, 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 layout.

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

1. Open the layout'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 .

   
   

   
   Description of the illustration dynamicui-templates-tab-field.png

   
   
2. Click and select Field in the dialog.
   
   

   
   Description of the illustration dynamicui-templates-newfield.png

   
   
3. Specify the Label and ID. Click Create.

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

   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 the illustration dynamicui-templates-field.png

   
   
4. 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 the illustration dynamicui-templates-field-general.png

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

   
   

   
   Description of the illustration dynamicui-templates-field-event.png

   
   

   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="altNameTemplate">
     <span class="vb-icon vb-icon-image"></span>
     <oj-input-text value="{{ $value }}" label-hint="[[ $metadata.labelHint ]]"></oj-input-text>
   </template>

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

Apply a Template to a Field

To apply a template to a field in a layout:

1. In the rule set editor, open the layout you want to work on.

   The center pane of the layout editor lists the fields that will be displayed in the layout and the templates that are applied to them. If you duplicated an existing layout, your new layout might already list some fields, or have templates already applied to fields.

   
   

   
   Description of the illustration dynamicui-layout-editor-fields.png

   
   
2. Select the field in the center pane.
3. Select a template from the Template dropdown list in the Properties pane.

   If no template has been applied to the field (as in this image), you can select a template in the list. You can also click Create to create a template for the field in the template editor.

   
   

   
   Description of the illustration dynamicui-layout-editor-notemplate.png

   
   

   If the field already has a field template applied to it (you'll see the template name next to the field name), you can still select a template in the list unless a default template has been defined for the field. You'll see a notification in the Properties pane and an Override button if a default field template has been defined.

   
   

   
   Description of the illustration dynamicui-layout-editor-override.png

   
   

   If a default template has been defined for the field, click Override in the Properties pane, and then select the template from the dropdown list.

   
   

   
   Description of the illustration dynamicui-templates-field-override.png

   
   

   At any time you can click Reset in the Properties pane if you want to re-apply the default template.

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 Properties pane, or set if in the rule set's Templates tab in the Properties pane.

Set a Default Field Template for a Rule Set

In addition to applying templates to fields in individual layouts, you can set the default field template for a rule set in the rule set's Properties pane. The default field template will be applied to the field in every layout in the rule set. After a default field template is applied to a field, you'll need to override it if you want to change the field's template in an individual layout.

To define a default field template for a field in a rule set:

1. Open a rule set in the editor, then open the Templates tab in its Properties pane.

   The Templates tab lists all the fields in the layout that have a default template applied to them. A field's default template might be defined in the base app (Built-in default field templates) or in the extension.

   
   

   
   Description of the illustration dynamicui-rulesets-templatestab.png

   
   
2. Click + Default Field Template.
3. Select the field that you want to apply the template to.

   You can select a field that already has a default field template applied in the base app if you want to override it.

4. Select the template that you want to apply to the field. Click Confirm.
   
   

   
   Description of the illustration dynamicui-rulesets-templateselect.png

   
   

In the Templates tab, the new default field template mapped to the field is added to the list of default field templates defined in the extension. In this image, in the list of Built-in default field templates, the BusinessUnitName template is crossed out to show it's been overridden by a template defined in the extension. You can remove any default field template mappings that you create by clicking next to the mapping in the list.

Description of the illustration dynamicui-rulesets-templatedefault.png

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 layout.

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

To start an action chain from a field:

1. Open the Templates editor of your layout 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 Add New Event in the Events tab and select the Quick Start option in the drop-down list.

   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

   
   

   
   Description of the illustration dynamicui-templates-field-addevent.png

   
   

   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. You can also add more events to the text field.

4. In the Action Chain editor, define the action chain properties

   In the action chain's Properties pane, you can edit the default ID, add a description, and configure the action chain's input parameters and return type.

   
   

   
   Description of the illustration dynamicui-templates-field-action.png

   
   
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 can 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 the illustration dynamicui-templates-field-newevent.png

Video: Customize the Fields in Your Dynamic Layout

This video shows how to create field templates and how to create your own custom fields.

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. The template can be one of the built-in templates defined in the base app, or it could be your own form template. 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 form to always display a Rating Gauge component, regardless of which fields are defined in the layout. You could create a 'Leads' 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 layout, but templates can't be shared between layouts.

To create a form template for a dynamic form:

1. Open the layout'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 .

   
   

   
   Description of the illustration dynamicui-templates-tab.png

   
   
2. Click and select Form in the dialog.
   
   

   
   Description of the illustration dynamicui-templates-createform.png

   
   
3. Specify the Label and ID. Click Create.

   The new template opens in the template designer. The template designer contains a Components palette, Structure view, canvas and 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 the illustration dynamicui-templates-form.png

   
   
4. While Form Template is selected in the editor, click Add item in the Extra section in the Properties pane.

   The Extra fields are fields that are defined in the template, not the layout. Each field you add in the Extras 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 altName field to the template as an Extra.

   
   

   
   Description of the illustration dynamicui-templates-addref.png

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

   
   Description of the illustration dynamicui-templates-formdesigner.png

   
   

   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 a Input Text component that was positioned above the Additional Fields template in the Form Layout.

   
   

   
   Description of the illustration dynamicui-templates-form-structure.png

   
   
6. 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 to open the Expression Editor, or to open the Variables picker.

   
   

   
   Description of the illustration dynamicui-templates-bindcomponent.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 form:

1. In the Rule Sets 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 the templates that are applied to them.
2. While the form is selected, click Use Template in the Properties pane.
   
   

   
   Description of the illustration dynamicui-templates-selecttemplate.png

   
   

   If a template has already been applied to the form and you want to switch to a different one (or remove it), click Select in the Properties pane. The list of templates will include form templates defined in the base app as well as the templates you've created.

   You can click Create in the Properties pane if you want to create a new form template. For more on using templates with a form layout, see Control How a Form Layout is Rendered.

3. Select the template you want to apply in the Use Layout Template window. Click Select.

   The Use Layout Template window lists the available templates you can apply to your form layout. You can also select Create a New Template to create a new form template.

   
   

   
   Description of the illustration dynamicui-templates-selecter.png

   
   

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 (NewOrganizationCardLayoutTemplate) and the fields defined by the template (altName, origin).

Description of the illustration dynamicui-templates-appliedttemplate.png

You can't edit templates defined in the base app, but you can edit the fields defined in templates you've created. You can click Go to Template in the Properties pane to open the template in the editor.

If the template contains a field you don't want to appear in your form, you'll need to select a different template, or click Select to open the Use Layout Template window, and then select No 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 might 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 layout in the Application Extensions pane, then choose the dynamic form; click the form on a rendered page in the canvas area; or select it from the Properties pane.

   
   

   
   Description of the illustration dynamicui-rulesets-tab.png

   
   
2. Open the form you want to edit.

   You can use buttons in the toolbar to duplicate the current layout (), to copy selected fields in your current layout to another layout (), and to copy fields from another layout into the current one ().

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 in the toolbar.
   
   

   
   Description of the illustration dynamicui-rulesets-groupfields.png

   
   

   The selected fields are grouped under a new folder in the layout diagram:

   
   

   
   Description of the illustration dynamicui-rulesets-formgroup.png

   
   
5. Type a name for the new group by naming the folder in the layout diagram. Click 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.

Create Fields For a Layout

You can create fields in your layout if you'd like to use a field that isn't defined in your Oracle Cloud Application. You can set the fields to variables, or to expressions that reference other fields available in the layout.

You can see the list of fields you can use in your layouts in the Fields editor. This list will contain any fields you create, but most of the fields will be defined by your Oracle Cloud Application. The service provides a service definition, such as an OpenAPI3 definition, that describes the fields and properties. Service definitions determine the Oracle Cloud Application fields and properties that you can use in your layouts, and the base app defines the service definitions that your app extension uses.

Note:

Creating a field in VB Studio doesn't create a field in your Oracle Cloud Application. You need to use App Composer to create custom fields in your Oracle Cloud Application. For details, see Add Objects and Fields in Configuring Applications Using Application Composer.

Your app extension can't create or modify the fields in your Oracle Cloud Application, or the service definition used by your app extension, but it can override some field properties, such as "Read Only" and "Required". So if a field's Required property is set to False in the service definition, in your app extension you can override the property to make it more strict and set it to True. This won't change the description in the service definition, where the property will still be set to False. However, you can't override a property to make it less strict, meaning you can't set a Required property to False if it is already set to True in the service definition.

If the fields defined in the service definition don't meet your needs, you can create calculated fields and 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. To create a virtual field, see Create a Virtual Field below.

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 calculated 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, then click the Fields tab.
   
   

   
   Description of the illustration dynamicui-custom-field.png

   
   
2. Click Custom Field.
3. Type a label for the field (the field's display name). When you type in the label field, 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 Referenced Field, then select a field in the list. Click to add it.

   You can add any field available in your layout, including the sub-fields of fields with an object type. If you add one or more referenced fields, you won't see the Default Value property in the Properties pane because the Value property is now used to specify the expression.

   If you set a calculated field to Read Only, you set the field's value or expression in the Value field (there is no Default Value for read-only fields)

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 the illustration dynamicui-custom-field-picker.png

   
   

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

   
   

   
   Description of the illustration dynamicui-custom-field-editor.png

   
   

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

   
   

   
   Description of the illustration dynamicui-custom-field-properties.png

   
   
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.

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 MemberOfDepartment.

Description of the illustration dynamicui-custom-field-list.png

Create a 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 rule set layouts. For example, you can create a single field that combines several contact details that are stored in different fields in your layout. 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 need to 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 virtual field:

1. Open the Fields tab of the dynamic table or form you want to work with.
2. Click Custom Field and type a label for the field (the field's display name).

   When you type in the label field, a suggested ID is generated for you. The ID can't be changed later.

3. Select the Object (Virtual Field) type. Click Create.
   
   

   
   Description of the illustration dynamicui-custom-virtual-create.png

   
   
4. In the Properties pane, click Add and select the fields you want to include as reference fields.

   You can add any of the available fields as reference fields, including sub-fields of objects.

   
   

   
   Description of the illustration dynamicui-custom-virtual-addref.png

   
   
5. Select a field in the Sort By dropdown list to define the field that should be used for sorting when the virtual field is used in a table.

   Only one field in a virtual field can be used for sorting. For example, if the virtual field FullName consists of a FirstName and LastName field, select LastName if you want it to be used when the table is sorted by FullName. The Sort By field will be used for sorting regardless of how the virtual field is rendered in the table by the template. (Remember, you need to use a field template to display a virtual field).

   The table won't be sortable by the virtual field if you don't select a Sort By field.

6. In the Rule Sets tab, open the rule set layout where you want to add your field.
7. 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.
8. While your virtual field is selected, click Create in the Properties pane and type a name for the template in the Label field. Click Create to open the new template in the editor.
   
   

   
   Description of the illustration dynamicui-custom-virtual-template.png

   
   

   You need to 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 dropdown list. You'll need to create one if no template exists.

9. 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.
10. 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 rule set layouts. When adding the virtual field, you can apply the same field template, or create additional field templates to apply to the virtual field.

Add Converters and Validators to Fields

You can add converters and validators to fields, 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:

• Built-in Oracle JET converters
• Built-in Oracle JET validators

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.
   
   

   
   Description of the illustration field-validator-converter.png

   
   

   A default option is selected based on the field's type. For example, the default validator for an employee's Email field that uses the Email format is the Expression Validator:

   
   

   
   Description of the illustration field-converter-default-example.png

   
   
3. Change the type if needed, enter additional details, then click Add Validator or Add Converter.

   The details you'll need to enter will depend on the validator or converter you use, so you might need to consult the samples and documentation for the specific options. Use the JSON editor if you want to add options other than those shown on the UI. For the Length Validator shown here, the options specify how to count the characters and the minimum and maximum string lengths allowed:
   
   Description of the illustration field-validator-example.png
   

   You can also create your own validator or converter by selecting the From Code option. With this type, the path field specifies the location of a JavaScript file that implements the custom validator or converter; the name field specifies the name of the constructor; and the Option field specifies the options specific to the custom validator or converter, for example:
   
   Description of the illustration field-converter-custom-example.png
   

   In this example, the RelativeDateTimeConverter JS file implements a converter with a constructor named RelativeDateTimeConverter and a relativeField option whose value can be, for example, day, week, month, and year. The implementation would convert a date value like 2014-01-02T20:00:00 to a relative date value, like Today, Tomorrow, This Week, Next Week, and so on, based on the value of the relativeField.

   It's possible to update your validator and converter options any time after they've been added. Hover near the validator or converter name, click , and make your updates. You can add as many validators as you want, but a converter can only be replaced because a field can have only one converter.
   
   Description of the illustration field-validator-converter-properties.png