Adding a Component to a Page

You build pages in the Page Designer by dragging components from the Components palette and positioning them on the canvas to create business objects, design forms and to organize page elements.

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. For example, Common components and Layout components can be added to any page, but Field components can only be added to form pages associated with a business object because field data is stored in a business object. A Not Allowed indicator is displayed when you try to place a component on the canvas where the component is not allowed.


Description of pagedesigner-component-blocked.png follows
Description of the illustration pagedesigner-component-blocked.png

Note:

Components cannot be positioned inside a Table component.
To add a component to a page:
  1. Open the page you want to build in the Page Designer.
  2. Open the Components Palette.
  3. Drag the component from the palette and place it on the canvas.
  4. Select the component and modify its properties in the Property Inspector.

Most pages in your application will be associated with a business object. An example of a page that is not associated with a business object is the landing page that is created when you create your application. Typically you will create a new parent business object by dragging a Collection component onto a landing page, associating the page with the business object in the process. The form pages for creating, editing and displaying details of business objects are examples of pages that are associated with a business object when they are created. By default, Field components that are added to a form will reference new or existing fields in the associated business object.

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

Component Type Description
Common The components in the Common section are basic page elements that are not associated with business objects. Common components can be placed almost anywhere on the canvas and on any type of page.
Field The components in the Field section 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 reference an existing field in the business object.
Collection The components in the Collection section are associated with a business object and are used for displaying business object data, for example, a table with a row for each business object. When you add a collection component to a page you need to map the component to an existing business object or create a new business object in the wizard.

You can create a child business object by dragging a Collection component into a form page.

Layout The components in the Layout section are containers for organizing elements on the page, for example, to create panels or tabs within a page. Layout components can be placed on any type of page
Chart The components in the Chart section 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 section 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.
Media The Image element in the Media section is used to add images to the page. When you drag the Image element onto the canvas you are prompted to upload an image or select an existing image from the library. Image components can be added to any page.
Custom The Custom Code component in the Custom section is used to add custom code to the page. When you drag the component onto the canvas you can enter your custom code in the Property Inspector. Custom Code components can be added to any page.

About Component-level Accessibility

The standard components in the Components palette of the Page Designer are Oracle JavaScript Extension Toolkit (JET) components that are designed to be accessible. In most cases you do not need to do anything to add accessibility other than to provide meaningful labels for the components and possibly other properties.

Oracle JET components provide support for keyboard and touch navigation, zoom, screen readers and component roles and names. Some JET components also support accessibility and navigation using specific keystrokes and gestures. For Oracle JET components, the Oracle JET JavaScript API reference documentation contains an Accessibility section that provides information about each component's accessibility features and requirements. See Using the Accessibility Features of Oracle JET Components.

If your application uses any custom components you will want to consult the components’ documentation for details about features that support accessibility.

Adding a Table to a Page

Use the Table component in the Components palette to display business object data in a table format.

After you drag a table component onto the canvas, use the Table Creation wizard to associate the table with a business object and set the table properties and options. You can associate the table with an existing business object or create a new business object.

To add a table to a page:

  1. Locate the Collection section in the Components palette.
  2. Drag the Table component onto the canvas.
    When you drag the component onto the canvas the Table Creation wizard opens in the Property Inspector.
    Description of page-designer-createtable.png follows
    Description of the illustration page-designer-createtable.png
  3. In the Data step of the wizard, select an existing business object or click New Business Object and enter a name to create a new business object.
    Selecting a business object will take you to the next step in the wizard.

    Note:

    When you create a new business object in a create, edit or detail form, the new business object will be a child of the business object associated with that page.
  4. In the Mapping step, drag fields from the Available list into the Selected list to create a column in the table for the fields. Click Next.
    The Selected list must contain at least one field. To create a field in a custom object, click New Field and specify a name and data type. You can also add fields to custom objects in the Page Designer and Data Designer.
  5. In the Object Actions step, select the actions that you want enabled. Click Next.
    Forms for creating, editing and viewing objects are automatically created when the actions are enabled. Enabling the Create action adds a Create button above the table. Enabling Edit, Delete and Details enables the links for the function in the Actions menu in the table. You can use the Property Inspector to enable actions if you do not enable them in the wizard.
  6. In the Options step, select the filtering and sorting options that you want to enable.
    You can modify the option settings later.
  7. Click Finish.
