Simplifying User Experience Design

Oracle APEX simplifies designing experiences for users working with your application data.

In App Builder, creating and enhancing pages is productive, iterative, and immediate. You can create one using a wizard, or start with a blank page. Then, you use the APEX Page Designer to configure page elements and can run it at any time. Changes you save in Page Designer are instantly visible in the running page, so you can fluidly evolve its look and features. The APEX runtime executes your page definition, so there is no code generation or deployment step to wait for. You immediately experience the page exactly as users see it just by refreshing the browser.

With minimal effort and no low-level web developer skills, laying out your page is intuitive and adding interactivity is simple. Common tasks are straightforward, like defining list-driven items and items whose available choices depend on the value of others. Your pages look professional on desktop and mobile devices of any screen size and they can launch like native apps.

• Starting a New Application
  Create a new app from App Builder, then review its starter pages and page list.
• Creating Pages Quickly
  After creating a new application or editing an existing one, as shown below, the Create Page wizard shows a gallery of the most common page types.
• Working in Page Designer
  You create and enhance your application pages in Page Designer.
• Running and Iteratively Editing Pages
  At any time, you can run your page in the browser to use it like an end-user does.
• Adding Interactivity to Pages
  Add interactive behavior to your pages using Dynamic Actions.
• Universal Theme Design System
  Applications you build with Oracle APEX use a built-in design system called Universal Theme.
• Report Columns and Form Items
  Most region types have an associated data source with a set of columns APEX infers automatically.
• Cascading, List-Driven Items
  Apps often need end-users to pick one or more choices from a list of valid options, and sometimes the available items depend on a previous selection the user makes.
• Simple Layout for Any Screen Size
  Pages in your APEX application look polished and professional at any screen size with minimal effort.
• Launching Like Native Apps
  With a single click, you can let any user install and launch your APEX app like a native app.

Create a new app from App Builder, then review its starter pages and page list.

App Builder is your home base for working on applications in your workspace. As shown below, your existing apps display in a list with details, or using the View Icons toolbar button next to the Search field you can switch to an icon view.

To create a new application, click the Create button along the top.

To start simple, just enter an application name and click (Create Application). Every APEX application in your workspace has a numeric ID as well. You can choose a number, or use the available ID App Builder suggests.

Each page in an application has both a number and user-friendly "alias" to uniquely identify it. The page alias appears in the browser address bar when navigating to a page. Notice both show in the page list below. If you prefer seeing less detail about your pages, use the toolbar button next to the Search field to toggle to icon view.

Each page's icon in this view reflects its page type. In both icon and list views, when your application has more pages than will fit in a screenful, pagination links appear.

After creating a new application or editing an existing one, as shown below, the Create Page wizard shows a gallery of the most common page types.

After picking a page type, the wizard lets you start with sample data or select a data source. You can opt to include additional context with a breadcrumb as well as add an application menu entry. In a few clicks, you get a page you can iteratively enhance in the Page Designer and run anytime. For several of the report region types, the wizard also lets you create a related form page to create new rows, edit the data of a selected row, or delete rows no longer needed.

You create and enhance your application pages in Page Designer.

Page Designer includes tabs showing information about rendering, layout, dynamic actions, and processing. You use the Property Editor to configure settings for any component in these tabs. Additional areas like the component palette, search tab, and help tab add additional just-in-time assistance to let you quickly build the pages your apps require.

• Key Page Designer Areas
  The main areas of Page Designer you use to configure your page are the Property Editor and the Rendering, Layout, Dynamic Actions, Processing, and Page Search tabs. As you select one or more components in any of these tabs, the Property Editor updates to reflect your selection.
• Page Layout Based on Template with Slots
  Your chosen template defines the layout of each page. The template's named slots arrange the areas of the page that can contain visual components like regions, page items, or buttons.
• Adding Regions in Page Designer
  The APEX Page Designer's region palette includes all the region types you can drag and drop onto a slot in your page.
• Adding Items in Page Designer
  You can use the Page Items palette in Page Designer to add UI controls to the page.

At any time, you can run your page in the browser to use it like an end-user does.

When you run the page, it opens in a second browser tab, just next to the App Builder tab. This lets you see exactly how the page looks on any device or screen size. As shown below, the Smart Filters region in the example Patients page from the previous sections displays as a search field in the navigation bar at the top of the page.

You could try selecting a value of Approved from the Status filter and Lasik laser vision correction from the Initial Procedure filter. You'd immediately notice the search criteria appear as "chips" in the search field, and the Search Results cards region now shows only the patients whose Lasik Laser Vision Correction medical procedure request has been approved. However, you notice the map region continues to show pins for all patients, instead of only the eight (8) patients that match the search filter criteria.

You can quickly get the map's filtered display working by configuring interactivity in the page: when the cards region is refreshed, the map region should also get refreshed. You see how that's done in the next section.

Notice the developer toolbar APEX adds along the bottom of the page when you run pages from App Builder. To iterate quickly, simply click the (Page 8) button in that toolbar to open it in Page Designer. To edit a particular element of the page, click the (Quick Edit) button there, then click on the region or item in the page you want to edit. In either case, you immediately jump to the Page Designer in the right context to carry out your next page configuration change.

Add interactive behavior to your pages using Dynamic Actions.

