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.
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:
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:
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:
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:
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:
- In the Rule Set editor, open the dynamic table's layout
- 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.
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:
- To set a field to display as a text area in a particular form layout:
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.
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.
The fields will appear in the following order when the Lunch
sub-type is applied to the discriminator:
- lunch2 (added and positioned explicitly)
- ExpenseId (added and positioned explicitly)
- expenseLine1 (added using
@all
) - lunch1 (added using
@all
) - 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:
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
:
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:
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:
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.
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.
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.
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.
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:
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:
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:
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:
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.
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:
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.
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:
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:
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
).
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:
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:
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
.
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:
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:
To add a converter or validator to a field: