11 Common Use Cases

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

Locate the VB Studio Service URL

When you file a service request for VB Studio, you'll need to provide the URL of the VB Studio service instance that was provisioned for you. Here's how to locate your VB Studio service instance's URL:

  1. Launch the Oracle Cloud Console at https://www.oracle.com/cloud/sign-in.html.
  2. Provide your Cloud Account Name (the account that you chose when you signed up) and click Next.
  3. Sign in with the user credentials that you received when you set up your account.
  4. Click the menu at the top of the page, then select Platform Services and Developer in the navigation tree, as shown here:

    This image shows the service navigation tree when you click the menu on the Oracle Cloud console. Platform Services and Developer is highlighted to show the navigation that gets you to your VB Builder Studio instances.

  5. For the VB Studio instance you want, click the Manage this instance icon and select Access Service Instance:

    This image shows the VB Studio instance provisioned for you in Oracle Cloud. The Actions menu is highlighted to show Access Service Instance, which you click to get the URL for the VB Studio instance.

  6. When the service instance opens in a new browser tab, make a note of the URL. The URL uses the format https://servicename-cloudaccount.servicetype.ocp.oraclecloud.com/ic/builder, where:
    • servicename specifies the VB Studio service
    • cloudaccount specifies your cloud account name
    • servicetype is either builder or integration
  7. Provide this URL when filing a service request with Oracle Cloud Support.

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 {
            tracker.showMessages();
            tracker.focusOn("@firstInvalidShown");
            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 Endpoint... node to the true branch of the If action:

You can now test the form validation.

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 Property Inspector, 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]]">
        </oj-bind-text>    
      </span>
    </template>
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 VB Studio. 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 a 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 with the Aggregate from related business object data option. 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 About Field Triggers).

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

Style VB Studio Applications

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

When you style your VB Studio 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. JET components provide a styling API through the use of Sass (Syntactically Awesome Style Sheets) only, and any directly styled oj-* component selectors or other approaches aren't supported. This is because the internal structure of JET components, and the styles that they use, are subject to change from release to release.

The published set of Sass variables constitutes a stable supported API that will internally re-map the configuration as required by internal changes within the JET implementation. See "Theming Applications" in Developing Applications with Oracle JET. To get the latest version, scroll to the bottom of https://www.oracle.com/webfolder/technetwork/jet/index.html and click Developer's Guide under Docs.

By default, all VB Studio applications created with version 20.10 or later use the Redwood UI theme. VB Studio applications have a built-in 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.

Run VB Studio Applications On Other Servers

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

Specifically:
  • Business objects won't run, because they require the VB Studio 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 VB Studio server authentication proxy manages connections to REST services, so you'll need to define your VB Studio 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 VB Studio 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 Audit, Build, and Deploy Visual Applications 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.

Note:

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.

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

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.