When you click Finish the new table appears on the canvas and is populated with data from the business object, or sample data if you are creating a new object. If you select the table on the canvas you can modify the properties and settings for the table in the Properties Inspector.

Customizing Table Layouts

You can customize the display and formatting properties of individual table columns in the Property Inspector. You can also create new columns in the Property Inspector, or by dragging a data field from the Data Palette onto the table. When a column is selected, the Property Inspector shows properties specific to this column and allows the user to customize Column Title, Column Width, Text Alignment, Action, and value formatting options for some of the field types. To customize a table column, click on the column you want to customize, or select the column in the Data tab of the table’s property inspector.

To customize the column:

  1. Use the Column Title to set the text of the column title.
  2. In Column Width,select Auto if you want the column width to respect the largest value on the current table page, or Pixel if you want to specify a fixed width for the column. If you select Pixel you will be able to choose from two formatting options:
    • Ellipsis, which will render the value on one line, or 
    • Wrap, which will render the full value of each item, adjusting the table row height as needed.
  3. In the Action tab, configure any actions associated with the column. See Defining Actions in Tables and Lists.
  4. In the Style tab, set the Text Alignment to Left, Center or Right. By default, numeric fields are aligned right, and all other fields are aligned left.

    Description of pagedesigner-style-tablecolumn.png follows
    Description of the illustration pagedesigner-style-tablecolumn.png

    You can adjust the Value Formatting, including decimal places, trailing zeros, and the thousands separator for the following table column field types: number, percentage, currency, datetime, date, or time.

    For URL fields that contain a link to an image, you can use the Display As property to choose if the field is displayed as text or as an image in the table. You can set the width and height if you are using the field to display an image


    Description of pagedseigner-properties-urlfield.png follows
    Description of the illustration pagedseigner-properties-urlfield.png
  5. To change the order in which a selected column appears, drag it to the left or right.
Your changes will be saved and displayed as you make them.

Adding a List to a Page

Use the List View component in the Components palette to display business object data in a list format.

After you drag the list view component onto the canvas, use the List Creation wizard to associate the list with a new or existing business object and set the list properties and options.

To add a list to a page:

  1. Locate the Collection section in the Components palette.
  2. Drag the List View component onto the canvas.

    When you drag the component onto the canvas the List Creation wizard opens in the Property Inspector.

  3. In the Data step of the wizard, select an existing business object or click New Business Object and enter a name to create new business object.

    Note:

    When you create a new business object in a create, edit or detail form, the new business object will be a child of the business object associated with that page.
  4. In the Layout step, select a layout option for the list. Click Next.
  5. In the Mapping step, drag a field from the list and position it in the desired section on the canvas. Repeat for each field that you want to be displayed in the list.
    Description of page-designer-createlist.png follows
    Description of the illustration page-designer-createlist.png
    To create a new field, click New Field and specify a name and data type. Click Next.

    If you are creating a new business object you can create as many fields as you need. You can also create additional fields later in the Data Designer and drag the new fields from the Data palette into the List component on the page. Alternatively, you can drag a field component from the Components palette into the List component and bind it to an existing field.

  6. In the Object Actions step, select the actions that you want enabled. Click Next.

    All actions are enabled by default. When the Create action is enabled the page will contain a Create button above the list. Forms for creating, editing and viewing objects are automatically created if the corresponding actions are enabled. Enabling Edit, Delete and Details enables the links in the Actions menu. You can enable actions later in the Property Inspector.

  7. In the Options step, enable any filtering and sorting options.
  8. Click Finish.
When you click Finish the list element appears on the canvas and is populated with data from the business object, or sample data if you are creating a new object. When the list is selected on the canvas you can modify the properties in the Property Inspector.

Defining Actions in Tables and Lists

You can use the Actions tab in the Property Inspector for Table and List components to configure the predefined and custom actions.

The Actions tab displays a list of actions that are defined for the component. Each collection component has several predefined actions available. In addition to these predefined actions, you can create and edit custom actions.