Define one or more dynamic actions to run in response to an event that happens while a user interacts with the page. Common events include the change in value of a page item or selection of a list, the closing of a modal dialog, refreshing of a region, and many others. Button and menu clicks can use Triggered Actions. Handle all other events by defining a Dynamic Action event handler. APEX offers a large set of native dynamic actions that you can extend by using dynamic action plug-ins.

Some dynamic actions modify aspects of the page in the browser like showing or hiding items and enabling or disabling them. Other ones engage the APEX server to refresh a region's data or execute server-side code. Any actions involving a server request support declaratively sending the latest values of page items or report columns to the server. Just set the Items to Submit property to a comma-separated list of item or column names. While a report region's primary key column is always available to send, enable other columns' Available on Client setting as needed. Since the Execute Server-side Code dynamic action can also modify page item values, list any you want APEX to update in the page in the companion Items to Return property.

In the patients search page we're studying, recall that when the cards region is refreshed, the map region should also get refreshed. The event named Page Change [Cards] fires when a cards region is refreshed, so you can define a dynamic action related to this event to get the job done.

You'd start by selecting the Search Results region, and choosing Create Dynamic Action from the context menu. Then in the Property Editor you select the Page Change [Cards] event. You can give the dynamic action event handler a name like When Results Refreshed to make the intent more clear to colleagues who might have to enhance the page in the future. The set of built-in action types includes ones to hide or show elements, refresh elements, enable or disable elements, set or clear the value of items, execute custom code in the client or server, and many others. In this case, you need the one to refresh the Map region. So, you configure the type of the related action to be Refresh and set Map as the region to refresh. Those few clicks make the map automatically refresh whenever the cards region results change.

End users would definitely appreciate if the map would zoom and center itself around the filtered list of patients to display to save them having to do manual adjustments. Since a dynamic action is one of the kinds of plug-in components members of the APEX community can create and distribute, imagine you find a Center & Zoom Map Around Points dynamic action plug-in on apex.world or as part of a blog article or tutorial.

You can download and import it into your APEX app to put it to use. You select the Map region in the component tree and again choose Create Dynamic Action. You name this second event handler When Map Refreshed and set it to react to the After Refresh event on the Map region. Finally, you define the dynamic action to be of type Center & Zoom Map Around Points [Plug‑in]. The figure below shows the result in Page Designer.

Now at runtime, as shown below, as the end-user fine-tunes their patient search both the cards and map regions reflect the narrowed results, and the map adjusts to fit the remaining patients' locations into the view.

Applications you build with Oracle APEX use a built-in design system called Universal Theme.

Technically speaking, Universal Theme consists of HTML templates, Cascading Style Sheets rules, icons, images, and JavaScript libraries. However, APEX shields you from having to understand these technologies. It's only important to remember that these resources cooperate to automatically ensure a consistent, professional look to all the pages you create on any desktop or mobile screen size.

• Theme Styles
  Universal Theme comes with several pre-defined styles.
• Universal Theme Reference App
  Bookmark the Universal Theme reference app at oracleapex.com/ut to quickly consult a live reference for many aspects of APEX user interface development.
• The Role HTML and CSS Play to Format Data
  While Universal Theme lets you deliver great results without being an expert in web technologies, understanding the role HTML and CSS play is useful when customizing data formatting.

Most region types have an associated data source with a set of columns APEX infers automatically.

Page Designer makes working with the columns of report regions and grids easy, as well as with page items in a form region. This is true even when new use cases require updating your application data model.

• Configuring Report Region Columns
  If a region lets you configure settings on its data source columns, then they appear in Page Designer under a heading in the component tree.
• Synchronizing Column Changes
  If your region's data source needs to work with additional columns, or different set of them, your page can automatically adapt.
• Deleting or Commenting Out Columns
  Often, your table includes more columns than you need to show in a particular region. In that situation, you have two options: you can delete the column from the region's column list, or you can comment it out.
• Page Items in a Form Region
  When your page includes a Form region, the Page Designer detects and displays a page item for each column in the data source in the Region Body slot.
• Flexible Form Page Item Layout
  While report regions control the layout of their columns, form regions have a flexible layout.

Apps often need end-users to pick one or more choices from a list of valid options, and sometimes the available items depend on a previous selection the user makes.

For example, after picking a particular department the user might need to select an employee in that department. Oracle APEX makes list-driven page items easy to configure. It offers many different ways to visualize and select options, and simplifies defining cascading lists.

• List-Driven Items Available
  Your pages can use ten different kinds of list-driven items.
• Defining the List of Values
  When you create a list-driven page item, you define its list of valid choices either locally on the page item itself or by referencing a shared component List of Values by name.
• Configuring Cascading Lists
  When you need one page item's value to influence the list of choices in another list-driven item, you can easily configure this cascading effect.

Pages in your APEX application look polished and professional at any screen size with minimal effort.

Instead of focusing on exact positioning and sizing, you arrange regions and page items into a flexible grid of columns and rows. At runtime, your page elements respond automatically to the device's screen size by adjusting position and size to fit their relative layout to the space available. You test your page by running it. You see what users experience, with one-click access to Page Designer to make iterative refinements. Your live changes to browser width, or testing the page on different sized devices, give the immediate visual feedback you need to perfect your page.

• Flexible Grid of Columns and Rows
  Design a page's layout by arranging regions and page items into a flexible grid.
• Templates and Options Set Look and Feel
  Choosing from Universal Theme's available page templates, region templates, and item templates, you get professional results using a declarative approach. Each template offers options you can configure in Page Designer to fine-tune your page's look and feel.
