10 Common Use Cases

Here are some common scenarios that Oracle Visual Builder users encounter.

Work With the Visual Builder Cookbook

If you're looking for Visual Builder samples that demonstrate different use cases, the Visual Builder Cookbook is for you. The cookbook provides a collection of step-by-step recipes that describe how to implement different techniques to develop your application in Visual Builder. You also get the complete code for each sample, so you can inspect and learn from it.

Here's how you can access the cookbook right from your Visual Builder instance:
  1. Click any application on the Visual Applications Home page.
  2. Click Menu in the upper right corner and select VB Cookbook.
This opens the cookbook hosted as a Visual Builder application at https://vbcookbook.oracle.com/.
You can also create your own copy of the cookbook on your Visual Builder instance:
  1. Click New on the Visual Builder Home page to create a new application.
  2. Enter an application name and click Change Template.
  3. Select Oracle Visual Builder Cookbook as the app's template.
  4. Click Select, then Finish.
This installs a complete copy of the cookbook in your environment. The cookbook app will have everything you need to run the samples, including backend business objects, and the code for all the samples.

Enable Client-Side Validation for a Form

You may want to set up a form so that your application can check the validity of its contents before the user submits it.

To do this, surround the form with an oj-validation-group element, and add a custom isFormValid Javascript function that returns a boolean. You can then call that function before the form is submitted.