To create a custom action:

  1. Click Add Action.
  2. Click Add Custom Action.
  3. Enter an Action Name for your custom action, then click Menu Item or Toolbar Button to select its location.
    The Configure Action dialog opens.
  4. Drag an action from the list of available actions to the recipe area. Edit its configuration if required.
  5. Optionally, repeat the previous step to add additional actions to your custom action.

    Note:

    You can customize the action behavior with your own JavaScript code. SeeAbout Configuring Button Actions for more information.
  6. When you have finished creating your custom action, click Done.
Your custom action will be saved and can be viewed in the component’s Property Inspector.

Adding a Chart Component to a Page

You can use a chart component to add a visual representation of a business object.

Tutorial iconAdding a Chart to a Page Tutorial

A chart is useful to visually represent multiple fields in a business object. When you add a chart to a page you select three fields (or more in the case of a bubble chart) that contain the data that you want to display in the chart. For example, if you wanted to display growth over time for a category you might want to choose a line chart. When you create the chart your business object would need to have fields containing values such as the growth index, an interval and a category identifier. The chart could display the growth information for each category. You could also create a default query in the Property Inspector to filter the data displayed in the chart, for example, to limit the categories displayed in the chart.

You select the business object and the fields that you want to display when you drag the chart onto the canvas. In pages with a collection component or used for viewing business objects, you can select the business object associated with that page, but you could also choose a different business object with relevant data. The chart can display data stored in any of the business objects available in your application, but it cannot display data stored in multiple business objects. Access controls used to secure the data in the business object also apply to the component. Chart components are always read-only.

The following table describes the chart components that are available in the Components palette.

Chart Types Description

example of Bar Chart
Bar Chart

Bar charts are useful when you want to compare values across categories or over time. You can also stack the charts when cumulative values are important.


example of Line Chart
Line Chart

Line charts are useful when you want to visualize trends in a set of values over time and compare these values across series. Consider using an Area chart to display cumulative values.


example of Area Chart
Area Chart

Area charts, like Line charts, are useful when you want to visualize trends in a set of values over time and compare these values. Choose the stacked option for the chart when cumulative values are important.


example of Pie Chart
Pie Chart

Pie charts are useful when you want to visualize the parts of a whole. Pie charts do not display zero or negative values so they are not recommended for data sets that may have negative or null data.


example of Funnel Chart
Funnel Chart

Funnel charts are useful when you want to view data for stages of a process, such as the stages of a sales process. The area of a funnel slice is proportional to its value for the corresponding stage.


example of Donut Chart
Donut Chart

The Donut Chart is similar to the Pie Chart except that you can add text to the center.


example of Bubble Chart
Bubble Chart

Bubble charts define data items using x, y, and z values, making them useful for viewing relationships between 3 dimensions. However, 0 or negative values should not be used for the z value.

To add a chart component to a page:
  1. In the Page Designer, open the page where you want to place the chart component.
  2. Drag the chart component from the Components palette and position it on the page.

    You can add chart components to any page, including pages that are not associated with a business object. A dialog box for choosing the business object and fields opens when you add the component.


    Description of chart-palette.png follows
    Description of the illustration chart-palette.png
  3. Select the business object in the dropdown list and select the fields that you want to display in the chart. Click Create.

    The Business Object dropdown list displays the available business objects in your application. The other values in the dialog box depend on the type of chart you are adding.


    Description of chart-dialog.png follows
    Description of the illustration chart-dialog.png
  4. In the Options tab in the Property Inspector, specify the display options, label position and any other options for the chart.
    The options available depend on the type of chart. You can experiment to find the most suitable display options for your data. The chart is updated on the canvas each time that you modify the options.
    Description of chart-properties1.png follows
    Description of the illustration chart-properties1.png
  5. In the Data tab of the Property Inspector you can modify the chart values that are mapped to the fields in your business object.
    The chart on the canvas is updated each time that you change the settings. You can also change the business object.
    Description of chart-properties2.png follows
    Description of the illustration chart-properties2.png

    You can set the display to a plain value or an aggregation. If you select Aggregation, the options change to allow you to specify the aggregation function, which can be Count, Average, Maximum, Minimum, or Total. For all functions but Count, you specify the field that function is applied to. Finally, you specify the Group By field.
    Description of chart-properties3.png follows
    Description of the illustration chart-properties3.png

    You can create a Default Query to limit the items that are displayed in your chart.
    Description of chart-default-query.png follows
    Description of the illustration chart-default-query.png

  6. In the Responsive tab you can set the visibility of the component and the location of the legend for various screen sizes.
    When you change the screen size in the dropdown list the canvas changes to the new screen size.
  7. In the Roles tab you can set the visibility of the chart to each of the roles defined for the application. By default, it is visible to all roles.