• Nest Regions to Create Any Layout
  A region can contain other regions in addition to its primary content.

With a single click, you can let any user install and launch your APEX app like a native app.

By enabling the Installable switch in your application's Progressive Web App settings, you give users a simple installation experience on their smartphone or desktop. Your app icon appears in the device's Home Screen, in the Dock of their Mac, or in their Windows Taskbar. Tapping or clicking the icon launches a full-screen experience that looks and feels like other native apps on the platform. A key difference with progressive web apps is that your APEX app is always up to date, and you are always certain all users have your latest fix or feature.

You can try this experience yourself on your smartphone or desktop by visiting the Universal Theme Reference App at https://oracleapex.com/ut. As shown below, clicking the "cloud with download arrow" icon in the navigation bar opens the simple installation experience to guide you.

After the quick installation process, tapping the Universal Theme app icon on your Home Screen opens the app in full screen where it works and behaves like any other native iPhone app. The figure below shows one of the pages in the reference app used for finding icons. You can install the APEX Progressive Web App reference app at https://oracleapex.com/pwa in an identical way.

Your APEX app can use mobile device features like front-facing (selfie) cameras and mobile location, and take advantage of optimized mobile keyboards for searching and entering numbers, email addresses, phone numbers, and URLs. Check out the APEX To Go mobile sample app shown below at https://apex.oracle.com/go/apextogo to learn more about creating APEX apps that are optimized for the mobile experience.

The main areas of Page Designer you use to configure your page are the Property Editor and the Rendering, Layout, Dynamic Actions, Processing, and Page Search tabs. As you select one or more components in any of these tabs, the Property Editor updates to reflect your selection.

The Help tab works in reverse. By clicking on the name of any property in the Property Editor, the Help tab updates to display context-sensitive help about that particular setting.

• Rendering, Layout, and Property Editor
  In the default arrangement of Page Designer tabs, the Rendering tab is grouped together with the Dynamic Actions, Processing, and Page Shared Components tabs, and all present a tree of their respective contents.
• Configuring Settings with Property Editor
  You use the Property Editor to review and change the settings of components on the page.
• Configuring Dynamic Behavior
  Use trigger actions to configure dynamic behavior for buttons and menus, and event handlers in the Dynamic Actions tab to react to value changes, dialog closure, and other user interface events.
• Validation, Processing, and Branching
  Use the Processing tab shown below to review and declaratively configure what happens when the end-user submits the page.
• Searching Your Page
  The Page Search tab lets you search your page to find anything you're looking for.
• Help on Any Setting at Your Fingertips
  The Help tab shows detailed information about any setting you select in the Property Editor.

Your chosen template defines the layout of each page. The template's named slots arrange the areas of the page that can contain visual components like regions, page items, or buttons.

Page Designer shows the named slots where you can add user interface elements, and helps you understand their relative positioning. Use the Hide Empty Slots context menu option in the Layout panel to toggle whether slots display even when they contain no components.

The APEX Page Designer's region palette includes all the region types you can drag and drop onto a slot in your page.

After dropping a region type into a slot, use the Property Editor to assign it a meaningful name and to set other properties that influence its look and behavior. If the region defaults to showing built-in sample data, change its Location property to another option like Local Database to use your own application data. For more information on each type of region, see Supported Region Types in Oracle APEX App Builder User’s Guide.

Whether you jump start the process with the Create Page wizard or begin with a blank page, you add new regions to your page in the same way. Just drag one from the region palette and drop into a slot on the page.

Alternatively, you can create a region using the Create Region option on the context menu in the Rendering tree, then set the region type and the desired slot name in the Property Editor.

For example, suppose you need to create a page to let staff of a medical clinic search for patients. If you start with a blank page, you could begin by dragging a Cards region to the BODY slot of the page, naming it Search Results, configuring its data source to be the patients table, and using the Property Editor to select the patient table's columns to show on each card.

Next, you might drag a Smart Filters search region, drop it into the BEFORE NAVIGATION BAR slot at the top of the page, name it Search, and set it to filter the cards region. Finally, to also show the filtered patient results on a map, you could drop a Map region into the BODY slot to the right of the cards region, name it Map, and configure its data source to use the filtered results of the cards region. For more details on this technique, see Showing Search Results in Other Regions.

After performing these steps and choosing Hide Empty Slots from the layout context menu, your patients search page looks like the figure below.

The Page Designer panel on the left shows your page's components in a tree. The layout panel in the center is a visual representation of how regions and items are positioned relative to each other on the page. The Search region is at the top in the navigation bar, the breadcrumb in its appropriate bar, and the Search Results Cards and Map regions are side by side below that in the body of the page.

You can use the Page Items palette in Page Designer to add UI controls to the page.

Suppose we continue with the patients search page example from the previous section. After adding regions to the page, you might fine-tune the Search Results cards region to let the user choose a sorting order. A Select List item is a popular control to use for that purpose. As shown below, the page items palette in Page Designer contains all available UI controls, including a Select List. For more details on each page item type, see About Item Types in Oracle APEX App Builder User’s Guide.

To add a Select List to the Search Results region's SORT ORDER slot, you would drag and drop it as shown below, then use the Property Editor to name it P8_ORDER_BY, and configure its list of choices as static values. Then, you would select the Search Results region and configure the new Select List as its Order By item to specify the corresponding ORDER BY clauses. To learn more about user-driven sorting, see Managing Sorting with Order By Item in Oracle APEX App Builder User’s Guide.