Suppose you have a form with three text fields. To set up a basic client-side validation for this form:

  1. Open the page that contains the form.
  2. Click the Code button to switch to the code view of the page.
  3. Locate the div element that contains the oj-form-layout element. If it isn't already, enclose this div element in an oj-validation-group element that has an id attribute. For example:
    <oj-validation-group id="CreateForm">
  4. Click Source View in the Navigator, then find your application's app-flow.js file:

  5. Add the isFormValid function as shown here (the function code appears in bold):
    var AppModule = function AppModule() {};
    AppModule.prototype.isFormValid = function(form) {
        var tracker = document.getElementById(form); 
        if (tracker.valid === "valid") {
            return true;
        } else {
            return false;
    return AppModule;
  6. Go back to the page with the form. Click the Save button, then select the Actions tab for the button and click createExpenseReportChain.
  7. If an If action does not exist:
    1. Drag an If action after Start.
    2. In the Condition field, enter:
      {{ $application.functions.isFormValid("CreateForm") }}

      The argument to the isFormValid function is the id value for the oj-validation-group element.

    3. Move the Call REST businessObjects/... node to the true branch of the If action. For example:

You can now test the form validation.

Restrict User Access to an Application/Flow or Page

When you want to limit user access to your application, you can set up user roles at the application level, then restrict access only to those roles. You can use this approach to restrict access to your app, or even a page or flow in your app.

To restrict access to your application:

  1. Create a user role (for example, Admin), then associate it with specific IDCS groups or users, as described in Manage User Roles and Access.

    When you set up user roles for your visual application, the roles map to groups in your IDCS account. These roles act as additional roles on top of the built-in Authenticated User role.

    Note that when access to the app requires authentication, all users who access the application are assigned the Authentication User role after they sign in. By default, an authenticated user can see and manage all business object data. To change this, configure security settings on the business object.

  2. Set role-based permissions by editing the JSON metadata for the app, page, or flow artifact:
    1. In the Web App tab, click the node for the artifact. To restrict access to the application for example, click the application node.
    2. Click JSON to open the artifact's metadata.
    3. Update the existing security entry in the file, or add code similar to the following at the end of the file:
        "security": {
          "access": {

      where user-role identifies the user role created in the previous step, for example, Admin.

  3. Test the application to preview it in different roles, as described in Activate Role-Based Application Preview.
  4. When you are ready, stage and publish your application, as described in Stage and Publish Visual Applications.

Conditionally Show or Hide UI Components

You can dynamically display UI components in your application by surrounding the component with an oj-bind-if and setting conditions to either show or hide the component.

See Manage Component Visibility Using Conditions.

Validate Dates in Forms

You can use the Expression Editor to validate a date you enter in a form.

Suppose you have a form for creating a business object instance that has a Start Date and an End Date field. You want to be sure that the end date can't be earlier than the start date. To do this:
  1. In the Page Designer, select the Input Date component for End Date in the form.
  2. In the General tab of the Properties pane, click the fx icon for the the Min property.

  3. In the left panel, expand the business object and double-click startDate.
    The expression $variables.expenseReport.startDate is displayed in the editor pane (where expenseReport is the name of the page variable).
  4. Click Save.
    The expression is displayed in the Min property, surrounded by double brackets.
As a result, the DatePicker for the End Date field makes all dates before the Start Date unavailable. If you manually enter a date before the Start Date, you'll see an error message.

You may also need to specify a format for dates. See Format a Date Field for information on how to format a date field of a business object.

Format a Date Field

You can format date fields of business objects to match the format you need.

When first added to a business object, date fields use their default formatting. To format a date field:
  1. Drag an inputDate component from the Components palette and drop it on top of the date field.
  2. Set that field's converter property to match the format you need.

Format Row Values in a Table Conditionally

You can use a column template to specify row-specific formatting for particular values in a table column.

Suppose, for instance, that your table has a Salary column and you want to display the values that fall above a certain level in bold. In your table, you can represent the Salary field of the business object as a separate column template, so that you can define the format for this field.
  1. In the JavaScript for the page, define a PageModule function that determines the format you want to show. This code defines a weight function to set the font weight:
    PageModule.prototype.weight = function(salary) {    
        if (salary > 2000) {
            return "bold";    
        return "normal";  
  2. To create the column template, drag and drop a Text component onto the existing field, then click the Code button for the page.
  3. Surround the field with a span element within the template element. Make sure to put a colon in front of the style attribute.
    <template slot="Salary">
      <span :style.font-weight="{{$page.functions.weight($current.data)}}">
        <oj-bind-text value="[[$current.data]]">
When the page is displayed, all salary values above 2000 appear in bold.

Create a Search Filter for a Table

You can use an input text component to filter a table column to search for text.

  1. Drag an Input Text component onto your page.
  2. Click the All tab of the component and locate the raw-value attribute, which tracks what is typed into the text field.
  3. Click the Select Variable icon for the attribute to create a new page variable (call it searchVar, for example).

    After you set the raw-value attribute, when you type in the Input Text field, the value of the searchVar variable will change.
  4. Click the table, then click the Add Data quick start to populate the table.
  5. On the Add Data page of the quick start, specify the business object you want to use and click Next.
  6. On the Bind Data page of the quick start, bind the fields you want to display and click Next.
  7. On the Define Query page of the quick start, click the filterCriterion builder icon on the Target side.
  8. Select the table column you want to filter, the operation you want to use ($co for Contains, or $sw for Starts With, for example), and the value ($variables.searchVar).

Once you have bound the raw value of the input text to a variable and then used that variable as the filter criterion for a table column, you have your search filter. Use the Run icon or the Live button to test the behavior.

Filter Multiple Attributes in a Search

You can apply a single search input term to multiple attributes of a service endpoint by setting up a filterCriterion with many conditions.

You can use filterCriterion to filter data displayed in a Table, List, or another collection component in Visual Builder. For information on how to create a search filter in a Table, see Create a Search Filter for a Table. You can use this configuration for a List View component as well. For detailed information on filtering data, see Filter Data Displayed in a Component.

Once you have your search filter, simply extend the filter criteria. For example, to filter data in the Traveler and Destination table columns, your filter criteria might look as shown here:
"criteria": [
"value": "{{ $page.variables.filterVar }}",
"op": "{{ \"$eq\"\n }}",
"attribute": "{{ \"traveler\"\n }}"
"value": "{{ $page.variables.filterVar }}",
"op": "{{ \"$eq\"\n }}",
"attribute": "{{ \"destination\"\n }}"
"op": "{{ \"$or\"\n }}"

Wrap Table Header Text

If the header text for table columns doesn't display completely when a column's width is reduced, you can enable text wrapping for the header. Use the headerStyle attribute as shown here on the column definition to enable wrapping if the header does not fit:

"white-space:normal; word-wrap:break-word;"

Apply an Aggregate Function to a Calculated Field From a Child Business Object

When you want to aggregate a field in a parent business object based on a calculated field in a child business object, the calculated field won't show up as a Field to Aggregate field with the Aggregate from related business object data option in a field's Properties pane or the Create Aggregate Field option in the Fields tab. Using a calculated field with declarative field aggregation isn't supported, but you can get around this by storing the calculated value in the business object.

Consider a sample Shopping Cart scenario, where you have a Shopping Cart business object with Cart Item as its child business object. Assuming that Cart Item has a field cartItemAmt (calculated as Qty * Unit Price), you're trying to aggregate cartItemAmt as the TotalAmount in the Shopping Cart business object.

The recommended approach for this requirement is to store the calculated value in the business object. You can do this by adding a trigger to the detail item that will catch any transaction and update the calculated field in the parent field (see Field Triggers).

This approach has the added advantage of speed; because the calculation isn't done at runtime, your page will load faster.

Change an Application's Logo

When a web app uses the Redwood theme, here's how you can customize the application to use your company logo:

  1. In the Navigator, click Web Applications and expand your web app.
  2. Expand Root Pages, then double-click the page under it (shell, by default) to open it in the Page Designer:

    Image shows how to open a web application's root shell page, by clicking Root > shell in the application's tree structure

  3. Click Code to switch to the page's code view.
  4. Look for the commented img tag that you can use to insert your logo, and uncomment the tag. Place your cursor inside the src attribute, then click Design to return to design view:

    Image shows the page's code with the img tag highlighted

  5. In the Image's Properties pane, click the Data tab.
  6. Drag your image into the drop target area in the Data tab.

    Image shows an empty Image component in the application header. On the right, the Data tab in the Properties pane shows where you can drag and drop an image of your logo.

    Once you add the image, the Source URL field updates to show the path to the image.
  7. If necessary, click the All tab to view and edit image attributes.
  8. Click Preview to see how your logo appears.

Style Visual Builder Applications

All styling in Visual Builder applications happens manually in CSS. There are no declarative features for changing the display of text or images. Because all Visual Builder applications are just JET applications, they use JET themes to style the applications.

Visual Builder applications created with version 20.10 or later, by default, use the Redwood UI theme. The Redwood theme provides hundreds of custom properties (also called CSS variables) to achieve its look and feel. Starting with JET 10 in version 21.07, you can customize the Redwood theme using application CSS overrides (as described later in this section).


Styling applications that use the Redwood theme is supported only for web applications. If you’re styling applications that use the Alta theme, note that support for Alta themes is deprecated in JET 10.

When you style your Visual Builder or JET applications, it's important to use theming correctly. Otherwise, you run the risk of finding that your re-styling breaks when you upgrade your platform versions. For more information about theming your application, see "Using CSS and Themes in Applications" in Developing Applications with Oracle JET. To get the latest version, click Help and Support on https://www.oracle.com/webfolder/technetwork/jet/index.html, then scroll to the bottom and click Theming.

Visual Builder applications also have an app.css file that you can use to define additional styling on top of the main theme. For example, if you've made a div element clickable, you may want to add a class called clickable to the div and define the CSS for the class so that the element is highlighted, the cursor changes to a pointer when you hover over it, and so on. See Add a Custom Style to a Component.

Customize the Redwood Theme for a Web Application

Starting with JET 10 in version 21.07, you can use CSS overrides to customize the Redwood theme for web applications created in Visual Builder. In this scenario, your application uses the built-in Redwood CSS file (redwood.css), but you add variable overrides in a separate CSS file for your application (redwood-overrides.css).

The advantage of overriding CSS variables in a separate file is that you won't need to rebuild your application with each new version of JET. Whenever the default Redwood theme changes in a future release, the changes will be picked up by your application CSS files without requiring changes.

To customize the Redwood theme used by a web application:

  1. In the Navigator's Web Applications tab, select your application and click the Settings tab.
  2. When the Theme is set to Redwood, click the Create Override link:

    A new redwood-overrides.css file is created in your application’s resources/css folder.

  3. Click the file under Theme Override to open it:
  4. Uncomment and change the values of the variables you want to control.

    Because JET releases over time may change variable values, you might want to uncomment all variables, so that future changes don't affect your theme. To do this, remove the /* just before :root at the beginning of the file and the */ at the end of the file.

    Then, update the variables you want to override. For example, to override the font used by the Redwood theme for your application, search for family, then change the --oj-html-font-family variable's values:
    Description of redwood-override-change.png follows
    Description of the illustration redwood-override-change.png

  5. Check your application and verify the changes.

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


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 Properties pane in the Page Designer's Design view 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 Properties pane. 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.

Add Login and Logout Capabilities to an Application

Visual Builder applications provide built-in options for you to implement login and logout for your users.

Customize Application Login

By default, any application you build in Visual Builder includes a login screen—unless you enabled anonymous access that allows users to access your app without signing in. The default login screen points to the Sign-In page that Oracle Identity Cloud Service (IDCS) provides for token-based authentication:
Description of default-login-page.png follows
Description of the illustration default-login-page.png

If you want to customize this sign-in page (you'll need rights to register applications in IDCS), you can use the Branding feature to change the company name and the login text, as well as upload logos to replace the defaults. The position of the text and images, and the colors and fonts, remains the same. For anything beyond what the branding feature supports, you'll need to use the Authentication REST API that IDCS provides to help you develop your own sign-in page.

Enable Application Logout

You can enable a logout function for your application by adding the built-in Logout action to any page component, for example, a button or a menu item.

Web applications in Visual Builder come with a default shell that displays a Sign Out option under the logged-in user's email, but you'll need to add the Logout action to the menu component to actually trigger a logout:
Description of webapp-shell.png follows
Description of the illustration webapp-shell.png


The Sign Out option doesn't appear for mobile apps or apps enabled as PWAs, but you can enable the same functionality for these apps by calling the Logout action from any page component.
To add a Logout action to a page component:
  1. Open your web or mobile application in the Navigator.
  2. In the Structure view, select the component you want to add the Logout action to, then click the Events tab in the Properties pane, click +New Event, and select Quick start: 'ojAction'.

    To enable logout for a web app's default Sign-In option, locate the Menu component in the app's shell page under the Root Pages folder, then add a new event as shown here:
    Description of webapp-shell-menu-addojaction.png follows
    Description of the illustration webapp-shell-menu-addojaction.png

  3. In the Action Chain editor, drag and drop the If action from the Actions palette to the Add icon ( Add icon ) in the action chain, then set the Condition field's value as [[ $variables.menuId ==='out']].
  4. Drag and drop the Logout action on the true branch of the If action:

    If are using an external identity provider, enter the provider's logout endpoint in the Logout URL field, something like https:***/oam/server/logout?end_url=https://****/oamwebsso/logout-success.jsp. If you are using IDCS for authentication, you don't need to specify the logout URL.

When you are done, run your app to check whether you're being logged out of all active sessions (in the same browser) associated with the same identity domain.


The logout action won't work when you preview the app in Live mode (to avoid logging you out during development). You'll need to stage or publish your app to make sure logout works as expected.

Redirect URL After Logout

A post-logout URL always points back to the deployed app (because the server runtime logout code isn't aware of changes made in the IDCS client app). One option is to use the IDCS logout directly (instead of the Visual Builder logout URL) and specify your post-logout URL in a query parameter, for example:


Run Visual Builder Applications On Other Servers

While it's possible to run Visual Builder web applications on other web servers, you do lose some functionality.

  • Business objects won't run, because they require the Visual Builder back end.
  • You can't use Identity Cloud Service to manage your users, roles, or authentication, so you'll have to manage these aspects of your app.
  • The Visual Builder server authentication proxy manages connections to REST services, so you'll need to define your Visual Builder services to use a "Direct (Bypass Authentication Proxy)" connection. The calls are then made directly from the browser to the remote REST service. See Fixed Credentials Authentication Mechanisms for more information.

If these limitations are acceptable, then you can host your Visual Builder app on another server.

To modify your app to do this:
  • Use the direct access to your REST services, and switch the set of services that the app is accessing. One way is by doing a global search and replace, to update the address of the server hosting the REST services that provides data to the app. This will allow the back end to be on-premise.
  • Ensure that you've allowed anonymous access to the app. Identity Cloud Service won't be available to manage authentication.
  • Create a zip file that contains the app ready to be deployed. See Optimize Your Builds and Audit Your Code Using Grunt for information on how to do this.

You can take this optimized version of the app and host it as a regular collection of HTML/JavaScript resources on a web server.

Embed a Web App in an Oracle Cloud Application

You can edit an Oracle Cloud Application to embed your web app using Page Composer or Application Composer. For your embedded web app to work in an Oracle Cloud Application, you'll want to confirm that:

  • Your Visual Builder instance is associated with Oracle Cloud Applications;
  • Single Sign-On (SSO) is enabled;
  • The authentication for your web app is using an Oracle Cloud Account.


Contact your service administrator or project owner if you are unsure about how your Visual Builder instance is configured.

When a user is logged in to an Oracle Cloud Application, the application provides the user's Oracle Cloud Account details for authentication when accessing the embedded web app, so the web app will appear in the application's page without requiring any additional login. This authentication only occurs when the user first accesses the embedded web app and may mean that the web app takes a long time to load. Subsequent accesses will be faster.


To reduce the initial loading time of the web app, consider adding an iframe to another page of the Oracle Cloud Application, such as the landing page, and then hiding that iframe. By adding this iframe, you allow the application to load resources and resolve some of the security handshake when loading the page with the embedded web app.

To add your web app to an Oracle Cloud Application, you'll need to:

  1. Prepare your web app in Visual Builder;
  2. Publish your web app;
  3. Embed your web app using Page Composer or Application Composer.

    For more information on which one you will use with your Oracle Cloud Application, see Differences Between Using Page Composer and Application Composer in Configuring and Extending Applications.

Make Your Web App Ready for Embedding

Before embedding your app in an Oracle Cloud Application, you'll want to configure your web app settings to allow embedding, and modify your shell page to remove the app's default header and footer. You might also want to choose a theme for your application that matches the look and feel of the application where you are embedding it.

When embedding a web app, it is quite common to set up your web app so that the Cloud Application passes some values to the web app as parameters in the URL. The input parameters are usually assigned to app-scoped variables defined in your app. The variables need to have the Pass on URL option set in the Properties pane.

To get your app ready for embedding:

  1. In your web app's Settings editor, open the Security tab and select Allow embedding in any application domain or Allow embedding in specified domains.

    You'll need to enter the domain name of your Oracle Cloud Application if you choose to allow only specified domains.

  2. If you want to change your app's theme, open the General tab and select the theme from the dropdown list in the General tab.
  3. In the Navigator, expand Root Pages and open the shell page in the Code editor.
  4. Delete the <header> and <footer> elements in the code.

    Your shell page should now only have <div> elements for the page, message notifications and the content. In Design view you can see that the app now only contains the core content.

  5. When your app is ready to be embedded, stage and publish the app so that the app is accessible at a public URL.
  6. Open the live app in your browser to confirm that the page renders correctly at the URL.
    When testing the URL, you might also want to test that passing your app parameter in the URL works correctly, for example, by including the variable name and some value in the URL (https://vbinstanceurl/.../appname/?VariableName=Value)
  7. Copy the URL, and make a note of the app parameters you are using.
    You'll need to know the URL and the parameters when you embed the app using Application Composer or Page Composer.

Embed a Web App Using Page Composer

For Oracle Cloud Applications that you edit using Page Composer, you embed your web app by adding a Web Page component to a page and then specifying the app's URL and parameters. The following steps are high-level and are presented here to help you embed your web app in a page using Page Composer. For additional details, see Overview of Using Page Composer in Configuring and Extending Applications.

To embed an app using Page Composer:

  1. Log in to the Oracle Cloud Application where you want to embed your app.
  2. Open a sandbox with Page Composer enabled, if you haven't already.
  3. In your Oracle Cloud Application, navigate to the page where you want to embed your web app content.
  4. Open the Tools menu and select Page Composer.

    Page Composer will appear in the menu if you're in sandbox which is configured to be edited using Page Composer.

    If you are using Application Composer, see the next topic.

  5. In the Source view, open the Selector panel and select the area in the page where you want to embed your app. Click Edit in the popup menu to enter Edit mode.
  6. Make sure the area is selected in the Selector panel, then click Add (+) in the panel's toolbar and add a Web Page component in the Add Content dialog. Click Close.

    The area now contains the Web Page component.

  7. In the Selector, right-click the new Web Page component and select Edit in the popup menu to open the Component Properties: Web Page dialog box.
  8. Add a name and description for the new component.
  9. In the Source field, open the dropdown list and select Expression Builder.
    If you are passing a variable to your web app as part of the URL, you'll need to use the Expression Editor to construct the URL.

    If you aren't going to pass a variable, you can paste the URL for your web app in the Source field.

  10. In the Expression Editor dialog, select Choose a Value, and then select Binding Parameter in the dropdown list.
  11. Select the binding parameter you want to use from the dropdown list.
  12. Select Type a value or expression, then edit the expression in the text area to define the URL of your web app.

    The text area contains an expression fragment (<generated-expression>) generated for you based on the binding parameter you selected. It might look something like #{bindings.DisplayName.inputValue}. This is the value that will be passed to your web app.

  13. Prepend the URL of your web app to this expression in the text area.

    Your expression might look something like https://vbinstanceurl/.../appname/?VariableName=<generated-expression>. When you paste in the URL, make sure it includes ?VariableName= before the generated expression, where VariableName is the name your web app expects in the URL (for example, "OwnerName").

  14. Click OK to close the Expression Editor dialog, then click OK to close the Component Properties dialog box.
  15. Click Done to finish the Page Composer editing session.
  16. Publish your sandbox after you've added the web page.

After closing the editing session, your web app content appears in the area in the page in the Oracle Cloud Application. The app is embedded in the page, and you can navigate to pages within the web app without leaving the Oracle Cloud Application page containing the web app. You can use your web app to display web app data in a page, and for example, to show a graph that rendered in the web app.

Embed a Web App Using Application Composer

For Oracle Cloud Applications that you edit using Application Composer, you embed your web app by adding a mashup to the application, for example, in a tab or a page. The following steps are high-level and are presented here to help you embed your web app in a page using Application Composer. For a detailed description of how to embed a web app, see the Mashups section in Configuring Applications Using Application Composer.

To embed a web app using Application Composer:

  1. Log in to the Oracle Cloud Application where you want to embed your app.
  2. Open a sandbox with Application Composer enabled, if you haven't already, and then open Application Composer.
  3. Create a parameter-based mashup for the web application.

    If you want to pass any input parameters to your web app, you'll need to define the names of the parameters when you create the mashup. For example, if your web app is using an input variable named accountid (https://vbinstanceurl/.../appname/?accountid=SomeValue), you'll want to add accountid to the mashup.

    For more details on creating a parameter-based mashup, see Register Your Web Application in Configuring Applications Using Application Composer

  4. In Application Composer, locate the application page (for example, the Details page) where you want to embed the web app.

    If you specified any parameters in your mashup, you'll need to map the parameters to fields in your application. For example, you would map the Registry ID field to the accountid parameter you defined in the mashup if you wanted to use the Registry ID value as your web app's input parameter. For more on adding a mashup to a page, see Embed a Registered Web Application into Your Application Page in Configuring Applications Using Application Composer.

  5. Publish your sandbox after you've added the mashup to your application.