Adding a Gauge Component to a Page

You can use a gauge component to add a visual representation of a value in a business object.

A gauge visually represents a single value. For most gauge components you can also configure a range of values and use the gauge to illustrate the position of the value within that range. For example, a value might represent the number of sold items and you could use a gauge to visually illustrate the number of sold items relative to the total number available.

You select the business object and the value you want to display when you drag the gauge onto the canvas. In pages with a list component or used for creating, editing and viewing business objects, you will usually want to select the business object associated with that page, but you can choose any business object available in your application. In edit or create pages you can use the Status Meter and Rating gauges to update values. When you use a gauge in a list component the gauge is always read-only.

The following table describes the gauge components that are available in the Components palette.

Gauge Example Description

example of Linear Status Meter

example of Circular Status Meter
Status Meter

Use the Status Meter gauges to display the status of a value within a range. You need to specify the minimum and maximum values for the range in the Property Inspector. You can also define various thresholds and threshold styles to provide additional visual indicators. For example, by creating a threshold with a value of 1000 and the color blue, the indicator will be blue if the value is below the threshold. You can also use a reference line to identify thresholds at a specific value.

Status Meter gauges are interactive and can be used to update a value.


example of Rating Gauge
Rating Gauge

Use the Rating gauge for a very coarse rating value, for example, to display or accept user feedback on a product. You might want to add a verification rule for this field because the maximum whole number value that can be displayed is 5.

Rating gauges are interactive and can be used to update a value.


example of LED Gauge
LED Gauge

Use an LED gauge to display the value as a number and can be used to call attention to a specific value in relation to a threshold. For example, by creating a threshold with a value of 1000 and the color blue, the color of the gauge will be blue if the value is below the threshold.

To add a gauge component to a page:
  1. In the Page Designer, open the page where you want to use the Gauge component.
  2. Drag the gauge component from the Components palette and position it on the page.
    You can add gauge components to pages associated with a business object, such as create and edit pages, into cells in List collections, and to pages that are not associated with a business object. You specify the business object in the dialog box when you add the component.
    Description of gauge-palette.png follows
    Description of the illustration gauge-palette.png
  3. Select the business object and the value field in the business object. Click Create.
    If you are adding a Status Meter gauge you can specify the minimum and maximum values for the range in the dialog box or later in the Property Inspector.
  4. In the Options tab in the Property Inspector, specify the label, label position and any other options for the gauge.
    The options available depend on the type of gauge.
    Description of gauge-linearmeter-dialog.png follows
    Description of the illustration gauge-linearmeter-dialog.png
  5. In the Database tab of the Property Inspector, specify the threshold settings for the gauge and any other settings.
    The gauge on the canvas is updated when you change any settings.
    Description of gauge-propertiessm.png follows
    Description of the illustration gauge-propertiessm.png
  6. In the Responsive tab you can set the visibility of the component for various screen sizes.

Adding an Oracle JET Composite Component to a Page

You can import an Oracle JET composite component to your application as an extension and then use it in your application pages.

For information on importing a composite component, see Importing a Composite Component Architecture (CCA) Component.

Note:

Oracle JET composite components are currently not backward-compatible. When importing composite components, and when upgrading composite components or your app, you need to ensure that your application and all composite components that you use in your application are using the same version of JET. The JET version for the current release is listed under Supported Oracle JET Version in What’s New for Oracle Visual Builder.