When added in Page Designer, the Smart Filters region starts with a single text search filter, but you can add other filters using the components tree. You do this by selecting the Filters node and choosing Create Filter from the context menu. Each additional filter defines a category of distinct values that users can select to interactively narrow results and find the patients they need. Notice below that filters have been added for City, State, Postal (Zip) Code, Insurance Provider, Status, and Initial Procedure. To learn more about search filters, see Search Filter Types in Oracle APEX App Builder User’s Guide.

Universal Theme comes with several pre-defined styles.

The Redwood Light style matches Fusion Applications using colors inspired by nature and is more visually spacious. The Vita style family variants use a more compact layout and other solid colors. The Iris style blends popular aspects of both. All are designed with accessibility in mind.

As shown below, the Theme Roller editor in the developer toolbar lets you switch theme styles to instantly see how your page looks in any style. It also lets you easily customize the colors of many theme elements and save the changes with a custom theme style name.

Bookmark the Universal Theme reference app at oracleapex.com/ut to quickly consult a live reference for many aspects of APEX user interface development.

The Components section shown below lists all the native APEX visual components you can use in your apps. Click on any component to see a live example along with steps to add the component to your page. In the Icons section, you can browse or search the library of predefined icons you can use on various UI elements to clarify their functionality for end-users.

Each subsection under the Reference heading documents an important facet of APEX UI development you will find useful. For example, there you can learn about pre-defined CSS style variables and classes useful for adjusting your page elements' look and feel in a declarative way, template directives syntax for easy conditional formatting, a handy button builder, and more.

The figure below shows the reference for the Calendar region. Where relevant, you can also experiment interactively with different template options that control how the component looks and behaves. You can then set the same options in Page Designer after finding the combination that's best for your use case.

Notice it also suggests an example SQL SELECT statement to show the basic data the region requires. In the case of a calendar, you can see the data source needs a text value like task_name to give each calendar event a user-friendly label along with date (with time) values like start_date and end_date to define the event's start and duration. The query can also contain other columns whose data can appear in the event tooltip or in its customized event display text.

Using the reference app's navigation bar controls, you can toggle the writing direction and theme style. For example, the figure below shows the Map region reference page in the "Vita - Dark" theme style.

While Universal Theme lets you deliver great results without being an expert in web technologies, understanding the role HTML and CSS play is useful when customizing data formatting.

Since APEX apps are web-based, they use standard tags to annotate or mark up data with details to help clearly present the information to users. The Hypertext Markup Language (HTML) uses tags like <ul> to indicate an unordered list of elements, <li> for each element in a list, <strong> to strongly emphasize some content, and many others. These tags introduce a logical presentation structure around the data to format. These tags can contain additional attributes like class whose value contains additional logical information about an element. For example, a tag like <li class="is-selected"> might distinguish a list element the user has selected among other elements in the list. Tags and attributes work in concert with Cascading Style Sheets (CSS) rules that define how different structural elements on the page should appear.

Consider the simple example below showing the HTML markup for a list of four departments, with the RESEARCH department annotated as being selected.

<ul>
  <li><strong>ACCOUNTING</strong> → NEW YORK</li>
  <li><strong>OPERATIONS</strong> → BOSTON</li>
  <li class="is-selected"><strong>RESEARCH</strong> → DALLAS</li>
  <li><strong>SALES</strong> → CHICAGO</li>
</ul>

Your browser receives this markup to display along with CSS styling rules like the following. These two simple rules declaratively specify the background and foreground color of a selected list item and the relative font size of list item content with a strong emphasis.

/* Color selected list items differently */
li.is-selected {
    background-color: lightblue;
    color: midnightblue;
}
/* Increase font size of strong elements in list items by 20% */
li strong {
    font-size: 120%;
}

The combination of this HTML markup and CSS style rule produces a result like you see below. It shows the four department names in a bold, larger font in a bulleted list. The selected RESEARCH department appears with a light blue background.

If a region lets you configure settings on its data source columns, then they appear in Page Designer under a heading in the component tree.

The figure below shows an Employees List region in Page Designer with its columns highlighted. Selecting a column like HIREDATE in the tree, the Property Editor lets you see and adjust its appearance and behavior. If you change properties like Heading and Format Mask, Page Designer indicates these unsaved changes with a vertical bar to the left of the property name as called out below. The next time you save the page, these change indicators disappear.

If your region's data source needs to work with additional columns, or different set of them, your page can automatically adapt.

If a region is based on a SQL query, then whenever you edit the SELECT statement Page Designer adds any new columns it detects to the list. However, if the region is based on a table or other data source, you decide when this synchronization occurs.

While developing, imagine you use Object Browser to add a new column to the EMP table that the Employees List region uses as its data source. To include this new column in your page, just select Synchronize Columns on the context menu as shown below. Page Designer adds any new columns to the end of the list. You can use drag and drop to rearrange the column list order as needed.

Often, your table includes more columns than you need to show in a particular region. In that situation, you have two options: you can delete the column from the region's column list, or you can comment it out.

The figure shows the columns of an Employees List region in Page Designer. Commented out columns display with a line through their name like the DEPTNO column below. To comment out a column, select Comment Out from its context menu.

Commenting out a column is useful while a page and its data source are still in active development, where you anticipate evolving the table further and repeating Synchronize Columns multiple times. If a column is commented out, it stays that way during synchronization. In contrast, if you had deleted the column from the region, then a subsequent Synchronize Columns action brings it back along with any newly added columns. Both techniques can be useful in the right situation. An Uncomment context menu option appears on any commented-out column that you can select to easily include the column in the region again.

