Design Pages

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

Use the Page Designer

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

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


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

The Page Designer Toolbar

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

Toolbar Item Description
Component palette icon

Toggles the Component palette

Page Structure icon

Toggles the Page Structure view

Reload Page icon

Reloads the page

Page Input Parameters icon

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

WhoAmI icon

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

Device selector icon

Opens a menu for selecting the screen size represented by the canvas.

Zoom Canvas icon

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

Live / Design / Code toggle icon

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

Expand Property Inspector icon

Toggles the Property Inspector in the Page Designer.

The Page Editor

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

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

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

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

The Components Palette

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

You add an element to a page by dragging it from the palette onto the canvas. You can use the Components Palette button ( Components Palette icon ) in the Designer to toggle the Components Palette.


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

The Page Structure View

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

You use the Page Structure button (Structure View button ) in the Designer to toggle the Page Structure view. When you select a component in the Page Structure view, the component is also selected on the canvas and its properties are displayed in the Property Inspector. You can organize and re-position components in the page by dragging them into position in the Page Structure view and by dragging them directly onto the canvas. You can select multiple components to simultaneously re-position them in the Page Structure view, for example, to move them into a new container.



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

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



The Property Inspector

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

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

Activate Role-Based Application Preview

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

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

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


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

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



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

Work with Pages and Page Layouts

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

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

Create Pages

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

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

To create a new page in a flow:

  1. Open the Web Applications or Mobile Applications browser in the Navigator.
  2. Expand the node of the app where you want to create the page.
  3. Expand the flows node.

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


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

After a page is created, you can change the page title in the page's Settings editor.

Edit the App Header and Footer

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

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

To edit the app's header and footer:

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

About Containers and Layout Components in Pages

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

When you create a page it automatically has a preferred page layout container. This page layout can be either a Grid or a Flex layout, and you choose which one you want to use in the Property Inspector. Every component that you add to your page is placed in a row in the page's Grid or Flex layout, or in a layout component that you have placed in the page layout.

The Grid layout has a pre-defined 12–column grid and rows for aligning elements when you position them. You can add layout containers and components to rows to help organize and layout components in the page. You can place multiple containers within a single row, or automatically create a new row by placing a container or layout component above or below an existing row. For each row, you can modify its display settings in the Property Inspector to control the layout of the components within the row. The pages in your application incorporate responsive design to resize gracefully based on the size of the display area of the device.

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



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



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



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

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

Add a Container or Layout Component to a Page

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

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

To add a container or layout component to a page:

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

    When a container is dragged onto the canvas, the locations where the component can be placed are highlighted on the canvas.



    If you do not place the component in an existing row, a new row containing the component is created when you place it on the page.

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

Add Components to Pages

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

About Page Components

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

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

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

Component Type Description

Common

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

Field

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

Collection

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

Layout

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

Chart

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

Gauge

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

Picker

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

Custom

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

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

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

Component Properties Description
General

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

Data

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

Events

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

All

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

Quick Starts

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

Add a Component From the Components Palette

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

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

To add a component from the Components palette:

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

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

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

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

Add a Component Using Code Completion in the Code Editor

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

If you want to add an Oracle JET component that is not in the Components palette, you can use the Code mode in the Page Designer to edit the page’s HTML source to add the component to your page. The code editor provides code completion that can help you locate JET components and view details about each component’s properties.

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

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

    For example, when you start typing <oj-a in the editor, the code completion window appears with a list of component tags that match the text you type. You can select a tag in the window to add it to the HTML file.


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

Manage Component Visibility Using Conditions

You can use an oj-bind-if component to surround other components and set test conditions to control if the components are displayed on the page.

You can add an oj-bind-if component to your page by dragging it from the Components palette or by using the popup menu in the canvas or Page Structure view. After adding the component, you set the conditions for the component by entering an expression in its Test property in the Property Inspector. In the Page Structure view and in Code mode you can see the components that are surrounded by a oj-bind-if component.



The content surrounded by oj-bind-if is displayed in the page if the test condition is true. For example, you can use an expression that evaluates if the value of a page variable does not equal a predefined value. The surrounded content is displayed if the values are not equal (the expression is true), and hidden if the values are equal.

You can use the Temporary Override property of oj-bind-if to temporarily set the result of the test condition to True or False. For example, when designing your page, if some content is hidden on the canvas because the test condition result is False, you can use Temporary Override to set it to True so that the content is visible on the canvas, or select Off to temporarily disable the test. The setting is temporary and will revert to Off when you reload the page. You can set the Temporary Override in the Property Inspector or in the component's popup menu that you can open from the Page Structure view or canvas.



You can use oj-bind-if to dynamically control what components a user sees based on the user's role, for example, to hide buttons or navigational elements, by using $application.user.roles.role_name in the expression. You can set restrictions on entire pages, or just on certain components in a page.

The visibility of components based on roles is only enforced on the client, and the value of the role could be changed in the client. For this reason, in addition to hiding components, you should also use role-based security to secure the application and the data in a page.

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

  1. In Design mode of the Designer, locate the component that you want to control dynamically.
  2. Right-click the component on the canvas or in the Page Structure view and select Surround > If in the popup menu.
  3. Select the oj-bind-if component on the canvas or in the Page Structure view and open the Property Inspector.
    The component has the Test property that you use to set the condition. The default expression is [[True]].
  4. Enter the condition for the component in the Test field.

    You can type the condition in the Test field, or use the Expression Editor to help build an expression using available variables.



Add Events to Components

