3 Develop Applications

To develop an application you need to define its metadata and create its pages and artifacts.

Understand an Application’s Structure

Your visual application can contain multiple web and mobile applications. The web applications in your visual application are displayed when you open Web Applications in the Navigator. The mobile applications are displayed when you open Mobile Applications in the Navigator.

The structure and required files are created by default when you create a web or mobile application. Open Web Applications or Mobile Applications in the Navigator to see a visual representation of the structure of your application and to navigate to the application’s artifacts. In the Navigator, the artifacts are represented as one object, but they actually represent two or three separate files that describe the artifact’s behavior and properties. The properties and behavior of an artifact are built by creating and combining the building blocks described in these files. For example, when you edit a flow artifact, you will describe the artifact’s variables and action chains in the artifact’s json file, and functions are defined in the artifact’s JavaScript file. See Understand the Application Designer.

When you open an application in the Navigator, the structure of the application is displayed as nodes and subnodes representing the application’s artifacts and files. You can collapse and expand nodes to hide and reveal the contents. Selecting an artifact or file in the Navigator opens the artifact in the one of the editors in the application designer.


Description of browser-app-structure.png follows
Description of the illustration browser-app-structure.png

The following table describes the nodes and artifacts that are displayed when a web or mobile application is open in the Navigator.

Item Description
application

All the artifacts of an application are grouped under the application node in the Navigator. You will see an application node for each of the apps in your visual application. For example, if your visual application has three mobile apps, you will see three application nodes in the Mobile Applications pane.

You can select the application node to view the application artifact in the designer. The application artifact represents the files and metadata that describe your application. The application artifact has the same name as your app. The descriptions of the application artifact are contained in the app-flow.json, app-flow.js and index.html source files. The metadata in these files defines the artifacts that can be used by every artifact in your application, for example, the variables that are application-scoped, types that describe data structures, and security settings for the application.

See Understand the Application Designer.

flows

All the individual flows in your app are grouped under the flows node. Your app can have multiple flows, and each flow can contain multiple pages. Depending on the type of application, one or more flows are created by default when you create the application. In mobile apps, the default flow is named item1. In web apps, the default flow is named main.

A flow consists of a flow artifact and the pages within the flow. The descriptions of the flow are contained in the <flowname>-flow.json and <flowname>-flow.js source files.

See Work with Page Flows.

pages

Pages are grouped by flow under the flows node. Each page uses a HTML file to specify the page elements, a JavaScript file that determines the page’s functions, and a JSON file for the page’s metadata.

See Design Pages.

resources

The resources node contains resources available to your application, such as images, style sheets (css) and translation files (strings).

See Work with Application Resources.

root pages

The root pages node contains one or more root page artifacts where flow artifacts are embedded. The artifact describes the area containing the flow and the areas outside the page flow that can contain elements such as a header or title area, a navigation toolbar, and a footer.

An application typically contains one root page artifact for each flow. By default, a root page artifact named app is created when you create a mobile app and an artifact named shell is created when you create a web application.

Note:

You can open the Source View in the Navigator to view all the source files in the visual application.

Understand the Application Designer

When designing your application you will use various tools in the application designer to view and edit the application’s artifacts and pages.

You use the application designer to create and edit the building blocks that prescribe the behavior of pages, application artifacts and flow artifacts in your web and mobile applications. The application designer has dedicated editors for each of the building blocks used to build your application. The editors provide an easy to use interface for editing the files containing the descriptions of artifacts and pages. For example, when designing a page, you might need to define page variables and create action chains, in addition to positioning page components in the page and specifying component properties. The application designer provides editors to help you perform these tasks so that you don’t need to edit the source code of the HTML, JavaScript and JSON files used to describe the layout and behavior. The application designer also provides a Metadata editor if you want to edit the JSON files directly.

The editors in the application designer provide forms and wizards to help you create and edit the building blocks, for example, to create action chains and to map parameters to variables. When designing pages you can use a visual editor to compose your pages, and use the Quick Starts to help you create the building blocks needed to add some of the functionality commonly used in applications.

When you open an artifact, each artifact opens in a separate tab in the application designer. You switch between editors by selecting the editor’s icon in the left margin of the application designer. You use the same editors to edit each of your artifacts, with the exception that page artifacts provide a visual Designer for designing the page’s layout, and application and flow artifacts provide a Page Flow view for displaying the page artifacts they contain.


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

The following table describes the editors available for editing artifacts.

Editor Icon Description

Page Flow icon

The Page Flow view displays the pages in your application and the navigation flows between the pages. When you open an application artifact, the Page Flow view displays the root page artifacts in your application. When you open a flow artifact, the Page Flow view displays the page artifacts contained in the flow. You can double-click an artifact in the Page Flow view to open it in the Designer.

The Page Flow view is only available with application and flow artifacts.


Designer icon

The Designer is a visual editor for composing the layout of a page. The Designer contains a canvas that represents the page layout and a palette with page components that you can drag onto the canvas to add to the page. The Designer has a Property Inspector that you use to specify the properties of the page’s components and to open Quick Starts. See Use the Page Designer and About Quick Starts.

The Designer is only available with page artifacts.


Variable icon

The Variables editor displays the variables and data types that are defined within the scope of the artifact. You can use the Variables editor to create and edit variables and types. See About Variables and Types.


Actions icon

The Actions editor displays a list of the action chains that are defined within the scope of the artifact. You can use the Actions editor to create new action chains and to open action chains in the editor. See About Action Chains.

Events icon

The Events editor displays a list of lifecycle and custom events that are defined for the artifact, the type of event and the action chain that the event starts. You can use the editor to create new events and action chains. See Start an Action Chain with an Event.


Settings icon

The Settings editor contains tabs for editing an artifact’s settings. The options available depend upon the artifact. The Settings editors for flow and application artifacts contain a tab for setting security options for the artifact.

HTML icon

The HTML editor displays the code for an application’sindex.html file when the application artifact is open in the designer. You use the Code view in the Page Designer to view and edit the HTML of pages in apps.


Functions icon

The Functions editor contains a code editor for editing the artifact’s JavaScript functions. By default, application artifacts use a file named app-flow.js, flow artifacts use a file named <FLOWNAME>-flow.js and page artifacts use a file named <PAGENAME>-page.js to define their JavaScript functions.


Metadata icon

The Metadata editor contains an editor for editing the JSON file that contains the artifact’s metadata, including descriptions of variables and action chains.. By default, application artifacts use a file named app-flow.json, flow artifacts use a file named <FLOWNAME>-flow.json and page artifacts use a file named <PAGENAME>-page.json.

Create Web and Mobile Applications

Your visual application can contain multiple web and mobile applications. Each application in your visual application is independent, but they can all use the data sources defined in the visual application.

Create a New Web Application

Each web application in your visual application is independent, but they can all use the data sources defined in the visual application.

To create a new web application:
  1. Click Web Applications in the Navigator to open the Web Apps pane.

    Structural representations of each of the web applications in your visual application are displayed in the Web Apps pane.


    Description of webapp-no-apps.png follows
    Description of the illustration webapp-no-apps.png

    If no web applications have been created, you will see a message in the pane and a + Web Application button that you can click to open the Create Web Application dialog box.

  2. Click Create Web Application ( Create Web Application ) in the Web Apps pane.

    The Create Web Application dialog box contains an Application Name field where you enter the name of your new web application and options for the navigation style of your app.



  3. Enter the name for the new app in the dialog box.
    The name you enter is used as the display name in the Web Apps pane in the Navigator.
  4. Select the None or Tabbed navigation style for the web app.
    For the Tabbed navigation style, you can specify the number of navigation items and a name for each.
  5. Click Create.

Create a New Mobile Application

Each mobile application in your visual application is independent, but they can all use the data sources defined in the visual application.

To create a new mobile application in a visual application:
  1. Click Mobile Applications in the Navigator to open the Mobile Apps pane.
    Structural representations of each of the mobile applications in your visual application are displayed in the Mobile Apps pane.
    Description of mobileapp-appnav.png follows
    Description of the illustration mobileapp-appnav.png

    If no mobile applications have been created, you will see a message in the pane and a + Mobile Application button that you can click to open the Create Mobile Application wizard.

  2. Click Create Mobile Application (Create Mobile Application icon) in the Navigator.
    In the General Information page of the Create Mobile Application wizard, specify the application name for the mobile application you are about to create. You can also choose from three navigation styles. The Horizontal navigation style with three navigation items is configured by default. A Vertical navigation style is also available that allows you to create a root page with a navigation drawer panel including a header with an avatar, navigation items in the middle, and a footer with the application name. A page flow, with a starter page, is generated for each navigation item. Alternatively, select None if you want to configure the navigation items for your mobile application later. If you select None, one page flow is generated for the mobile application.
    Description of mob-appnav-createdialog.png follows
    Description of the illustration mob-appnav-createdialog.png
  3. Click Next.
    The Page Template – main page of the Create Mobile Application wizard is displayed.
  4. Select Custom and click Create.

Add a Custom Plugin to Your Mobile Application

VB Studio uses plugins developed with the Apache Cordova framework to access the capabilities of the devices on which your mobile application is installed.

A plugin is a package of code that allows the web view within which your application renders to communicate with the native platform on which it runs. The plugin does this by providing a JavaScript interface to native components that allows your application to use native device capabilities, such as camera, geolocation, and so on.

VB Studio provides a range of plugins that are ready to use in the mobile applications that you create. One example is the camera plugin that is used when you configure your mobile application to use the Take Photo action. The plugins that VB Studio delivers provide coverage for a wide range of use cases. For those use cases where VB Studio does not provide a plugin ready to use, you can import a plugin into your mobile application using the Custom Plugins page of your mobile application’s Settings screen. To identify the plugins that VB Studio delivers, run the following command from the Cordova command-line interface after you add the Android or iOS platform, as described in the readme.md file included in the Cordova project source that you’ll download as a first step to adding a plugin to your mobile application.

cordova plugin ls

To find a plugin to use in your application, go to the Plugins page at https://cordova.apache.org/plugins/ that provides a registry of core and third-party Cordova plugins. Core plugins are plugins provided by Apache Cordova while third-party plugins are those developed by independent developers. Core plugins display a blue vertical strip to the left of the card that describes the plugin, as shown in the following image, where a core plugin (cordova-plugin-dialogs) appears after a third-party plugin named com-artemisoftnian-plugins-unityads2.

The Plugins page categorizes plugins according to the platform on which the plugins will run. Some plugins run on a wide variety of mobile platforms (Android, iOS, and so on), such as the cordova-plugin-dialogs shown in the image while other plugins may only support one platform. Ensure that the plugins you install in your application support the platforms where your application will run. Each entry generally provides information such as a brief description of the plugin’s functionality, the platforms it supports, and the number of days since it was updated. It then links to a web page where you can access more documentation for the plugin, such as how to install it in your application, how to use the APIs it provides, and any known issues with regard to its usage.

If you cannot find a plugin that meets your requirements, you can develop your own plugin. Although this blog post makes reference to another mobile development framework (MAF), it provides a suitable introduction to creating a Cordova plugin that could be used in a mobile application developed using VB Studio or any Cordova-based application.