When your page includes a Form region, the Page Designer detects and displays a page item for each column in the data source in the Region Body slot.

By convention, page item names use the prefix of P followed by the page number. As shown below, after selecting an item like P4_HIREDATE in the tree the Property Editor shows its settings like Label and Format Mask. When you adjust your application data model, the form region works similarly to report regions. If the data source is a SQL query then Page Designer automatically adds page items for any new SELECT list columns in the query. If instead the form region is based on a table or other data source, then you select Synchronize Page Items on the context menu to include new columns when needed. Form region page items support the same Comment Out, Uncomment, and Delete options as report regions do.

While report regions control the layout of their columns, form regions have a flexible layout.

Page Designer defaults form page items to reside in the form region's Region Body slot, but you can move them anywhere on the page. As shown below, a page item's Form Region property in the Source section of the Property Editor indicates what source region it belongs to. When a form region queries a row by primary key or saves modified data, it involves the page items that name it as a source. This lets you set the Region property in the Layout section to another region on the page as needed.

In this example, two of the items with the Employee form region as their source are in a Static Content region named Identity at the top of the page. The other items sourced from this form region are in an Organization tab or a Role & Pay tab using a Tabs Static Content region set to use the Tabs Container template.

At runtime, the page above looks like the figure below. It shows the employee Id and Name fields side by side, above two tabs labeled Organization and Role & Pay. The latter tab is selected and contains Job, Hired, Salary, and Commission fields.

Your pages can use ten different kinds of list-driven items.

The Select List, Select One, and Radio Group items all support a single selection. The Select One item has a type-to-search capability, and lets you use icons and have full control over how list items appears in the dropdown. The figure below shows examples of Select List, Select One, and Radio Group page items displaying choices from the DEPT table. Notice how the user has typed es into the Select One and its list has narrowed to only show choices containing those letters. The Select One item also features icons in the list.

The Checkbox Group, Combobox, and Popup LOV items all support either single or multiple selections. The Combobox item also lets a user type in a manual entry like "SHIPPING" below that's not in the list and supports icons and styling control on how list items appear. The Popup LOV can display additional columns and search across them. When used in single-selection mode, it can optionally return values of the additional list columns into other page items or grid columns in the page. Examples of the Checkbox Group, Combobox, and Popup LOV items appear in the figure below. Notice the Combobox and Popup LOV display selections as "chips", the user has typed es into to filter both's list options, and the icons that they support.

The Select Many, List Manager, and Shuttle items offer multiple selection only. The List Manager provides a search popup that combined with the Add button is used to add selected options to a list. The Select Many supports type-to-filter and gives styling control on how list items appear. The Shuttle has configurable controls for moving and reordering the selections. This figure shows examples of List Manager, Select Manager, and Shuttle in action.

The Text Field with Autocomplete supports free form text entry, with autocomplete from a list. The user can type to search and pick from the autocomplete list of pre-defined entries, or type in any other value that's appropriate. Similar to the List Manager, its related list of options only uses the Return Item. As shown below, the user has typed the letter M in a Salutation field, and the choices Ms., Mrs., and Mr. appear.

The Select List, Radio Group, and Popup LOV items support optionally including an item in the list that represents the null value, and if included it can have a custom label. This can be useful to display text that helps a user understand the meaning of not selecting a value. For example, the Department Select List page item shown below is used as an optional query by example criteria field. A Null Display Value of All helps the user understand that employees from all departments are retrieved if they don't select a specific department.

When you create a list-driven page item, you define its list of valid choices either locally on the page item itself or by referencing a shared component List of Values by name.

If it's the first time you need a particular list of choices, then defining it locally is most immediate. Later, if you need to reuse a list you defined somewhere else, you can easily convert the locally-defined list to a shared List of Values component. Then you can reference it in multiple page items going forward.

In both cases, for each valid choice you provide a Display Value and a Return Value. The display value is what the user sees in the user interface. The return value gets assigned to the page item when the user makes a selection. For a list-driven page item configured for single selection, its value is the return value of the user's choice. For a multi-selection page item, the value is a delimiter-separated string containing the return values corresponding to the user's choices. The default delimiter is the colon (:), but you can configure it to be a different character when needed.

For example, for a page item showing a list of departments, the list of choices might be defined as follows:

After a user chooses SALES from a single-selection page item P5_SELECTED_DEPARTMENT, its value would be 30. For a multi-selection page item P5_SELECTED_DEPARTMENTS, after the user chooses ACCOUNTING and RESEARCH its value would be 10:20.

• Defining a Local List of Values
  To define the available choices for a list-driven page item, you can specify a set of static values or provide a SQL query.
• Additional Shared LOV Features
  If you anticipate reusing a list of values multiple times, define a shared List of Values (LOV). This named component supports additional features and data sources when compared with a locally-defined one.
• Converting Local LOVs to Shared
  You can use the Locally Defined tab of the shared List of Values component page to quickly convert any locally-defined LOV to a named, shared one.

When you need one page item's value to influence the list of choices in another list-driven item, you can easily configure this cascading effect.

For example, in the Only Show Employees Select Many list below, the list of employees shown depends on the department selected in the Select List item to its left.

select ename as d,
       empno as r
from emp
where deptno = :P2_DEPARTMENT
order by ename