You define component behavior by adding types of events to the component and then selecting action chains that are triggered by the event.

The type of events that can be assigned depend on the type of component. Multiple events can be assigned to a component, and each event can trigger multiple action chains. When you add the event you can select an existing action chain or create a new one.

To add an event and action chain to a component:

  1. Select the component.

    Typically you want to assign events to elements such as buttons, menus and fields in form components. You can select the component on the canvas, in the Page Structure view or in Code view.

  2. Open the Events tab in the Property Inspector.

    The Events tab lists any events that are already assigned to the component.

  3. Click + New Event and select the Quick Start option to use the suggested event or New Custom Event to select an event to start the action chain.

    The Select Event dialog box displays a grouped list of types of events that can be assigned to the component. You can select an event type in the dialog box to display its description.


    Description of page-designer-inspector-selectevent.png follows
    Description of the illustration page-designer-inspector-selectevent.png
  4. Select the type of event you want to trigger the action chain. Click Select.

    After selecting a type of event you need to select the action chain that the event will trigger.


    Description of page-designer-inspector-selectchain.png follows
    Description of the illustration page-designer-inspector-selectchain.png
  5. Select an action chain from the list. Click Select.

    Alternatively, you can click New Action Chain to create a new action chain.

After an event is assigned to a component you can open the Events tab to edit the type of event, the action chain and any input variables.

To modify an existing component event, located the event in the Events tab and click Select to change the type of event assigned to a component, or click + New Event to add a new type of event. To select a different action chain, click Select in the Events tab, or click the name of the action chain to open it in the editor.

Add an Image to a Page

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

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

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

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

To add an image to a page:

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

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


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

Add an Icon Component to a Page

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

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

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

To add an Icon component to a page:

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

Add a Custom Style to a Component

You can add a style to a component and then define the style in your app's stylesheet.

You can apply style classes to page components to control how they are displayed. Some classes are already pre-defined in the app and are automatically applied to components when you add them to a page. Specific pre-defined style classes are applied to many Oracle JET components to ensure they display correctly and consistently. For example, if you look at the HTML for a Header component in a page's Code editor, you might see the following style classes applied to an h1 element: oj-flex-item oj-sm-12 oj-md-12. Pre-defined style classes used by Oracle JET components are prepended with oj-.

Note:

As a general rule, you should not override or modify the pre-defined classes or remove them from components. When defining and adding a custom class to a component, you should exercise caution to ensure that your class does not conflict with the pre-defined classes already applied to the component.

You can define your custom style classes in the app.css stylesheet of your app. An empty app.css stylesheet was created in your app by default and the link included in the header of the app's pages. You can apply classes to components in the Property Inspector in the Design view of the Page Designer or in the page's Code editor.

To add a custom style to a component:

  1. Open the page in the Page Designer and locate the component that you want to modify with a custom class.
  2. Type the name of the custom class to apply it to the component.

    When you select the component in the Design view of the Page Designer, you can add the name of the custom class in the class property field, which is usually located under the General Attributes category in the All tab of the Property Inspector. You can also add the name of the class to a component directly in the page's Code editor.



  3. In the Navigator, expand the css node in your app's resources folder and click app.css to open the stylesheet in the editor.
  4. Define the class in app.css.
Reload the page in the Page Designer to see the class applied to the component.

Filter Data Displayed in a Component

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

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

Note:

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

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

Attributes Description

attribute

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

op

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

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

value

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

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

Create a Filter for Component Data

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

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

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

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

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


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

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

    Tip:

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


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

    You configure the Assign Variables action to assign values to each of the attributes of the filter expression.


    Description of filter-action-assignvariable.png follows
    Description of the illustration filter-action-assignvariable.png
  4. Click Assign in the action property editor to open the Assign Variables window.
  5. Expand the Service Data Provider in the Target pane and select filterCriterion to open the Filter Builder.

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



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

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

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



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

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

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

Add Page Functionality Using Quick Starts

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

About Quick Starts

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

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

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


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

Add Data to a Table or List

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

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

The Add Data Quick Start does the following for you.

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

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


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

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


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

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

Use the Add Data Quick Start

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

To bind an endpoint to a collection component:

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

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

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

Add a Create Page With a Quick Start

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

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

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

  • Creates an action chain for navigating to a page.

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

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

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

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

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

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

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

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


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

Use the Create Page Quick Start

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

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

To add a page to create a new business object:

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

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

Add an Edit Page With the Quick Start

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

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

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

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

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

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

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

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

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

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

The Quick Start does the following in the Edit page.

  • Adds a form with fields bound to a variable.

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

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

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

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

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

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

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


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

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


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

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

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

To create an Edit page:

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

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

Add a Details Page With the Quick Start

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

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

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

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

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

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

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

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

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

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

The Quick Start does the following in the Detail page.

  • Adds a form with fields bound to a variable.

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

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

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

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

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

Use the Add Detail Page Quick Start

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

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

To create a Detail page:

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

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

Work with the Functions Editor

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

Any JavaScript code that you add will have a defined scope based on the editor where you write the code. If your code will only be called from within a specific page, for example, to load some data when the page loads, you can write your code in the Functions editor for the page. If you want to use some JavaScript functions that will be used on multiple pages, for example, loading libraries for customizing navigation elements or custom web components, then you will probably want to open the Functions editor for a flow or the application. You use the Call Module Function action in an action chain to call functions. For details, see Add a Call Module Function Action.

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


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

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

Note:

The auto-save function will not save a JavaScript file that has invalid code.