Having identified or developed the plugin you want to use in your mobile application, download the cordova-package.zip file using the Cordova Project Source link in the Custom Plugins tab of your mobile application’s Settings page. The Readme.md file that is included in the cordova-package.zip file provides step-by-step instructions that describe how to add a plugin to the Cordova project and build the application for Android and/or iOS. Once you have successfully built the application, you upload the APK file (for Android) or the IPA file (for iOS) using the appropriate Upload Template Application dialog that you access from the New dropdown list in the Uploaded Templates section of the Custom Plugins tab.

You can upload one debug and one release template application for both Android and iOS. After you upload the template application, the build configuration for the platform and build type references the template application that you have uploaded. For example, if you upload a template application for Android with a built type of Release, that template application is associated with the build configuration of Release type for Android.

Having uploaded the template application that packages the Cordova plugin that you want to use in your mobile application, you can now write JavaScript functions that invokes the interfaces that the plugin provides access to. To accomplish this task, refer to the documentation that is provided with the plugin. Plugin documentation should also identify known issues with the plugin, if any exist. The following snippet of sample code demonstrates how you might initiate a barcode scan using the phonegap-plugin-barcodescanner plugin from a mobile application that uses this plugin.

function _showBarcodeScanner() {   
        // wrap the call with a promise 
        var barcodeScannerPromise = new Promise(function (resolve, reject) {
            window.cordova.plugins.barcodeScanner.scan
                (function (result) {
                    resolve(result.text);                    
                }, 
                function (err) {
                    console.error(err);
                reject(err);
            });
        });
        return barcodeScannerPromise;
    }

Work with Variables and Types

An application artifact describes the variables, types and action chains that can be used in any page in your application, as well as other configuration settings and properties of the application. When you open an application artifact, various editors are available for examining and modifying the artifact.

About Variables and Types

Variables can be used in any page, and custom types can be used to define the data of any variable. Variables and types can be created in application, flow and page artifacts. Variables created in an application are application-scoped and can be used to store data that can be used anywhere within the application, both within and across flows and pages, for example, for a login name. Variables created in a flow are flow-scoped and can be used in any of the pages within that flow. Variables created in a page can only be used within that page.

You use variables to store data that can be used by actions and page components in your application. Application variables are application-scoped, so their use is not limited to a specific page and they are accessible from any of the pages of an application. Application variables are useful for storing states, input parameters, login details and other data that you want to be accessible both within and across flows and pages. For each variable you must specify a Type property to define the type of data that is stored in the variable. See Understand Variables.

You use types to define the data type and structure of a variable, and every variable must be assigned a type. Types can be application-scoped, flow-scoped or page-scoped, and can be assigned to application, flow and page variables. There are two kinds of types that can be assigned to variables: built-in types and custom types. Standard built-in types are used to specify data that are a primitive type, a structure or a simple array or collection, for which each field can either be a primitive or a structure. There are also two special built-in types that are typically used for storing data retrieved from an endpoint and are used when some operations need to be performed on the data: Array Data Provider and Service Data Provider. For details about how to use types in the page model, see Types.

You can define custom types from an endpoint or your can define a custom object or array.

Create Variables in Artifacts

You can create variables in application, flow and page artifacts. Variables are assigned a scope that is based on where they are created, and the scope determines where they can be used. When you are deciding where to create a variable, you should consider where it might be used.

Each variable is required to have a unique name (Id) and a type. When you create a variable you must specify one of the built-in types or a custom type. After you create the variable, you can edit its properties and attributes in the Variables tab for example, to identify it as an input, or to add attributes if its type is array or object. You can also use a variable to trigger an action chain when its value changes. You can use the Events tab in the Variable Information pane to add onValueChanged event actions and specify the action chain the change will initiate.

To create a variable in an artifact:

  1. Open the Variables tab in the Variables editor of the artifact.

    The Variables editor contains a Variables tab and a Types tab. The Variables tab displays a list of the variables that are already defined for the artifact. You can enter a string in the filter field to limit the list to variables containing the string. The Variable Information pane is used for editing the details and event actions for the selected variable.


    Description of webapp-variables-editor.png follows
    Description of the illustration webapp-variables-editor.png

    You will see a message if no variables are defined.

  2. Click + Variable to open the New Variable dialog box.
  3. Type a name for the variable in the Id field and select a type in the Type dropdown list.

    The dropdown list displays the built-in types as well as any custom types that can be applied to the variable.


    Description of page-designer-variables-create.png follows
    Description of the illustration page-designer-variables-create.png
  4. Click Create.

    You can select the Create Another checkbox to immediately create another variable.

After you create a variable you can select the variable in the list and edit its properties and add event actions in the Variable Information pane.

Create a Custom Type

You create a custom type when you want a type that defines an array or an object, and you want to individually add each of the attributes that define the type’s data structure.

To create a custom type:
  1. Select your application, flow or page artifact in the Navigator.
  2. Open the Types tab in the artifact’s Variables editor.

    The Types tab displays all the types defined for the artifact.


    Description of var-type-responsetype.png follows
    Description of the illustration var-type-responsetype.png
  3. Click + Type and select Custom in the menu.

    The New Type dialog box appears when you select Custom in the menu.


    Description of var-type-custom-new.png follows
    Description of the illustration var-type-custom-new.png
  4. Type a name for the new type and choose either Object or Array as the type. Click Create.
    When you click Create, the new type is added to the list in the Types tab. You now define the structure by adding attributes.
  5. In the Types tab, click Add ( Add icon ) next to the new type to add an attribute.
  6. Enter the name and select a type for the new attribute. Click Create.
    You can select the Create Another checkbox if you want to immediately add another attribute to the type.
You can continue to refine the data structure of the type by adding attributes.

Create a Custom Type From an Endpoint

When you create a custom type from an endpoint, you define a data structure by selecting an endpoint and then choosing from the fields available at the endpoint. Custom types can be used to define the structure of any variable in your application.

For example, when sending a request to an endpoint getall_Contact you might want the structure of the response to be an array with the id and a few specific fields (a string name and a string email). You can create a custom type from the endpoint and select the fields that you want in the response. All variables that are assigned this custom type will have the same data structure.

To create a custom type from an endpoint:

  1. Select your application, flow or page artifact in the Navigator.
  2. Open the Types tab in the artifact’s Variables editor.
  3. Click + Type and select From Endpoint in the menu.
  4. Select an endpoint from the list. Click Next.
  5. Select the endpoint attributes you want to include in the data structure. Click Finish.
If you expand your new custom type in the Types tab, you can see it is a custom object type with an array items containing the fields in the endpoint that you selected.

Work with Flow Artifacts

You use flows to group the pages of your application together.

Work with Page Flows

Each page in your application is contained within a flow. You create a flow to group one or more pages that you might want to treat as an independent unit that performs some function in your application, for example, a flow that contains the pages and artifacts used to register a new user.

Your application can have multiple flows. When you open your web or mobile application in the Navigator, you can expand the flows node to see each of the flows in the application. You can create new flows in your application by clicking the Create Flow icon ( Create Flow icon ) next to the flows node. When you create a flow, a page within the flow is automatically created and set as the flow's default page.

A flow named main is created by default when you create an application. By default, the main-start page in the main flow is set as the default page in the flow, and the main flow is set as the default flow in your application.



When you expand the flows node of a web or mobile application in the Navigator, you can see that a flow consists of the following artifacts and resources.

Artifact Description
Flow artifact

Open the flow artifact in the designer to edit the flow’s metadata, such as the variables, types, chains and functions that can be used in pages in the flow. In the Settings editor for the flow you can set the default page in the flow.

You can expand the flow artifact in the Navigator to see the pages contained in the flow.

Click the Create Page icon ( Create Page icon ) next to the flow artifact to create a new page in the flow.

Page artifact

Open each page artifact in the designer to edit the page’s layout and other page metadata.

Resources

Each flow might contain a resources folder that contains images and translation resources that can be used in pages in the flow. See Work with Application Resources.

Set the Default Page for a Flow

When you create a flow, a start page is automatically created and set as the entry page for the flow. You can change the flow’s default entry page in the Settings editor of the flow artifact.

To set the default page for a flow:
  1. Open the flow artifact in the Settings editor of the application designer.
  2. In the General Settings tab, use the Default Page dropdown list to select the page in the flow that you want to be the default page.

Embed a Flow Within a Page

Each flow in your app can contain multiple sub-flows, enabling you to embed pages within other pages. You use the Flow Container component to create a container in the page where you can then embed sub-flows. After adding the container, you set the default sub-flow displayed in the container in the General Settings tab of the page's Settings editor.

In the page containing the embedded flow, you can only edit the page content outside the Flow Container component, and the embedded pages are not visible on the canvas. After setting the default sub-flow for the page, you can run the app to see the embedded content in the page.

To edit a page in a sub-flow, you need to open it in the Page Designer. To help you visualize the page, the canvas displays the content embedded in the Flow Container component and the content of the parent page, but you can only edit the content in the Flow Container. You set the default page for the sub-flow in the General Settings tab of the sub-flow's Settings editor.

You can use an embedded flow to isolate content from the page containing the flow, and to allow navigation between pages in the sub-flow without leaving the page containing the sub-flow.

To embed a flow in a page:

  1. In the Navigator, locate the flow containing the page where you want to embed the flow.
  2. Under the flow containing the page, click Create Flow ( Create Flow ) and enter a name for the new sub-flow in the Create Flow dialog box. Click Create.
  3. Open the page where you want to embed the new flow.
  4. In the Page Designer, drag the Flow Container component from the Layout category in the Components palette and place it on the canvas.
  5. In the page's Settings editor, select the default sub-flow in the General Settings tab.
    The Default Flow dropdown list displays all flows within the current flow.

Navigate Between Flows in the Root Page

You can use the navigateToItem event in an action chain to open the start page of a flow in your app's root page. You typically invoke the action chain from the drawer or tab elements used to navigate the app.

To use the navigateToItem event in an action chain, you add the Fire Custom Event action to the chain and then select the event and assign the name of the target flow to the event's payload. To use the navigateToItem event, the current page needs to have a flow container that is configured to hold the target flow. Firing the event loads the start page of the target flow into the flow container of the root page.

For example, when you create an app from a template that uses navigation elements such as a tabs or a drawer, the app will contain separate flows that can be loaded into the app's root page. If you create a web app with two flows (for example, "item-1" and "item-2"), and you want to use tabs in your root page to select the flow that is displayed in the flow container, you can create an action chain that fires the navigateToItem custom event. You would create an action chain for each of the flows, and add a click event listener to each tab to trigger the action chain.

To create a new action chain that navigates to the start page in a flow:

  1. In the Designer, open the root page containing the flow container and select the component on the canvas that will open the flow.

    For example, to navigate between flows displayed in the main flow container of a web app you will need to open the root page and select one of the navigation tabs.



  2. In the Events tab of the Property Inspector, click New Event and select the Quick Start option.

    A new action chain opens in the Action Chain editor when you select the Quick Start option.

  3. Type a name for the action chain in the Id field of the Property Inspector.
  4. In the Action Chain editor, drag the Fire Custom Event action into your chain.
  5. In the Fire Custom Event pane, select application:navigateToItem in the Event Name drop-down list.

    The drop-down list contains a list of custom events that can be invoked by the action. The navigateToItem event is prepended with "application:" in the drop-down list and can be used in any page in your app because it is application-scoped.



  6. Click Assign to open the Fire Custom Event window for mapping the navigateToItem payload to the name of the target flow.
  7. Select item in the Target column and select Static content in the editor pane.
  8. Type the name of the target flow (for example, "item-1") in the editor pane of the window. Click Save.