Then, you configure the Parent Items(s) property on the P2_ONLY_EMPLOYEES list item to name the page item it depends on: P2_DEPARTMENT. This property is in the Cascading List of Values section of the Property Editor.

Setting the Parent Items(s) property enables two automatic runtime behaviors. When a user changes P2_DEPARTMENT, then the value of P2_ONLY_EMPLOYEES gets cleared and its list of available choices is refreshed. If your list of values query depends on any other page items as bind variables, list their names in the Items to Submit property in the same section. The values of the page items mentioned in Items to Submit are sent along when the list gets refreshed, but there is no other automatic behavior related to the change in their values. It's only a parent item's value change that clears and refreshes the cascading list.

select ename as d,
       empno as r,
       case job
            when 'PRESIDENT' then 'fa-badgerine'
            when 'ANALYST'   then 'fa-line-chart'
            when 'CLERK'     then 'fa-user-headset'
            when 'SALESMAN'  then 'fa-badge-dollar'
            when 'MANAGER'   then 'fa-user'
       end as icon
from emp
where deptno = :P2_DEPARTMENT
order by ename

The example above shows a pair of cascading page items, but using the same technique, you can configure multiple levels of cascading. For example, a user could pick the brand of an automobile like Volkswagen from a P2_BRAND list. Then, they might select a particular model of Volkswagen like Tiguan from a P2_MODEL list that uses P2_BRAND as its parent item. Finally, the user could choose an available Tiguan engine configuration like 1.5 TSI 130 PS (96kW) from a P2_ENGINE list that mentions P2_MODEL as its parent item. At each level, when the parent item is cleared, the cascading list item gets cleared and refreshed.

The same cascading list behavior is available among editable Interactive Grid region cells, with the same simple configuration steps. Your grid column's list of values query references the parent column's value as a bind variable using its column name, and you configure the Parent Column(s) property using one or more column names.

Design a page's layout by arranging regions and page items into a flexible grid.

The grid of columns and rows uses three simple rules:

1. Each region's width is divided into 12 logical columns of equal size.
2. An element's start column and column span can be automatic or you can set them manually.
3. An element stays in the same row as the one before it, unless you configure it to start a new row.

As shown below, APEX uses a 12 column grid since it gives six ways to divide a row evenly. This simplifies laying out elements in a visually appealing way by default.

The figure below shows the Page Designer Layout pane for a patient registration page with a Patient region and a Map region. The Patient REGION BODY slot stretches its contents to fill the entire 12-column width. P4_FIRST_NAME starts in the first column, and takes up half the width: 6 columns. P4_LAST_NAME starts in column 7 and also spans 6 columns. In the fourth row starting with P4_ADDRESS, each of the four page items spans 3 columns. The Map REGION BODY slot similarly stretches its contents. Its single Geocoded Address page item starts in column one and spans all 12 columns.

The P4_USERNAME, P4_INSURANCE_PROVIDER, and P4_ADDRESS page items each has its Start New Row property set to true. Other page items have this property set to false, so each stays in the same row as the page item that comes before it in layout order.

Notice the Patient region's NEXT slot containing three buttons. It does not stretch its content to fill the region's available width. Instead, some slots meant for buttons do not use the grid layout. The buttons use only the width they need, with uniform space between them.

As shown below, the sequence of elements in the component tree in Page Designer sets the layout order. You can drag an element to reorder it in the tree, and the Layout pane immediately reflects the change. Alternatively, you can resequence items by changing the value of their Sequence property.

At the top of the tree, the elements whose icons are an eyeball with a diagonal line through it are hidden page items. These act like invisible page variables that users never see, so they do not appear in the Layout pane.

Besides the visible difference in the buttons' layout, another clue that the NEXT slot does not use the columns and rows grid is that the Property Editor has no Start New Row property for a button like Assistant in this slot. If that same button were instead in the BODY slot that does uses the grid, its Start New Row property would appear.

If you run this page, the figure below shows what you see in the browser. The page items in the Patient region's Body slot fill the available width, maintaining the relative layout from Page Designer. The Map region appears below the Patient region and also occupies all 12 logical columns. The buttons in the NEXT slot just use the space required by their label and icon.

By default, the Column Start and Column Span properties are set to Automatic. This means each element in a row tries to occupy the same amount of space if possible, and each starts in the next available column after the one that comes before it in layout order.

Sometimes you want to dedicate more width to a particular item or have it start in a specific column. You can manually set an item's Column property to explicitly start in a column from 1 to 12. Independently, you can set the Column Span property to the number of columns the item should occupy. Only legal combinations are allowed. So, for example, if you set an item to start in column 10 and also manually set a Column Span, then the only allowed values are 1, 2, or 3. Any more would cause that item to go beyond the 12th grid column.

In the figure below, both P4_ADDRESS and P4_CITY have their Column Span set to 4. This leaves 4 of the 12 columns to P4_STATE and P4_ZIP in that same row. Since they are set to Automatic, they evenly divide the remaining space with 2 columns each.

Running the page, the figure below now reflects the custom column spans.

While you are testing the page, you can reduce the width of the browser window to see how the page responds to a new screen size. APEX preserves your logical layout as long as it can as the screen gets narrower. The figure below shows how the same page looks on a narrower mobile device.

However if you continue to make the window narrow enough, at some point it will switch to showing each item in its own row to preserve the usability of the page. For example, the figure below shows the same page on the width of an iPhone 14 screen. This is responsive design in action. Every APEX page you create behaves this way. There's no need to design different versions of the same page for different screen sizes. Your single logical layout adapts to any device you use it on automatically.