To add a composite component to your application:

  1. Select Application Settings from the main menu, then select Extensions.
  2. On the UI Component page, select your composite component and click the Overview tab if you are not already on the Overview page.
  3. Activate the component by clicking the Extension Active toggle button, if it is not already activated.
    Description of cca-activate.png follows
    Description of the illustration cca-activate.png
  4. Select Page Designer from the main menu.
    The component icon appears in the Components Palette under Common.
  5. Drag the component onto the page where you want to put it.
    Description of cca-add-page.png follows
    Description of the illustration cca-add-page.png
    If you wish, you can first create an enclosing component, such as a List, and drag the component into it. If a popup appears, change any property values you want to.
  6. Click the component and look at the Property Inspector to view the editable properties of the component.
    Description of cca-properties.png follows
    Description of the illustration cca-properties.png
  7. Click the Data tab and the Actions tab, which may not have any content.
    Composite components are usually not bound to a business object, and they often lack associated actions. You can create a business object to hold data and set up the application to display content. You could also specify event handling for the Actions tab.
  8. Click the Design/Live toggle button and test the component features.

Adding a Multi-Select Component to a Page

If you create a business object that has a many-to-many relationship with another business object, you can use the multi-select component to allow users to specify values.

For example, if an Employee can be assigned to multiple Projects and a Project can have multiple Employees assigned to it, you can drop a multi-select component onto the Create Employee and Edit Employee pages and specify Project values in the pop-up creator dialog box. The component can also be used in detail pages.

To add a multi-select component:

  1. Locate the Field section in the Components palette.
  2. Drag the Multi Select component onto the canvas.
  3. In the pop-up creator dialog box, specify the Label, the Target Business Object, and the Display Property. The Intersection Object, Source Reference, and Target Reference fields are automatically filled in.
    Description of page-designer-multi-select1.png follows
    Description of the illustration page-designer-multi-select1.png
  4. Click Create.
To populate the component, the user selects from a drop-down list and can add as many values as the business object has.
Description of page-designer-multi-select2.png follows
Description of the illustration page-designer-multi-select2.png

See Viewing, Creating, and Editing Business Object Relationships for more information about many-to-many relationships.

Grouping Elements on a Page

You can organize the UI elements in your page using layout components.

The Layout section in the Components Palette contains components to help you separate and group elements on a page. Use the Tabs component to create tabs within the page. The Layout section also contains panel options for grouping components in specific areas within a page: a one-panel element, a two-panel element and a three-panel element. Panel elements can be used to create columns and rows in a page. Elements grouped in a panel will stay together when the page is responsively resized, and any UI elements in the panel are also automatically resized.

Note:

You cannot place a panel within another panel.
To group elements on a page with a panel component:
  1. Open the Components Palette (if not open).
  2. In the Layout section of the Components Palette, select a panel element, for example, a two-panel element, and drag the element to the canvas.
    When you drag a panel element onto the canvas, the panel element or elements will expand to fill the entire row of the canvas. For example, if you drag a two-panel element onto the canvas, each panel will take up one-half of the row.
  3. Select one of the panels on the canvas and resize the panel to four column-widths (33%).
    When you resize the panel, the remaining panel expands to eight column-widths. The canvas grid is 12 columns wide. When you add a panel to a row that already contains one or more panels, the other panels will resize to accommodate the new panel.
  4. Drag a one-panel element onto the canvas and drop it above or below the wider panel.
    You now have three separate areas on the canvas that you can use to organize elements.
  5. Drag elements that you want grouped together into the same panel.

Adding Custom Code to a Page

Use the Custom Code component to add your own code to the page.

If the components in the palette do not provide a function that you require, you can use the Custom Code component to add your own custom code to a page. Drag the component onto the canvas and add your HTML, CSS and custom JavaScript code in the text editors in the Custom Code window. In the HTML editor you add the markup code for the component and in the Model editor you add JavaScript code for the function by editing the model bound to the component. Each custom component has its own model and a unique Component Instance Property Name. The window also displays the code for the Page Model in read-only mode.

To add custom code to a page:

  1. In the Page Designer, locate the Custom section in the Components Palette.
  2. Drag the Custom Code element from palette and position the element on the canvas.
    The Custom Code editor opens in the Property Inspector.
    Description of page-designer-customcode.png follows
    Description of the illustration page-designer-customcode.png
  3. Add your code in one of the text editors.
    The Custom Code window contains three editors for adding custom code to the page. The Generated Page Model text box displays code for the page model and is read-only.
  4. Click Apply.
    When you click Apply the code is saved and the canvas is updated.
  5. Click Close.