Work with Actions and Action Chains

You create action chains to define the behavior of components in a page.

About Action Chains

An action chain is a sequence of actions that you create to define the behavior of components.

Action chains are triggered by events such as click, onValueChanged and focus that you add to components and page events. They have a scope property that determines where they can be used. The action chains that you create in a page’s Actions editor can only be used within the context of the page and cannot be used in other pages. Action chains that you create in the Actions editor for a flow can only be used within that flow. See Add Events to Components and Start an Action Chain with an Event.


Description of action-chain-simple-navigate.png follows
Description of the illustration action-chain-simple-navigate.png

For action chains that you might want to use in multiple pages of your application, such as one that navigates to the start page, you can create an action chain that is application-scoped.

You create action chains by assembling simple, individual actions into a sequence in the Actions editor. The Actions editor contains a palette of built-in actions that you drag onto the canvas where you create your sequence. After you add an action to the sequence you usually need to provide details required by the action. For example, when you add the Call REST Endpoint action to your action chain you need to specify the endpoint and other details about the response to the Call REST Endpoint action. Similarly, when you add the Navigate to Page action to an action chain, you are required to select a page in your application that the action navigates to.


Description of action-chain-palette.png follows
Description of the illustration action-chain-palette.png

The built-in actions are grouped in the palette by type. See Actions for a list of the built-in actions.

Create an Action Chain

You build action chains by dragging actions from the palette onto the canvas in the Action Chain editor.

To create an action chain:
  1. Open the Actions editor of your page.

    The Actions editor displays a list of the page’s action chains, or a message if no action chains are defined.


    Description of action-chain-editor-nochains.png follows
    Description of the illustration action-chain-editor-nochains.png
  2. Click + Action Chain.
  3. Enter a name for the action chain in the Id field. Click Create.

    The new action chain opens in the editor. The Action Chain editor contains the palette of built-in actions, a canvas and a property editor. The Start icon indicates the entry point of your action chain and the Add icon ( Add icon ) is a placeholder indicating where you can add an action to the chain. The property editor displays the properties of the action that is selected on the canvas.



  4. Drag an action from the palette and place it on the Add icon ( Add icon ) in the chain.

    Alternatively, you can click the Add icon ( Add icon ) in the chain and select an action in the popup menu of actions.


    Description of action-chain-editor-popupmenu.png follows
    Description of the illustration action-chain-editor-popupmenu.png

    To create a fork in your action chain, drag the action from the palette and drop it on the Add icon next to the action where you want the chain to fork. The Add icon appears next to each action in the chain when you drag an action from the palette.


    Description of action-chain-editor-forkchain.png follows
    Description of the illustration action-chain-editor-forkchain.png

    The new action is added to the chain and is selected by default. The property editor displays the properties that you can specify for the action. The properties depend upon the type of action.

  5. Specify the properties of the action in the property editor.
  6. Repeat steps 5 and 6 until your action chain is complete. The action chain is saved automatically.

    You can open your action chains at any time from the Actions editor and edit them as necessary.

    Tip:

    To remove an action from the chain, select the action on the canvas and click Delete ( Delete icon ) in the property editor.

When your action chain is complete you can start the action chain from an event in the page.


Description of action-chain-editor-finished.png follows
Description of the illustration action-chain-editor-finished.png

Start an Action Chain with an Event

You can start an action chain by defining an event listener that listens for a specific event, and when the event occurs the event listener can start one or more action chains. The types of events that are available depend on the type of artifact.

You select the type of event and the action chain in the Events editor of an artifact, such as a page. For example, you can use a page event, such as entering a page, to start an action chain. To start the action chain you would open the Events editor for the page to define an event listener, and then select the action chain that the event listener should start. To define the event listener, you select the event that the event listener listens for. This might be a default page event, like vbEnter, but it can also be a component event that you added to a component, like ojAction, which is usually applied to a button component. When designing your page you can use a Quick Start to assign events to components. For the steps, see Add Events to Components.

When creating an event listener you also need to select the action chain that should be started. You can create a new action chain or select one from the list of action chains that are already defined. The action chains that can be started from the event will depend on the scope of the action chain.

To add an event listener to start an action chain:

  1. Open the Events editor for the page containing the event that you want to trigger the action chain.

    The Events editor displays a list of all event listeners defined for the page, including details about where events are fired and the components that are firing them. The list will contain some default events as well as any events that you have defined, such as component events.



  2. Click + Event Listener in the editor.

    The Select Event window displays a list of event types that the listener can listen for.


    Description of page-designer-events-select.png follows
    Description of the illustration page-designer-events-select.png
  3. Select an event type from the list. Click Select.
  4. Select the action chain that will be started by the event listener.

    You can select any action chain that is scoped for the artifact. The window lists all action chains that can be started in the current context, grouped by scope. For example, if you are creating an event for a flow artifact, you can only call action chains defined in the flow or in the application.



  5. Click Select.
After you create an event listener, you can click Add Action Chain if you want it to start additional action chains.

Add an Assign Variables Action

You add an Assign Variables action to an action chain to map the source of some value to a variable. The variable can be used by other action chains or bound to a component.

For example, if your action chain sends a request to a GET endpoint, you can use the Assign Variables action to map the response to a page variable bound to a page component. Or, suppose you want to capture the ID of an item selected in a list. You could use a Selection event to start an action chain that assigns the selected item’s ID to a variable.

To add an Assign Variables action to an action chain:

  1. Open the Actions editor for the page.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Assign Variables from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The property editor opens when you add the action to the chain.


    Description of action-chain-editor-assignvariable.png follows
    Description of the illustration action-chain-editor-assignvariable.png

    The Assign Variables action is badged with a warning icon when no variables have been assigned.

  4. Type a name for the action in the Id field in the property editor.
  5. Click Assign in the property editor to open the Assign Variables window to map the source of the value to a page variable.
  6. Drag the sources of the values in the Sources pane onto targets in the Targets pane. Click Save.

    Each target can only be mapped to one source, but you can use the action to assign multiple variables. For example, you might want to map a value from the Chain in the Sources pane, such as an input variable or the result of an action, to a Page variable or to the input of another action in the Target pane. When you select the variable in the Target pane, the expression editor in the dialog box displays the expression for the source.


    Description of action-chain-editor-assignvariable-mapdialog.png follows
    Description of the illustration action-chain-editor-assignvariable-mapdialog.png

Add a Call Action Chain Action

You add a Call Action Chain action to an action chain to start a different action chain.

The action can call other action chains defined in the same page or in the application.

To add a Call Action Chain action:

  1. Open the Actions editor for the page.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Action Chain from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The property editor opens in the editor when you add the action to the chain.


    Description of action-chain-editor-callactionchain.png follows
    Description of the illustration action-chain-editor-callactionchain.png
  4. Click Select Action Chain in the property editor.

    The Select Action Chain window displays a list of available action chains. Depending on where you are creating the action chain, the window might have tabs for action chains defined in the page, in the current flow and in the application. If you are creating an action chain in a flow artifact, you can only select other action chains defined in the same flow artifact or in the application artifact, and you will not see a tab for Page action chains. You can use the Filter text field to filter the action chains in the list.


    Description of action-chain-editor-selectactionchain.png follows
    Description of the illustration action-chain-editor-selectactionchain.png
  5. Optional: If the action chain that is called requires input parameters, click Assign in the Input Parameter section of the property editor to map the input parameter to a variable.

    The action in the action chain is badged with a warning icon when an input parameter is required but has not been assigned.

    You map variables to parameters by dragging the variable for the source value in the Sources pane onto the Parameter for the input parameter in the Target pane. Click Save.


    Description of action-chain-editor-callactionchain-map.png follows
    Description of the illustration action-chain-editor-callactionchain-map.png

Add a Call Component Method Action

You add a Call Component Method action to an action chain to call a method on a component.

To add a Call Component Method action to an action chain:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Component Method from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The property editor opens when you add the action to the chain.


    Description of action-chain-editor-callcomponentmethod.png follows
    Description of the illustration action-chain-editor-callcomponentmethod.png
  4. Type a name for the action in the Id field in the property editor.
  5. Enter the name of the component in the Component Selector text field.

    In the text field you enter the actual name of the component that you want to call, for example, $page.components.byId('myCard')

  6. Enter the Method Name and map the parameters required by the method.

Add a Call Module Function Action

You add a Call Module Function action to an action chain to call a function defined for the current page, current flow or the application. You create and edit module functions in the Functions editor.

To add a Call Module Function action to an action chain:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Call Module Function from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The property editor opens when you add the action to the chain.


    Description of action-chain-call-modulefunction.png follows
    Description of the illustration action-chain-call-modulefunction.png
  4. Type a name for the action in the Id field in the property editor.
  5. Click Select Module Function to open a window to select the functions available.
  6. Select the function in the Select Module Function window. Click Select.
    You can select functions that are defined for the current page, the current flow or for the application.
  7. Specify any input parameters and return type for the function in the property editor.
    You can click Assign to map variables to the parameters.

Add a Call REST Endpoint Action

When you add a Call REST Endpoint action to an action chain you might need to specify input parameters for the request or create variables for the response that you can bind to page components.

When you add the Call REST Endpoint action to an action chain, the endpoint that you select will depend upon the functions that are available. Depending on the function you might also need to create some variables to map to the action’s parameters, such as input parameters and the action’s results. If you did not create the variables before creating the action chain, you can edit the action chain after creating the variables you need.

For example, an endpoint might require an ID to identify a record. In this case you will need to create a page variable that stores the ID, and that variable needs to be mapped to the action’s input parameter.

You will use the Call REST Endpoint action in action chains that perform typical functions such as creating, updating and deleting records, and any time you want to display the details of a record in a page. You can use the Quick Starts to help you create the action chains and variables for these functions.

Type of Endpoint Typical Requirements
POST

When you call a POST endpoint you will typically need the following:

  • Parameters: The page variable for the data needs to be mapped to the parameters of the payload of the POST call.

  • No input parameter is required.

GET

When you call a GET endpoint you will typically need the following:

  • Input parameter: The ID of the record you want to retrieve should be passed as an input variable.

  • The payload of the GET call needs to be assigned to a variable using the Assign Variable action.

When you want to send a request to a GET endpoint to retrieve a collection, you will typically use a page variable of the type ServiceDataProvider.

DELETE

When you call a DELETE endpoint you will typically need the following:

  • Input parameter: The ID of the record you want to delete should be passed as an input variable.

  • There is no payload when calling a DELETE endpoint.

PATCH

When you call a PATCH endpoint you will typically need the following:

  • Input Parameter: The page variable storing the ID of the record you want to update should be mapped to the Input Parameter.

  • Parameters: The page variable for the updated data needs to be mapped to the parameters of the payload of the PATCH call.