So far, the Map region has appeared below the Patient region. The figure below explains why. The same simple to understand grid of columns and rows also operates at the page level. The component tree nodes representing the Patient and Map regions are collapsed to emphasize how they are elements at the same level of the tree. Their Layout pane contents are blurred to focus attention on how the regions themselves are two consecutive elements contained in the BODY of the page. Each is using the Automatic setting for Column Span, so each occupies the entire width available: all 12 logical columns in the page BODY. Notice the Map region has its Start New Row property set to true, so it starts in a new row.

By setting the Map region's Start New Row property to false, it stays on the same row as the element before it at the same level of the component tree. As shown below, this puts the Map region to the right of the Patient region in the same row of the page BODY. Since both regions use the Automatic setting for Column Span, they evenly split the space in their row. The same intuition for configuring Column and Column Span in a region's contents, also applies at page level. You could force the map to only occupy one third of the width instead of one half, simply by setting the region's Column Span to 4. This is because 4 is one third of the 12 available columns.

Leaving the Automatic setting and running the page produces the result in the figure below. The Patient region occupies half the width of the page's body. Within that half of the page, the relative 12-column layout of the region's BODY contents is preserved. Since the Map region's only Geocoded Address item spans all 12 column in that region's BODY contents, the map fills its entire half of the page body.

Following the three simple rules illustrated here, laying out any page that works at any screen size becomes a breeze with a bit of practice.

Choosing from Universal Theme's available page templates, region templates, and item templates, you get professional results using a declarative approach. Each template offers options you can configure in Page Designer to fine-tune your page's look and feel.

The Universal Theme Reference App at https://oracleapex.com/ut is your playground for live experiments.

• Page Template Sets the Scene
  The page template you choose organizes the space on the page into slots that contain your page contents.
• Region Template Styles a Section
  A region's template organizes the layout of its section of the page.
• Item Template Controls the Label
  The item template controls how a page item renders its label.

A region can contain other regions in addition to its primary content.

Both the Layout pane and the component tree display this relationship. Sub-regions have a Parent Region property you can see and change in the Property Editor. By nesting regions inside other regions and applying the grid layout rules, you can quickly produce any kind of layout.

While any region can contain other regions, empty Static Content regions are most common for layout needs. For example, in the figure below, the page's Body slot has three static content regions named Start, Center, and End. Each uses the Blank with Attributes template, so none shows a header or borders. The Start region contains page items in its Body slot, while Center and End act as invisible containers for the regions inside.

These three top-level regions are in the same grid row of the page Body, so you can divide up the space in the 12-column grid by setting each region's Column Span. The Start region has Column Span of two (2) and also contains a (Search) button in its Previous slot. The Center region spans six columns and nests a Tabs region and a Departments region. The End region contains a Help region showing an informational message and a Chart region in two grid rows one above the other. The Tabs region contains two Cards regions: Subordinates and Managers, while Departments nests two Content Row regions in the same row side by side.

The figure below shows how the page looks at runtime. It shows how the three top-level regions divide up the page's horizontal space according to their column span. Within each one, the nested region content are stacked vertically and horizontally as indicated in Page Designer. You'll quickly develop an intuition for using the grid layout rules with region nesting to create any layout you need to.

In the default arrangement of Page Designer tabs, the Rendering tab is grouped together with the Dynamic Actions, Processing, and Page Shared Components tabs, and all present a tree of their respective contents.

As shown below, their tab names show when there is enough horizontal space. The Rendering tab displays the hierarchy of regions, page items, and buttons on the page. Tree headings reflect the different page template and region slots where components can appear.

Selecting a component in the Rendering tab highlights it in the Layout tab, and updates the Property Editor to reflect the component's settings. The figure below shows how these same four tabs display only an appropriate icon when the panel width is narrower. You can use the vertical splitters between panels to adjust their widths. By clicking the small arrow in the splitter, you can collapse or expand the side columns as needed.

If useful, you can drag any tab to another position in its current panel, or into any position in a different panel. To reset the tab arrangement, choose Reset Layout from the Utilities dropdown menu. Its icon is a wrench with a down-pointing chevron.

You use the Property Editor to review and change the settings of components on the page.

The Property Editor displays all settings for the selected component. Some components have settings that appear across multiple tabs. The property editor supports multiple selection, searching for a selected property, and pinning a search to examine the same setting across multiple components.

Configuring Settings for Multiple Components

When you select multiple components in the Rendering, Dynamic Actions, or Processing tabs, the Property Editor shows the settings in common to all selected components. To perform multiple selection, you can:

• select one component then Shift-select another to select a range, or
• Control- or Command-select any set of components.

As shown below, when the selected components have the same value for a common setting, like Icon, the property value displays. When their values for a property differ, a delta symbol appears and the property shows empty.

Setting any property value while multiple components are selected sets that same value on all selected components.

Searching for a Particular Setting

Use the Filter search field at the top of the Property Editor to find a particular setting by name. As shown below, after typing ic into the field, the editor displays a filtered view of properties whose section title or property name contains the search term. Search results include the Identification group and the Icon setting, both of which contain ic in their name. This property search helps you quickly narrow the focus to just the property you need to change. Press the Escape key while the search field has focus to clear the search and see all settings again.

Pinning a Property Editor Search