To add a Call REST Endpoint to an action chain:

  1. Open the Actions editor for the page.
  2. Click the action chain in the list to open it in the Action Chain editor.
  3. Drag Call REST Endpoint from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The property editor opens when you add the Call REST Endpoint action to the action chain.


    Description of action-chain-editor-selectendpoint.png follows
    Description of the illustration action-chain-editor-selectendpoint.png

    The Call Rest Endpoint action is badged with a warning icon when no endpoint has been selected.

  4. Click Select Endpoint in the property editor.

    The Select Endpoint window displays a list of the endpoints that are available in your application. Each business object and service usually exposes multiple endpoints. The endpoint that you select will depend upon the function of the action chain. The endpoint that you select will also determine the properties that you will need to specify for the action, for example, input parameters.


    Description of action-chain-editor-selectendpoint-dialog.png follows
    Description of the illustration action-chain-editor-selectendpoint-dialog.png
  5. Select an endpoint from the list. Click Select.
  6. Edit the action’s properties in the property editor.

    The property editor is displayed when the action is selected on the canvas.


    Description of action-chain-properties-callrest.png follows
    Description of the illustration action-chain-properties-callrest.png
  7. Optional: If the REST call requires input parameters, click Assign in the property editor to open the window to map the variable for the input value to the action’s parameter. Click Save.

    You map variables to parameters in the Call REST Endpoint window by dragging the variable in the Sources pane onto the parameter in the Target pane. In some cases you might need to make multiple mappings. To delete a line mapping a variable to a parameter, place your cursor on the line and then right-click to open a Delete option. You can select the parameter name to view the expression for the mapped variable.


    Description of action-chain-map-inputparameters.png follows
    Description of the illustration action-chain-map-inputparameters.png

    If a suitable variable does not exist, you can create the variable in the Variables editor and edit the action later.

  8. Optional: If the REST call requires other parameters, click Assign in the Parameters section to open the window for mapping the variables to the action’s parameters. Click Save.

    If the structure and names of attributes match they can be automapped. The mapping can also be done individually.

  9. Optional: Specify any other parameters that may be required for the action.
After adding the Call REST Endpoint action, you can continue by adding more actions to the action chain, or by invoking the action chain from an event. If the REST call has a result, you might want to add a Fire Notification action, or add Assign Variables to the chain and map the result to a page variable.

Add a Fire Custom Event Action

You add a Fire Custom Event action to invoke a custom event that you have defined in your application.

A custom event can be defined in an application, flow or page, and can be used to perform some action, such as navigating to a page. A custom event can carry a payload that you define when you create the event. The Custom Events tab in the Events editor displays a list of the custom events available in the context.

To add a Fire Custom Event Action:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Fire Custom Event from the Actions palette into the action chain.
  4. Type a name for the action in the Id field in the property editor.
  5. Select the Custom Event in the Event Name drop-down list.

    The drop-down list displays the custom events that are available in the current context.

  6. Click Assign to open the Mapper and define the event's payload.

    The event payload depends upon how the custom event is defined. You can use the Mapper to map the payload to a source, such as a page variable, or define a specific value or expression.

Add a Fire Notification Action

You add Fire Notification actions to display notification messages in the browser window.

You add a Fire Notification action for each message that you want to add to the action chain. When you add the action you select the type of result that will cause the notification to fire by selecting a notification type. For example, if an error occurs when performing an action in the chain, the notification will appear if you select error as the notification type. If you also want a notification to appear when the action succeeds, you will need to add another Fire Notification action and set the notification type to confirmation.

To add a Fire Notification action to an action chain:

  1. Open the Actions editor for the page or application.
  2. Create an action chain, or open an existing action chain to add the action in the editor.
  3. Drag Fire Notification from the Actions palette into the action chain.

    You can drag the action onto the Add icon ( Add icon ) in the action chain, or between existing actions in the chain. The property editor opens when you add the action to the chain.


    Description of action-chain-editor-firenotification.png follows
    Description of the illustration action-chain-editor-firenotification.png
  4. Type a name for the action in the Id field in the property editor.
  5. Type the message to display in the Message field.

    The message you enter can be a static string (The name was updated.) or can contain variables ({{ 'Could not create new Contacts: status ' + $chain.results.createContacts.payload.status }}).

  6. Select a Notification Type to specify the type of result that will fire the notification, and a Display Mode to specify how the notification is displayed.

Add a Navigation Action

The Actions palette contains a Navigation section that provides actions for navigating to the previous page, a specific page in the application or an external URL.

When you add a Navigate action to an action chain to navigate to a specific page in your app, after you select the target page you can specify an input parameter to specify the id of a record.

To add a navigation action to an action chain:

  1. Open the Actions editor for Page.
  2. Click the action chain in the list to open it in the Action Chain editor.
  3. Drag an action from the Navigation section of the palette into the action chain.

    The Navigation section contains Navigate, Navigate Back and Navigate to URL actions


    Description of action-chain-navigation-actions.png follows
    Description of the illustration action-chain-navigation-actions.png

    You can drag the action onto the Add icon ( Add icon ) in the action chain, and typically this action will be the final action in the chain. The property editor opens when you add the Navigate to Page action to the action chain.

  4. Specify the details of the page or URL in the property editor, if required. If you add the Navigate Back action you do not need to specify any details.. If you add theNavigate to URL action you need to provide the URL in the property editor. If you add the Navigate action you need to perform the following steps.
    1. Click Select Target in the property editor.
    2. Select the context of the target in the Select Target window.

      The targets you can select will depend upon the context of your action chain. The target for a Navigate action can be one of the root (shell) pages of the application, another page in the current flow, or a different flow that is defined in the current page. One or more of these options might not be valid targets for your action chain. After you choose the context of your target you can choose from the available targets in that context.

      Description of action-chain-editor-selecttarget-db.png follows
      Description of the illustration action-chain-editor-selecttarget-db.png
    3. Select a page in the list. Click Select.

      If the page you select requires an input variable you will need to map a page variable to the action’s Input Parameter.

    4. Type a name for the action in the Id field in the property editor.

      When the action is selected on the canvas, you edit the action’s properties in the property editor.


      Description of action-chain-editor-navtopage.png follows
      Description of the illustration action-chain-editor-navtopage.png
    5. Optional: If the page requires input parameters, click Assign in the Input Parameters section to open a window to map the variable for the input value to the action’s parameter. Click Save.

      In the window, you map Sources to Targets by dragging the variable in the Sources pane onto the parameter in the Target pane. You can click the parameter name to view the expression for the mapped variable.


      Description of action-chain-map-pageinputparameters.png follows
      Description of the illustration action-chain-map-pageinputparameters.png

      If a suitable variable does not exist, you can create the variable in the Variables editor and edit the action later.

Test Action Chains

VB Studio provides an editor to help quickly generate unit tests for your action chains by generating suggestions for you of outcomes in the action chain to validate.

Using this editor, you can apply test-driven development as an approach in creating action chains. The editor detects what information needs to be provided at runtime to perform the actions in the action chain. This information includes values for variables and constants used by the action chain, and actions like Call REST endpoint actions, the results of which need to be mocked when running a test. Once the necessary context is provided, the editor generates suggestions for expected outcomes that you can add to the test, or you can add your own expected outcomes (expectations).

You access this editor from the Tests tab in the Actions editor of an individual action chain. Once in the editor, you can create one or more tests for the associated action chain. For each test, you define context, mock actions, and expected outcomes. A context refers to a variable that the action chain uses. If, for example, you have an action chain that uses a call module function that takes a subtotal variable as input and returns the total after tax, add a context entry that includes the subtotal variable and a sample value for the variable.

Mock actions are needed for Call REST Endpoint actions and other actions in the action chain. For each mock action, you specify a possible outcome for the action and a result. If, for example, your action chain includes a Call REST Endpoint action that fetches product information, you need to specify a mock action that has a success outcome and includes a sample result of product information. Right-click the action for which you need to define a mock action, and choose Mock Action from the context menu that appears to add a mock action. Finally, you specify the expected outcome(s) for the test. VB Studio generates a set of suggestions for expected outcomes that you can add to the test. You can add one or more of these expected outcomes to the test, and edit the expected outcome.

Once you have defined the test(s), you can run them individually or simultaneously using the appropriate button that the editor provides (Run or Run All).

The following image shows the Tests editor where three tests have been defined for an action chain that fetches product information. Two of these tests have run (Success Path and Failure Path), and one has not (Test Three). The red icon beside the Failure Path test indicates that it failed, as does the red border around the expectation for the fireNotification message where the test author set the expected outcome to Success! but the actual outcome was Bad Request. The green icon beside the Success Path test indicates that the test succeeded. No visual indicator appears beside Test Three because it has not yet been executed.

The percent value for Coverage indicates the level of test coverage for the actions in the action chain. If you create tests that include all actions in the action chain, and all expected outcomes for the actions, the percent value for Coverage will be 100%. In the following image, the test author removed a series of entries from the Expectations list for the Failure Path test, thereby reducing the Coverage percent value for the action chain to 83%. For the action chain in the image, you can increase the value for Coverage by adding entries that appear under the Suggestions list to the Expectation list.

Description of test-overview-threetests.png follows
Description of the illustration test-overview-threetests.png

The first time that you access the Tests editor, click the + Test button to create a test. The test name defaults to Test 1. Specify an alternative test name, if you want.

Once you create a test, the Tests editor enables the following UI controls that assist you in developing and running a test.

  • A pane on the right of the Tests editor appears where you can add context, mocks, and expectations for the test that you run.
  • Run and Delete buttons that you use to run and delete the test.

An aggregated view of all tests that you have defined for the mobile and web applications in your visual application can be displayed by clicking Tests in the status bar of your browser. This displays a view of all action chain tests per application, in addition to a visual indicator that gives the status of the test (Pass/Fail/Not Run). It also provides a button (Run All) that runs all tests in the visual application simultaneously.

Description of test-action-chain-aggregate.png follows
Description of the illustration test-action-chain-aggregate.png

Design Pages

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

Use the Page Designer

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

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


Description of page-designer-overview.png follows
Description of the illustration page-designer-overview.png
The Page Designer Toolbar

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

Toolbar Item Description
Component palette icon

Toggles the Component palette

Page Structure icon

Toggles the Page Structure view

Reload Page icon

Reloads the page

Page Input Parameters icon

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

WhoAmI icon

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

Device selector icon

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

Zoom Canvas icon

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

Live / Design / Code toggle icon

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

Expand Property Inspector icon

Toggles the Property Inspector in the Page Designer.

The Page Editor

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

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

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

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

The Components Palette

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

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


Description of page-designer-palette.png follows
Description of the illustration page-designer-palette.png
The Page Structure View

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

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



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

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



The Property Inspector

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

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

Activate Role-Based Application Preview

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

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

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


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

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



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

Work with Pages and Page Layouts

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

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

Create Pages

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

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

To create a new page in a flow:

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

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


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

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

Edit the App Header and Footer

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

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

To edit the app's header and footer:

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

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

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

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

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



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



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



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

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

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

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

To add a container or layout component to a page:

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

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



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

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

Add Components to Pages

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

About Page Components

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

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

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

Component Type Description

Common

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

Field

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

Collection

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

Layout

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

Chart

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

Gauge

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

Picker

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

Custom

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

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

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

Component Properties Description
General

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

Data

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

Events

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

All

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

Quick Starts

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

Add a Component From the Components Palette

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

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

To add a component from the Components palette:

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

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

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

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

Add a Component Using Code Completion in the Code Editor

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

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

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

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

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


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

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

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



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

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



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

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

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

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

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



Add Events to Components

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

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

To add an event and action chain to a component:

  1. Select the component.

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

  2. Open the Events tab in the Property Inspector.

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

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

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


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

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


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

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

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

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

Add an Image to a Page

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

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

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

To ensure that the relative path to the image resource is built correctly when the app is staged and published, the path to the image in the Source URL field needs to include the builtin variable $flow.path or $application.path to identify the location of the resource folder.

To add an image to a page:

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

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


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

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

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

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

To add an Icon component to a page:

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

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

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

When defining and adding a custom class to a component, you should exercise caution to ensure that your class does not conflict with the pre-defined classes already applied to the component.

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

To add a custom style to a component:

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

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



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

Filter Data Displayed in a Component

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

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

Note:

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

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

Attributes Description

attribute

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

op

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

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

value

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

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

Create a Filter for Component Data

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

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

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

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

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


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

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

    Tip:

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


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

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


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

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



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

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

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



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

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

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

Add Page Functionality Using Quick Starts

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

About Quick Starts

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

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

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


Description of page-designer-quickstarts.png follows
Description of the illustration page-designer-quickstarts.png
Add Data to a Table or List

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

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

The Add Data Quick Start does the following for you.

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

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


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

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


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

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

Use the Add Data Quick Start

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

To bind an endpoint to a collection component:

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

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

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

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

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

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

  • Creates an action chain for navigating to a page.

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

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

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

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

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

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

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

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


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

Use the Create Page Quick Start

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

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

To add a page to create a new business object:

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

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

Add an Edit Page With the Quick Start

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

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

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

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

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

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

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

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

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

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

The Quick Start does the following in the Edit page.

  • Adds a form with fields bound to a variable.

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

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

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

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

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

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

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


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

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


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

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

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

To create an Edit page:

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

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

Add a Details Page With the Quick Start

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

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

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

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

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

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

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

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

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

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

The Quick Start does the following in the Detail page.

  • Adds a form with fields bound to a variable.

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

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

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

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

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

Use the Add Detail Page Quick Start

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

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

To create a Detail page:

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

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

Work with the Functions Editor

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

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

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


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

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

Note:

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

Audit Application Code

Use the Audits feature to check and verify the code of your application as you develop it. This feature helps you catch and fix errors before you stage and deploy your application.

When you use Audits, VB Studio scans and runs checks on the code in your application and displays errors and warnings, if any. In addition to reporting errors related to JET components, the Audits pane displays other errors, such as syntax errors, warnings for missing dependencies, and translation-related errors. You can view details for the issues and also resolve issues from the Audits Pane.
  1. Click Audits to view the Audits pane.
    The application is scanned and results are displayed in the Audits pane. The results are sorted into four categories based on severity.
  2. Review the listed issues.
    For each issue, you can review severity, issue details, source and location.
  3. Optionally, filter the issue list to review specific issues by using the Search field and by selecting or deselecting the severity buttons.
  4. Select an issue and click the Menu icon (Menu icon).
  5. Select Open in Source Editor or Open Artifact to view the source code for the issue.
  6. Select Do not report this type of defect again to ignore similar defects in future.
  7. Resolve the issue, if possible, by selecting the appropriate option.

    For example, for the String not externalized for translation issue, select the Add to translation bundle option to fix the issue.
    Description of audits_extr_tran_resolve-png.png follows
    Description of the illustration audits_extr_tran_resolve-png.png

    Similarly, for the Element should have non empty ID attribute type issues, select the Add missing ID attribute option to fix the issue.
    Description of audits_miss_attr_resolve-png.png follows
    Description of the illustration audits_miss_attr_resolve-png.png

Secure the Application

You can secure access to your application with user credentials, and also create user roles to secure data at the level of the business object.

About Authentication Roles and User Roles

You use authentication to manage access to the pages and data in your application. In addition to the default authentication roles, you can fine tune access to your application resources by creating user roles and assigning authenticated end users to them.

All app users are automatically assigned either the Anonymous User or Authenticated User authentication role, or both. If access to the app requires authentication, all users are automatically granted the role Authenticated User when they sign in. If anonymous access to the app is also allowed, users that sign in are granted the Authenticated User role AND the Anonymous User role, and users who are not signed in are only granted the Anonymous User role. You can use these roles when granting permissions to operations on business objects when role-based security is enabled. The following table describes the two authentication roles.

Authentication Role Description
Anonymous User

All users who access VB Studio applications are assigned this role when anonymous access to the application is enabled.

Authenticated User

All users who access VB Studio applications are assigned this role after they sign in. An authenticated user can see all components and manage business objects unless access to the object is explicitly disabled for the Authenticated User role.

All developers are assigned this role by default.

You use user roles to secure access to business objects and data in your application. The application’s user roles ensure that users assigned the same role or group in the Oracle PaaS identity provider are granted equal access in your application. You define the user roles for the visual application in the User Roles tab of the visual application’s Settings editor. The user roles defined for your application are stored in user-roles.json in the visual application's settings folder. See Manage User Roles and Access.

You assign users or groups in the identity domain to a user role in your visual application, but only identity domain administrators can add users to the identity domain, and it is the responsibility of the identity domain administrator to add users to groups and maintain them in the identity provider. Administrators manage groups using Oracle Identity Cloud Service (IDCS), or use Oracle Shared Identity Manager (SIM) to manage roles for services using a Traditional Cloud Account. All user authentication is delegated to the identity provider.

When a user attempts to access data in a business object secured by a user role, the roles assigned to the user are authenticated in the identity provider. The user is granted access if one of the user roles securing the business object is mapped to one of the roles or groups the user has been assigned to in the identity provider. Security based on roles is disabled by default. You can set role-based security and privileges for viewing, creating, updating and deleting objects in the Security tab of the business object in the Business Objects editor. See Secure Business Objects.

Note:

By default, Authenticated Users can access all objects and components in your application. To thoroughly enable role-based security you must explicitly specify authentication or visibility for an object to a user role and disable access for the Authenticated User authentication role.

About Anonymous Access

You can enable anonymous access to allow users to access your app without signing in. If anonymous access is not enabled, all users must sign in with the credentials of their Oracle Cloud Account.

All users accessing your app are assigned roles that can be used to secure access to the data and services in the application. By default, your application requires authentication, but you can use the Settings editor of the app artifact to allow anonymous access to the app. When anonymous access is enabled, users that do not sign in are assigned the Anonymous User authentication role. By default, users assigned this role cannot access the data stored in your visual application’s business objects and data retrieved from services. You must explicitly allow anonymous users access to the data by configuring the security settings of business objects and services. See Access and Secure Business Objects and About Service Connection Authentication and Connection Type.

Changes that you make to authentication and security settings are only applied when you stage or publish the application. The versions of your application that are currently staged or published are unaffected. For example, if your application is already published, you must create a new version of the application before you can change the security settings. You then must stage and publish the application when you want the new security settings to take effect.

Note:

The following table describes the options for allowing anonymous access to your application and artifacts.

Allow Anonymous Access Options Description Behavior
Web and mobile applications

You enable the Allow Anonymous Access option for a web or mobile app in the Security tab of the Settings editor for the application artifact. Settings for anonymous access must also be set explicitly for business objects and service connections.

This option must be enabled to allow anonymous access to services and business objects.

When enabled, users are not required to sign in. Users that are not signed in are assigned the role Anonymous User. Signed in users are assigned the Anonymous User AND Authenticated User.

Business objects

You enable anonymous access to business objects by enabling role-based security in the business object’s Security tab and specifying the operations that the Anonymous User authentication role can perform. See Secure Business Objects.

When enabled, anonymous users can perform operations on custom business objects based on the permissions granted to the Anonymous User authentication role.

Service connections

You enable anonymous access to service connection data by enabling and specifying the authentication mechanism for anonymous access in the Security field of the dialog where you add or modify a server that the service connection uses. See About Service Connection Authentication and Connection Type.

When enabled, anonymous users can access data from the service connections that are configured to allow anonymous access.

Allow Anonymous Access

To allow anonymous access to an app and its data, you edit the security settings of each app artifact, business object and service connection. If your application is already published, you must create a new version and then change the security settings and publish the application.

Enabling anonymous access in the app artifact's Security tab is required to enable users to access the app without signing in. When anonymous access is enabled for an app, the following property is defined in app-flow.json:

"security":{
      "access":{
          "requiresAuthentication": false
      }
  }

To allow anonymous access to an app and data in its business objects and from services:

  1. Open your web or mobile application in the Navigator.
  2. Open the application artifact and select the Settings editor in the designer.
  3. Open the Security tab and select Allow anonymous access in the Access pane.
  4. Open the Security tab of the business object.
  5. Enable Role-based Security (if not enabled).
  6. Configure the rights granted to users assigned the Anonymous User authentication role.
  7. Open the Authentication tab of the service connection.
  8. Select Allow anonymous access.

    If the Allow anonymous access option is not visible, you might need to select Enable authentication / proxy and also confirm that anonymous access is an option for the authentication mechanism used to connect to the service.

  9. Select the Anonymous Authentication Mechanism from the dropdown list.

If you want to allow external clients anonymous access to the Describe endpoint for business objects in your visual application, select Allow anonymous access to business objects Describe endpoint in the Business Objects tab of the visual application's Settings editor. If you choose to allow anonymous access, access to an endpoint will still require adding the header “Authorization: Public” to the request. This header is injected automatically for requests sent from your visual applications.

Manage User Roles and Access

You can create, edit and remove the user roles used to secure access to business objects in your application.

In addition to the Authenticated User role, when a user signs in to your application, they can be assigned an application user role based on their user credentials and the roles or groups they have been assigned to in the identity provider. You use the User Roles tab in the visual application’s Settings editor to create user roles and assign roles and groups in the Oracle PaaS identity provider (IDCS) to the user roles. When you create a user role, the role and any groups or users assigned to it are automatically added to the application in IDCS.

After creating a role, you can secure access to business objects by specifying the application user roles that can access the object and setting the access privileges for the role in the business object’s Security tab.

To create a user role in your visual application:

  1. In the visual application workspace toolbar, click the Options menu.
  2. Click Settings.
  3. Open the User Roles tab in the Settings editor.

    The User Roles tab displays a tile for each user role in your application, and the groups and users that have been assigned to it.



  4. Click Create Role.
  5. Type the name in the Create Role dialog box. Click Create.

    This role name is displayed when designing your application. It is not exposed to end users.

  6. Click Assign groups or users in the tile if no users or group have been assigned.

    If you want to edit a user role and some groups or users have already been assigned to it, click the Edit icon in the tile.

  7. In the Change Assignments dialog box, click the Add icon for each group that you want to assign to the role. In the Users input field, type the name of the user that you want to add, or type a character to retrieve a list of users if you cannot remember a user’s full name. For example, type a to retrieve all user names that include the character a. Click Save Changes.


    You can assign multiple groups and roles to your user role. The list of groups and users is defined in the identity provider and managed by the identity domain administrator. When you save your changes, the user roles for your application in IDCS is automatically updated.

Embed a Web Application

Your web application can be embedded in sites in domains associated with your Identity Domain as well as external sites.

You must explicitly allow embedding in your web application’s settings if you want to allow other applications to embed your application. For example, if you know that another site wants to use pages and data from your web app in their site, and they don't want to or can't link to your app, you can allow your app to be embedded in their app.

For security reasons, all embedding is denied by default. You can use the Settings editor in the application designer to edit the metadata of the application artifact. The web application’s security settings are stored in the configuration.json file, which is located in the application’s settings folder when you browse the application’s sources.