If you plan to inspect or change a particular property across multiple components, select them all, search in the Property Editor to find the setting, and then set their common property in one go. As shown below, you can also search the Property Editor first to find the setting and then click Pin in the search field. This "freezes" the search until you click Pin again to unpin the search. With the search pinned, you can visit any number of components in the page and see or change only the properties in the filtered Property Editor.

Use trigger actions to configure dynamic behavior for buttons and menus, and event handlers in the Dynamic Actions tab to react to value changes, dialog closure, and other user interface events.

When your user needs to perform an action by clicking a button or menu, you can add Triggered Actions directly to the element in the Rendering Tab. As shown below, the Refresh button triggers an action to refresh the Results region. The Invoice Complete menu item sets the ID of the selected invoice and submits the page to perform business logic related to completing an invoice.

To handle any other user interface events, you can use dynamic action event handlers. The Dynamic Actions tab shows all event handlers defined on the page, and the sequence of Dynamic Action steps that you've configured to execute when each event occurs. As shown below, when the user closes a modal dialog this page invokes, this page handles that event by refreshing the Results region.

Use the Processing tab shown below to review and declaratively configure what happens when the end-user submits the page.

You can define validations to ensure data correctness, page processes to perform work of various kinds or to do more complex validation checks, and branches that determine the next page the user sees if no validation errors occur. After selecting any validation, page process, or branch in the tree, the Property Editor updates to shows its settings.

The Page Search tab lets you search your page to find anything you're looking for.

Clicking on any search result in the Page Search tab shows its settings in the Property Editor. The figure shows the results of searching the Review Invoices page (22) for the text patient, followed by clicking on the second result. Its properties display immediately in the Property Editor.

The Help tab shows detailed information about any setting you select in the Property Editor.

As shown below, after clicking on the Type setting label, the Help tab updates to explain the setting, available options, and usage examples. For settings supporting substitution strings, the Help tab information confirms the kinds of substitutions allowed, the syntax to use, whether you can use template directives, and often includes examples of usage.

To define the available choices for a list-driven page item, you can specify a set of static values or provide a SQL query.

When defining the static list of values, as shown below, you type in the Display Value and Return Value for each entry. Use the buttons next to the entries to delete and reorder them, and switch the Sort at Runtime toggle off if the items should appear exactly as entered. The default is to sort the items alphabetically on Display Name.

select dname as d, deptno as r
  from dept
 order by dname

select ename as d, empno as r
  from emp
 where deptno = :P5_DEPARTMENT
 order by ename

If you anticipate reusing a list of values multiple times, define a shared List of Values (LOV). This named component supports additional features and data sources when compared with a locally-defined one.

For example, when you create a shared LOV with static entries, you can optionally configure a condition with each entry to indicate when it should appear in the list.

A shared LOV whose choices are not static is known as a Dynamic List. Its entries come from a SELECT statement or a remote data source. The query or data source can provide additional columns beyond the usual display value and return value. One of these additional columns can be the name of icon to display in each row, and you can use these extra columns in the custom list entry display formatting of Select One, Select Many or Combobox page items. With a Popup LOV, you can also display the additional columns, let users search on them, and return their values into other page items.

You can use the Locally Defined tab of the shared List of Values component page to quickly convert any locally-defined LOV to a named, shared one.

The figure shows the Shared Components List of Values list page. On its Locally Defined tab, two List of Values appear, each with a Convert button in the Action column of the table. Just click this button to convert the locally-defined LOV into a shared component. App Builder adjusts the original page to use the new shared LOV.

The page template you choose organizes the space on the page into slots that contain your page contents.

The figure below shows the slots each page template provides. Standard is the default, and is one of the five that also display the application navigation menu. See the Design, Page Templates section of the Universal Theme reference app for additional details.

A region's template organizes the layout of its section of the page.

There are many different region templates to explore in the Universal Theme Reference App, but the default Standard template serves most common use cases. As shown below, its Region Body slot shows your primary contents using the 12-column grid layout. It has nine slots for positioning buttons, and simple options control its heading, border, and spacing. When appropriate, you can decide to show only the region's contents by using these options to hide its header and remove UI decoration.

To show region contents with no buttons or borders, the Blank with Attributes template is a one-click alternative to hiding the Standard template's header and using no UI decoration.

When you need to create a toolbar, but none of the page template's or Standard region's button slots are correct, then the Buttons Container template lets you create a toolbar somewhere else on the page.

The item template controls how a page item renders its label.

You use an item template to configure how the user sees a page item's label and required indicator. Set the item template to Hidden to have no label. To have the label appear before the item, use the Optional or Required template. In these three cases, the Label Column Span indicates the number of grid columns the label occupies. Within their respective column spans, the label is aligned to the end and the page item to the start. Notice that by default, the field is not stretched to fill its column span, although there is an option to enable that. In the figure below, the three query by example fields above the employees search results use the Optional item template.

Using the Optional - Above or Required - Above item template, the labels show above the page item and there is no Label Column Span to set. As above, the fields do not stretch. The figure below shows the same page with its query by example fields using this template. All the page items use the Automatic column span setting, so the three items in the same row occupy four columns each.

The label on items using the Optional - Floating or Required - Floating template appears inside the item. The label shrinks slightly and moves up when the field has a value. This item template stretches the item to fill its column span as shown below.

The Department query by example field in the figure below uses a Required - Floating item template. Items with a required template display a visual marker, and if desired a template option lets you show an inline Required label as shown below.