Description of settings-embedding.png follows
Description of the illustration settings-embedding.png

To allow your web app to be embedded in another app:

  1. Open the web application in the Navigator.

  2. Select the application artifact to open it in the application designer.

  3. Click Settings in the application designer and open the Security tab in the Settings editor.

  4. Enable Allow embedding in any application domain.

When your app is embedded within another app, the preferred method is for the other app to only embed the content of the page and not display the elements that wrap the content. For example, you might want to prevent a user from opening your app's user menu and logging out when it is embedded in another app. You can edit the shell template page to remove content such as the header and footer elements that you don’t want to appear when the page is embedded.

Configure Basic Authentication for a Mobile Application

Mobile applications that you develop with VB Studio can use basic authentication rather than the default Oracle Cloud authentication mechanism.

To use basic authentication, you specify a login endpoint URL and logout endpoint URL in the input fields that appear when you select Basic as the authentication mechanism in the Security tab of the mobile application's settings. At runtime, the mobile application presents a login screen where the user enters their user name and password (user credentials). These user credentials are converted into a basic authentication header and the login URL is invoked to pass the basic authentication header to the authentication service. On successful authentication, the user is navigated to the home page of the mobile application. If you want to pass additional HTTP headers to the service that you are connecting to through basic authentication, click New Header to display input fields where you enter the HTTP header(s) you want to pass.

The login and logout endpoint URLs can be any third party or Oracle Cloud service URL that supports basic authentication. This contrasts to the Oracle Cloud authentication mechanism which requires the user to have a valid account in the Oracle Identity Cloud Service that is associated with VB Studio.

There are a number of things you need to know if you configure basic authentication for your mobile application. User roles, which secure access to individual page flows or business objects in your application based on the user’s role, cannot be used if you configure basic authentication for your mobile application. The built-in variable, user, which accesses information about the current user when the mobile app uses the Oracle Cloud authentication mechanism, does not return information when the mobile app uses basic authentication.

Mobile basic authentication is not designed to use any Visual Builder server runtime artifacts like the Visual Builder proxy. Therefore, the connection type that you use must be Dynamic, the service supports CORS. Propagate Current User Identity and None are the two authentication mechanisms for REST service connections that you can use if your mobile application uses basic authentication. We recommend that you use Propagate Current User Identity to pass the user credentials entered by the mobile application user to the REST service. Note though that you cannot use Propagate Current User Identity while you develop and test the mobile application in VB Studio using the Page Designer’s Live and Design modes or run it in a separate browser tab. For these scenarios, temporarily use one of the following authentication mechanisms for the REST service connection:

  • Basic
  • OAuth 2.0 Client Credentials
  • OAuth 2.0 Resource Owner

Once you complete testing the mobile application in VB Studio and are ready to install it on a device, switch the authentication mechanism that the REST service connection(s) in the mobile application use back to Propagate Current User Identity and the connection type to Dynamic, the service supports CORS.

REST services that permit anonymous access can be accessed from a mobile application that uses Basic as its authentication mechanism if the REST service connection in the mobile application is configured to use None as the authentication mechanism.

Basic authentication is not a supported option for mobile apps that enable PWA support.

Configure Data Cache and Offline Support

Use the Oracle Offline Persistence Toolkit to enable data caching and offline support within your application.

The toolkit is a client-side JavaScript library that is delivered ready-to-use by VB Studio. The toolkit provides caching and offline support at the HTTP request layer. This support is transparent to the user and is done through the Fetch API and an XHR adapter. HTTP requests made while the client or client device is offline are captured for replay when connection to the server is restored. Additional capabilities include a persistent storage layer, synchronization manager, binary data support and various configuration APIs for customizing the default behavior. This toolkit can be used in both ServiceWorker and non-ServiceWorker contexts within web and hybrid mobile apps.

Using the toolkit, you can configure your application to:

  • Download content for offline reading where connectivity isn’t available.

    For example, an application could include product inventory data that a salesperson could download and read at customer sites where connectivity isn’t available.

  • Cache content for improved performance.
  • Perform transactions on the downloaded content where connectivity isn’t available and upload the transactions when connectivity returns.

    For example, the salesperson could visit a site with no Internet access and enter an order for some number of product items. When connectivity returns, the application can automatically send the transaction to the server.

  • Provide conflict resolution when the offline data can’t merge with the server.

    If the salesperson’s request exceeds the amount of available inventory, the application can configure a message asking the salesperson to cancel the order or place the item on back order.

The architecture diagram illustrates the major components of the toolkit and how an application interacts with it.

To use the toolkit in a web or mobile application, you update the application’s app-flow.js file to include an OfflineHandler() function that determines the scope of data in your application to cache, what type of caching strategy from the toolkit to use, and so on. The following commented app-flow.js file demonstrates one scenario of how you might go about implementing caching and offline capabilities in your application. The following app-flow.js file also demonstrates how you enable the logging functionality of the toolkit while you develop the application that uses the toolkit. Enabling this type of logging during the development phase will help you understand what data the toolkit caches offline in your application. Disable the logging functionality when you are ready to publish your application in a production environment.

Responses from REST services to your application must not include either the no-cache or no-store value in the Cache-Control HTTP header as these values prevent the toolkit from working in your application. Work with the administrators of the REST services that your application connects to so that values in the Cache-Control HTTP header are configured appropriately.

Oracle maintains the persistence toolkit as an open-source project. For additional information about using the toolkit, see the README.md and Wiki for the persistence toolkit on Github at https://github.com/oracle/offline-persistence-toolkit. API documentation for the toolkit is linked to from the aforementioned Github page, but can also be accessed directly at https://oracle.github.io/offline-persistence-toolkit/index.html.

define([
    'vbsw/helpers/serviceWorkerHelpers',
    /**
     * Add the following entries to include the toolkit classes that you'll use. More information about these
     * classes can be found in the toolkit's API doc. See the link to the API doc in the paragraph before 
     * this sample file.
     * 
     */
    'persist/persistenceManager',
    'persist/defaultResponseProxy',
    'persist/fetchStrategies',
    /**
     * Add the following entry to enable console logging while you develop your app with the toolkit.
     */
    'persist/impl/logger'
],
    function (ServiceWorkerHelpers, PersistenceManager, DefaultResponseProxy, FetchStrategies, Logger) {
        'use strict';

        function AppModule() { }

        function OfflineHandler() {
            /**
             * Enable console logging of the toolkit for development testing
             */
            Logger.option('level', Logger.LEVEL_LOG);
            Logger.option('writer', console);

            var options = {
                /**
                 * The following code snippets implements the toolkit's CacheFirstStrategy. This strategy 
                 * checks the application's cache for the requested data before it makes a request to cache 
                 * data. The code snippet also disables the background fetch of data.
                 */

                fetchStrategy: FetchStrategies.getCacheFirstStrategy({
                    backgroundFetch: 'disabled'
                }),
            };
            this._responseProxy = DefaultResponseProxy.getResponseProxy(options);
        }

        OfflineHandler.prototype.handleRequest = function (request, scope) {
            /**
             * (Optional). Write output from the OfflineHandler to your browser's console. Useful to help 
             * you understand  the code that follows.
             */
            console.log('OfflineHandler.handleRequest() url = ' + request.url + ' cache = ' + request.cache +
                ' mode = ' + request.mode);

            /**
             * Cache requests where the URL matches the scope for which you want data cached.
             */
            if (request.url.match(
                'http://localhost:1988/webApps/ifixitfaster/api')) {

                return this._responseProxy.processRequest(request);
            }
            return PersistenceManager.browserFetch(request);
        };

        OfflineHandler.prototype.beforeSyncRequestListener = function (event) {
            return Promise.resolve();
        };
        OfflineHandler.prototype.afterSyncRequestListener = function (event) {
            return Promise.resolve();
        };
        AppModule.prototype.createOfflineHandler = function () {
        /** Create the OfflineHandler that makes the toolkit cache data URLs */            
            return Promise.resolve(new OfflineHandler());
        };
        AppModule.prototype.isOnline = function () {
            return ServiceWorkerHelpers.isOnline();
        };
        AppModule.prototype.forceOffline = function (flag) {
            return ServiceWorkerHelpers.forceOffline(flag).then(function () {
                /** if online, perform a data sync */
                if (!flag) {
                    return ServiceWorkerHelpers.syncOfflineData();
                }
                return Promise.resolve();

            }).catch(function (error) {
                console.error(error);
            });
        };
        return AppModule;
    });

Work with Application Resources

You can import and export the resource files that are used in pages in your application.

About Application Resources

By default, each web and mobile application contains a resources folder for the components, images, translation files and other resources that can be used in the application. A flow artifact can also contain a resources folder for images and translation bundles used by pages in the flow. A page artifact can contain a resources folder for translation bundles.

To add resources, you can use the import tool in the Navigator and Source View to add folders and files to your application, for example, to add files and resources from other applications. Resources are typically files that you import to support or add functionality to pages in your application. For example, if you want to use an image in a page, you can import the image as a resource into an images folder and then use an image component in a page that references the image location.

Each of your web and mobile applications has one or more resources folder containing the application’s resources. By default, the application artifact contains a resources folder containing folders for the following types of resources.

Folder Description
components

This folder contains your application’s Composite Components. Composite Components that you import in the Page Designer are saved to this folder. You can also click Create Composite Component in the Navigator to create a custom Composite Component.

css

This folder contains the app.css stylesheet that is linked from pages in your application. The stylesheet is empty by default. You can edit the stylesheet to add custom styling to page elements. app.css is not used to control the styling of Oracle JET components.

images

This folder is the default location for any custom images that you might want to add to your application. Images in the application’s resources directory can be used in any page in the application. This folder contains two favicon files by default (favicon-dark.ico and favicon-light.ico). Web and Progressive Web Apps uses these favicons. The favicon used depends on the mode the app uses (light or dark mode). Overwrite the default-provided favicons if you want to use your own favicons. See Work with the Image Gallery.

Flow artifacts can also contain an images folder that stores images that can be used in pages in the flow. When you add an image to a page, it is stored in the images folder in the resources folder of the flow that contains the page.

strings

This folder is the default location for your translation bundles. See About Translation Resources.

Flow and page artifacts can also contain a strings folder that stores translation bundles.

Import Resources

By default your application contains folders for components, stylesheets, images and translation files. To add resources, you use the Import command to add files to your application, for example, to add files and resources from other applications.

You can import resources by uploading individual files and ZIP archives using the Import command available when you right-click an artifact or a resources folder in the Navigator, or by dragging the files directly from your local file system onto a folder in the Navigator. You can create new sub-folders by modifying the path in the Import Resources dialog box.

You can import resources into the application’s resources folder and sub-folders, or any other artifact in the Navigator. The location you select will determine the scope of the resources you import. When you import the resource, you should confirm the Import location . For example, you can import an image into the flows folder, but the expected location for an image is in an images folder in one of your application’s resources folders. Images that are not in an images folder will not appear in the Image Gallery.

To import resources into a new application:

  1. Open your web or mobile application in the Navigator and locate the folder or artifact where you want to import the resource.
  2. Right-click the folder or artifact and choose Import in the popup menu.

    Description of artifact-browser-import-resource.png follows
    Description of the illustration artifact-browser-import-resource.png

    Alternatively, drag a file from your local file system onto the folder or artifact in the Navigator to open the Import Resources dialog box.

  3. In the Import Resources dialog box, choose the file or archive with the resources you want to import. You can drag the resource into the drop target area or click the drop target area to navigate to the resource on your local system.

    Optionally, you can edit the path in the Import location field to create new folders.


    Description of artifact-browser-import-resource-dialog.png follows
    Description of the illustration artifact-browser-import-resource-dialog.png
  4. Click Import.

Export Resources

You might want to export an application’s resources when you want to import them into another application or share them with a team member.

You can download an application’s resources by exporting the application as an archive.

To export an application’s resources:

  1. In the visual application workspace toolbar, click the Options menu.
  2. Click Export.
  3. Click one of the export options to download the archive.

    You can choose if you want the application archive to include the data stored in the application’s custom business objects.


    Description of export-application-dialog.png follows
    Description of the illustration export-application-dialog.png
The application archive includes the application’s resources.

Work with the Image Gallery

You use the Image Gallery to import image resources into your application and when selecting the image resource referenced by an image component. You open the Image Gallery from the Data tab in the Property Inspector when an image component is selected on the canvas.

Images in your application are stored in an images folder located in one of the resources folders in your application. A folder for resources in your application is created by default when the application is created. Images in the application’s resources folder can be used in any page of your application. In addition to the application’s default resources folder, each flow in the application might have a resources folder for resources used in pages in the flow.

You can use the Image Gallery to view and manage the images in your application. The Image Gallery only displays the images that are stored in the images folders of the application and the current flow. Images stored in other locations are not visible in the Image Gallery.

You can use the Image Gallery to perform the following tasks:

  • Import images. You can choose to add images as resources of the current flow or the application.

  • Select an image displayed by an image component. You can select images stored in the application’s or the current flow’s images folder. When you select the image, the path to the image (for example, {{ $flow.path + 'resources/images/myimage.png' }}) is entered in the component’s Source URL field in the Property Inspector.

To import images into the Image Gallery:

  1. Open a page in the Page Designer and select an image component on the canvas.

    You can select any image component on the canvas. Alternatively, you can temporarily drag an image component onto the canvas.

  2. Open the Data tab in the Property Inspector and click the Image Gallery icon ( Image Gallery icon ).

    When an Image component is selected on the canvas, the Data tab in the Property Inspector displays a Source URL field for the path to the stored image. The field is empty when no image has been defined.


    Description of page-designer-inspector-newimage.png follows
    Description of the illustration page-designer-inspector-newimage.png

    You need to open the Image Gallery to add images to the application’s images folder. If you drag an image into the drop target area in the Data tab, the image is added to the flow in the Image Gallery and the path to the image is automatically entered in the Source URL field, but the Image Gallery dialog box does not open.

  3. Select Application in the Images panel of the Image Gallery.

    Alternatively, you can select Flow in the Image Gallery to import images into the flow’s images folder. The folder will be created automatically if it does not exist.


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

    The Images panel of the Image Gallery displays a list of the images that can be used in pages in the application and in the current flow. In the Application section, two favicon images also appear that VB Studio uses for web and Progressive Web Apps. Overwrite these to use your own favicon images. You can select an image in the Images panel to preview the image. If you select an image in the Images panel and click Select, the path to the image will be entered in the Source URL for the image component in the Data tab.

  4. Drag your image into the drop target area in the Image Gallery.

    Alternatively, you can click the drop target area to select an image using your local system’s file browser. You can import as many images as you want, but you need to add them individually. You can choose if you want to import an image into the Application or Flow resource folders by selecting the folder in the Images panel.

  5. Click Close to close the Image Gallery without selecting an image for the image component.

Update Your Oracle SaaS Application Template Theme

If your visual application uses a theme provided by an Oracle SaaS application template, you will need to update the template when new versions are released. New versions are typically released when a new version of Oracle JET contains changes that might affect how components used by the template are displayed. After downloading the new application template, you import it into your application as a resource and then select the new theme provided by the template in the app's Settings editor. For details on how to import the application template, see Work with Application Resources.

If you have existing visual applications that use the sample R13 SaaS LightBlue theme from an earlier version, you'll need to upgrade the theme before running the app under Oracle Visual Builder Studio 19.4.3. To upgrade the theme, download the updated version of the Oracle SaaS R13 theme files (ApplicationsCloudUI-export-3.0.0.zip) from the vbcs-samples repository on GitHub, import the update theme resources into your application and select the updated theme in your web app's Settings editor. For details on the upgrade steps, see Upgrading the Sample R13 SaaS LightBlue Theme for Visual Builder 19.4.n.

Work with Oracle JET Web Components

Oracle JavaScript Extension Toolkit (JET) Web Components are supported by visual applications at both run time and design time.

About Oracle JET Web Components

You can import Web Components as archives or directly from the Component Exchange associated with your instance. See Web Components in the JET Cookbook for an example of a Web Component.

To view the Web Components that have been imported into your web or mobile app, expand the resource node in the Navigator:



A Web Component must contain the following files. It may also contain additional files and folders, for example, a SCSS file or resources such as translation files.

File Description
loader.js A RequireJS module that defines the Web Component dependencies for its metadata, View, ViewModel, and CSS. The naming convention for Web Components requires that the name of the file is loader.js.
component.json A Web Component metadata file that defines its available properties and methods. The naming convention for Web Components requires that the name of the file is component.js.
view.html The view for the Web Component
viewModel.js Describes the ViewModel for the Web Component where methods defined in the Web Component metadata are defined
styles.css Contains the custom styling for this Web Component

Note:

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

Work with the Component Exchange

The Component Exchange is a repository of components that can be installed in your VB Studio instance.

Your VB Studio instance administrator specifies the Component Exchange that is associated with the instance. All developers in the instance are able to use the same set of components. The exchange contains a set of default components that have been provided by Oracle, and any components that other developers have published to your exchange.

The Components tab in the Navigator helps you to install and manage the components that you download from the Component Exchange.



The Components tab has the following tabs for locating and managing components from the exchange:

  • Browse - Use to search the Component Exchange for components that can be installed, to open a component's details page and to install components.

  • Installed - Use to view a list of installed components. The tab displays details about each component, and components are badged to indicate warnings or available updates.

  • Updates - Use to view a list of available updates and to update components to the latest version.

Get Components From the Component Exchange

If your administrator has associated your instance with the Component Exchange, you can use the Components tab in the Navigator to add and manage those components.

To add a component from the Component Exchange:

  1. Open the Components tab in the Navigator.
    Alternatively, in the Components palette in the Designer you can click Get Components in the Options menu, or click the Search Exchange button that is displayed in the palette when you use the palette’s filter field.
  2. Locate the component you want to install and click Install.

    You can click the component in the Components tab to open a tab containing details about the component, including a description and examples of how to use the component.



After you install the component, it's added to your Components palette. You can now drag the new component onto the canvas and use it in your pages.
Update a Component from the Component Exchange

When a newer version of an installed component is available, you can install it in the Updates tab in the Components pane. You'll know an update is available when you see a notification in your browser window or a badge over the Components icon in the Navigator.

To update a component from the Component Exchange:

  1. Open the Components tab in the Navigator.
  2. Open the Updates tab in the Components tab.

    If you installed a component that is part of a pack, the Updates tab displays the name of the pack containing the newer version of your component.



  3. Click Update All to install all updates available for installed components.

    To update an individual component, click the component's name to open its detail page, then click the Update button.



    If the installed component is not compatible with the JET version in your VB Studio instance, you'll see a notice to that effect.

Uninstall a Component

When you no longer want to use an installed component in your application, you can uninstall it to remove it from your Components palette.

To uninstall a component:
  1. Open the Components tab in the Navigator and locate the component you want to uninstall.

    If you know the name or details about the component you can use the Search field to filter the list of components.

  2. Click the component to open the component's details page.
  3. Click Uninstall Component in the details page.

Import a Web Component Archive

If you want to use a Web Component but it is not available in your Component Exchange, you can import the component as a ZIP archive. For example, if you want to use a component that your team member is currently developing, they can give it to you as an archive so that you can try it in your application.

To import a custom Web Component archive:

  1. Open the application into which you want to import the component.
  2. Open a page in your application in the Page Designer.
  3. Locate the Custom section in the Components palette and click Import Custom Component ( Import Custom Component icon ).
  4. Upload your ZIP archive in the Import CCA Component dialog box. Click Import.

    You can add the ZIP archive by dragging it into the upload area or clicking the area and locating the file on your local system.


    Description of page-designer-component-import.png follows
    Description of the illustration page-designer-component-import.png

The imported Web Component is displayed in the list of components in the Custom category of the Components palette or in the category specified by the component’s metadata. After importing the Web Component, you can position it in your page and configure its properties in the Property Inspector as you would a standard component.


Description of page-designer-component-custom-imported.png follows
Description of the illustration page-designer-component-custom-imported.png

Create a Web Component

Oracle JavaScript Extension Toolkit (JET) Web Components are reusable pieces of user interface code that you can embed as custom HTML elements. You can create a Web Component from a template that comes with VB Studio.

When you use the Create Component dialog box to create a component, the new component contains the JavaScript, HTML, stylesheet and JSON files required. The files contain sample code to help you get started. After you create the Web Component, you can click the component artifact in the Navigator to edit each of the component’s files.


Description of component-editor.png follows
Description of the illustration component-editor.png

To create a Web Component:

  1. Expand the Resources node of your web or mobile application in the Navigator.
  2. Click Create Component ( Create Component icon ) next to the components node.
  3. Type the ID for the component in the Create Component dialog box. Click Create.
The new Web Component is displayed under the components node in the Navigator.

Work with Translations

You can use the Property Inspector to bind text strings to values that are stored as keys and values in JSON files. You can open and edit the translation JSON files in the code editor, and download and upload the files as application resources.

About Translation Resources

The keys and values for translating your application are stored as JSON files in translation bundles in your application.

The names and locations of your translation bundles are up to you, but you must understand the rules governing the file names and the structure of your bundle to ensure that the bundles are recognized when you run your application.

By default, web and mobile apps will contain a default app-level bundle with the name app located in the resources/strings folder of the app. The relative path to the default translations bundle is stored in app-flow.json. The path identifies the top-level JSON file in the bundle that identifies the translation locales included in the bundle. If you open the application artifact in the code editor you can see the entry for the path to the translation bundle.

    "translations": {
        "app": {
            "path": "./resources/strings/app/nls/app-strings"
        }
    },

The suggested location for a bundle is resource/strings/<bundle-name>/nls/<bundle-name>-strings.json, where <bundle-name> is the name for the bundle you create. Bundles can be located where you choose, however the paths to the bundles must be specified in app-flow.json. For example, if you created a resource folder containing a bundle for the flow MyFlow, the path in app-flow.json might be similar to ./MyWebApp/flows/MyFlow/resources/strings/MyFlow/nls/MyFlow. You would use the period ( . ) at the beginning of the path to make it relative to the file.

When using translations in code, you can replace code that produces or uses an untranslated string with code that uses the translations object to retrieve the translated string from the bundle. For more on the translations object, see Translations.

Understand the Structure of Translation Bundles

You will want to understand the structure of translation bundles if you want to create additional translation bundles in your application.

The following guidelines describe the structure for the application’s default translation bundle:

  • The bundle contains a root folder named nls.

  • The nls folder should contain a JSON file identifying the translation locales contained in the bundle.

  • All bundle files should be JSON files with –strings.json appended to the bundle name. (For example, the JSON files for the MyNewPage bundle will be named MyNewPage-strings.json.)

The path to the root JSON file in each bundle in your application must be specified in app-flow.json.

Description of translations-resources.png follows
Description of the illustration translations-resources.png

Your bundle contains a JSON file at the root level of the nls folder that identifies the supported languages, and one or more folders within the nls folder containing JSON files storing the keys and values of translation strings. By default, the nls folder contains a folder named root that contains the root translation file app-strings.json.

When no additional locales are specified, the root level app-strings.json file only contains "root": true. If one additional locale is supported, for example, a French locale and translations, the root level JSON file would contain the following locale identifiers:

{
  "root": true,
  "fr": true
}

For each locale, the nls folder should contain a corresponding folder containing a JSON translation file with the translation strings for that locale. The default name for the JSON file in the root folder is <bundle-name>-strings.json. If a French locale is added, the nls folder would also contain a folder named fr containing a JSON file <bundle-name>-strings.json. Each translation file contains key/value objects and object metadata. For each object you can include descriptive metadata, including unique id identifiers for the element details and details about the object’s context that can be useful for translators.

Understand Translation Keys for Display Texts

To translate your application into other languages, you need to create translation bundles that store keys and values for the texts in your application’s UI.

When you save a string using the Translatable String popup in the Property Inspector, the value for the string is externalized to the translation bundle, and the value of the string is bound to the key in the translation file in that bundle. If you open the page in the Code view you can see the name of the translation bundle and the key bound to the string value. For example, an input label in the Code view code might be similar to <oj-input-text label-hint="Name" id="oj-input-text--452490439-1" value="{{ $page.variables.authors.name }}"></oj-input-text>.

When you externalize the string, the value of the string is replaced with a string similar to the following that binds it to a key in the translation file:

[[ $application.translations.app.input_text_label_hint_daea ]]

The expression identifies the scope and name of the translation bundle, and the translation key, using the following syntax: <scope>.translations.<bundle-name>.<key>.

You can also include parameters in the expression by using the syntax <scope>.translations.format('<bundle>', '<key>', {params}). For example, if you use the expression [[ $application.translations.format('app', 'bind_text_value_372d', { region: $page.variables.Country.region }) ]] in the UI component, the key-value pair defined in the bundle might be "bind_text_value_372d": "(This country is in {region})". In this case, the string “This country is in “ would be translated, and region would be the value of the page variable.

When you open the translation file in the editor, the file contains a key and value pair similar to the following:

"input_text_label_hint_daea": "Name",
    "@input_text_label_hint_daea": {
        "description": ""
    }

By default, each key-value pair in the translation file contains a description field as part of the metadata for the pair that can be used to provide a description of the value, for example, to provide additional context for the string that can be useful when translating the string. You can modify the file in the editor to add description metadata and other metadata for each key-value pair.

Tip:

You can use the Code view to locate strings in a page that have not been externalized for translation and add the string to the translation bundle. You can use the Audits window to locate all the strings in the application that have not been externalized.
Description of page-designer-code-translate.png follows
Description of the illustration page-designer-code-translate.png
Generate Translation Keys for Display Texts

For static strings in the UI of your application, you can use the Property Inspector to add keys and values for the strings to a bundle for translation.

You can use the Property Inspector to generate and add keys for UI components to a translation bundle. When you use the Property Inspector to define the translatable string, a key is generated automatically, but you can specify your own key in the dialog box. You can also edit the keys, values and metadata in translation files directly using a text editor.

To generate a key for a string using the Property Inspector:

  1. Select the component on the canvas that you want to be translatable.
    You can select components that use a static string in their text fields, for example, a Button component. You cannot create translations for elements where the display label or text is the result of an expression or variable.
  2. Click the globe icon for the text field to open the Translatable String popup.
  3. Confirm or edit the string to be translated. Click Save.

    The Translatable String popup contains a Text field for the string to be translated. The popup also contains a Description field that you can use to provide a description of the context for the string. The description text is included as metadata in the translation bundle.

Download Bundles for Translation

You can download translation files to your local system from the Translations tab in the Settings editor when you want to translate the application’s strings with your preferred translation tool or service.

When you download the translation bundles of your visual application, the archive that you download contains the translation files for all of the applications in your visual application. The archive contains a folder for each translation bundle in your application, and each folder contains a file in the .arb format with the strings to be translated. The file also contains metadata defining the bundle name and path that is used when uploading the file after the strings have been translated. The metadata in the file might be similar to the following:

  "@@x-bundleName" : "app",
  "@@x-bundlePath" : "webApps/mycontacts/resources/strings/app/nls/app-strings",

When downloading the bundle, you can choose to download an archive containing all strings that are stored in the translation bundle or an archive containing only those strings in the translation bundle that were added or updated since the last time you downloaded the translation bundle. The first time that you download the translation bundle you can only choose to download an archive containing all strings.

To download a translation resource bundle:

  1. In the visual application workspace toolbar, click the Options menu.
  2. Click Settings.
  3. Open the Translations tab in the Settings editor.
  4. Click the link for the archive that you want to download to your local system.

Use Translation Strings in JavaScript Files

You can use translation strings in JavaScript files and retrieve the translated text from the bundle when the function is called.

When you use a text string in a JavaScript function, the text string can be externalized to a translation bundle. You can replace the code that produces or uses the untranslated string with code that uses the translations object to retrieve the translated string from the bundle. When you edit the JavaScript function you will need to either hard code the translation key in the code or pass the key into the function as a parameter. To use the translations object in the function, you need to pass the object into the function as a function parameter.

For example, you might have a UI component in your page that displays a text string that comes from a JavaScript function that is called by a callModuleFunction action in an action chain. In the action chain, you can pass the translations object (for example, $application.translations) to the function and then assign the result to a variable bound to the UI component that displays the string.

To display a translated string used in a JavaScript function:

  1. Create a key for the string that you want translated and add the key and string to the translation bundle.

    You can use the Make String Translatable button in the Property Inspector to create the key in the bundle and generate the expression for the key. Alternatively, you can edit the translation file in the editor to create the key in the bundle and enter the expression for the translation string in the UI component’s Text field in the Property Inspector.

  2. Copy the expression containing the bundle name and key. The expression is displayed in the Text field of the component after the string is externalized.

    The expression might look similar to [[ $application.translations.app.h1__text_041a ]]. In this example, app specifies the bundle name, and h1__text_041a is the key. The bundle and key are used to evaluate the translated string. $application.translations specifies that the application-scoped translations object is used. The translations object might also be $flow or $page scoped, depending on where the bundle is located.

  3. Modify the JavaScript function so that the translations object $application.translations can be passed to the function from the action chain.

    In the following example, the action for calling the function will use translations to pass the object to the function.

      PageModule.prototype.getMessageFromBundle = function(translations) {
        ...
      };
  4. Edit the function to replace the untranslated text that should be displayed in the component with code that retrieves the translated text using the translations object. When the object is available in the function, the bundle name and key are used to retrieve the translated string from the bundle. 

    For example, the function can return a simple translated string:

      PageModule.prototype.getMessageFromBundle = function(translations) {
        ...
        return translations.app.h1__text_041a;
      };

    You can also include parameters to generate a formatted message: translations.format('app', 'h1__text_041a', param1, param2)

  5. Create an action chain that calls the function (callModuleFunctionAction) and assigns the result (assignVariablesAction) to a variable (in this example, Value).

    In this example you can see that the translations object is a parameter of the callModuleFunction action that is passed to the function, and that assignVariables assigns the result of callModuleFunction to the page variable Value.

          "root": "callModuleFunction1",
          "actions": {
            "callModuleFunction1": {
              "module": "vb/action/builtin/callModuleFunctionAction",
              "parameters": {
                "module": "{{$page.functions}}",
                "functionName": "getMessageFromBundle",
                "params": [
                  "{{ $application.translations }}"
                ]
              },
              "outcomes": {
                "success": "assignVariables1"
              }
            },
            "assignVariables1": {
              "module": "vb/action/builtin/assignVariablesAction",
              "parameters": {
                "$page.variables.Value": {
                  "source": "{{ $chain.results.callModuleFunction1 }}"
                }
              }
            }
          }
  6. Edit the Text field of the UI component to replace the generated expression with the page variable storing the result of the method. (Value).


    Description of page-designer-translations-labelexample.png follows
    Description of the illustration page-designer-translations-labelexample.png

    Tip:

    Use the Text field’s Select Variable menu to select the correct page variable

Upload Translated Files

You can upload the resource files containing translated strings in the Translations tab in the Settings editor.

To upload translated file you need to create a ZIP archive containing the ARB files with the translated strings. Before you create the archive, however, you need to modify the file names of the ARB files to append the locale abbreviation to identify the correct locale. For example, to upload an ARB file that contains translations for the French locale, you will modify the file name to <bundle—name>-strings-fr.arb.

To upload an archive with translation files:

  1. Open your web or mobile application and choose Settings in the application’s Options menu in the toolbar.

    Description of toolbar-settings-menu.png follows
    Description of the illustration toolbar-settings-menu.png

    Alternatively, on the VB Studio home page, locate the application and choose Settings in the application’s Options menu.

  2. Open the Translations tab in the visual application's Settings editor.
  3. Locate the archive containing the translated files on your local system and drag it into the upload area in the Translations tab. Click Close.
If you added a file with translations for a new locale, a folder for the new locale is created in the bundle. The new locale is also automatically added to the file defining the locales in the bundle.

Create Translation Bundles

You can use the Translation tab in the Settings editor to create additional translation bundles for application artifacts, flows and pages.

By default, each web or mobile app contains a translation bundle app in the app’s top-level resources folder. You can create additional translation bundles for the app in the app artifact’s Settings editor. You can also create bundles for individual flows and pages in the Settings editor for the flow or page when you want the translations to be flow-scoped or page-scoped.

When you create a new bundle in the Translations tab of the Settings editor, the metadata for the new bundle is automatically added to the JSON file of the app, flow or page. For example, if you create a translation bundle for a page in the page’s Settings editor, a resources folder containing the new bundle is created at the page level and the page’s JSON file is updated with the metadata for the bundle.


Description of translations-bundle-page.png follows
Description of the illustration translations-bundle-page.png

When you externalize a text for translation, the string and key are added to the nearest available bundle by default. For example, if you create a translation bundle for a page, the strings and keys are added to the page’s bundle when you externalize strings in the page. Strings in other pages are not added to that bundle when they are externalized.

To create a translation bundle:

  1. Open the Translations tab in the Settings editor of an application, flow or page artifact.

    The Translation Bundles tab displays a list of the bundles scoped for the selected artifact and the path to the bundle.


    Description of settings-editor-translations.png follows
    Description of the illustration settings-editor-translations.png
  2. Click +Bundle to open the New Translation Bundle dialog box.
  3. Supply the bundle name in the dialog box. Click Create.
When you click Create, the new translation bundle containing the translation files and folders is created in the strings folder in the resources folder of the artifact. The strings and resources folders are created if they do not exist for the artifact. The path to the new bundle is displayed in the Translations tab. The path is relative to the artifact’s JSON file.