How VBCS Really Works

If you examine what Visual Builder Cloud Service builds for you when you run the Quick Starts, you will see that the Quick Starts are just a convenient way for you to build the basics of your application quickly. When you need something more than the default, you can either adapt the logic built by the Quick Starts or create new logic from scratch.

A VBCS application consists of three elements: UI components, action chains, and variables. UI components can raise events that trigger action chains. Action chains can read and write variables, calling REST web services as necessary. The variables store the values and are used by the UI components to present the data and user interface to the end user. This circle is illustrated in Figure 7-1.

This chapter provides an overview of this process. For more details, refer to the long “Understand the Page Model” chapter of the Developing Applications with Oracle Visual Builder manual.

Examples from the Quick Starts

To see how these parts work together, you can build a simple application based on a business object. If you drop a collection component on the main-start page and then use Quick Starts to map that component to data and create an edit page, you have examples of much of the logic that a VBCS application uses.

Getting Data

When you have run the Add Data Quick Start on the main-start page, you can look at the Variables tab on that page. You will see a variable for holding the ID of the selected record and a variable of type xxxListSDP. The Types tab shows the definition of the type – we’ll discuss variable types in more detail later in this chapter. See Figure 7-2.

The variables are automatically populated by VBCS. If you want to see how this happens, and possibly override the default functionality, you can click the Customize Fetch Action Chain button at the bottom of the properties for the variable. Figure 7-3 shows the Customize Fetch Action dialog which tells you that you are overriding default functionality and will have to take responsibility for keeping the action chain and the variable in sync.

When you click Customize in this dialog, you will be shown the action chain the Quick Start has created to handle the call to the REST endpoint to retrieve the data. See Figure 7-4.

This action chain is automatically triggered when you load the main-start page. You can click the Call REST Endpoint action and investigate its properties. There is an Endpoint property pointing to the specific REST service to call as well as some parameter mappings that define how to call the service and how to map the result back to VBCS variables.

Editing Data

When you have run the Add Edit Page Quick Start on the main-start page, you will find that the main-start page has acquired a new button to edit a record. If you select this button in Design mode and examine the Events tab in the Property Inspector, you will find an ojAction event mapped to an action chain called navigateToEditXxxChain. See Figure 7-5.

From here, you can click Select next to Event to see what the possible events are and Select next to Action Chain to see the available action chains. From the Select Action Chain dialog, you can even create a new action chain. You can also click the action chain name itself (navigateToEditXxxChain) to open the automatically created navigation action chain. This action chain is more straightforward than the one to fetch data and merely include the necessary navigation step.

If you open the main-edit-xxx page created by the Quick Start, you will see that it has its own action chains to load data (loadXxxChain), save data (saveXxxChain), and go back (goBackChain).

UI Components

Now that we’ve seen some example of how VBCS default functionality is implemented, let’s look at the different moving parts in detail. We’ll start with the UI components.

When you have a UI component selected in the Page Designer, you can see and edit the events associated with the component on the Events tab in the Property Inspector.

To add a new event, you click the + New Event button. You are presented with a choice between a relevant Quick Start event and a New Custom Event. See Figure 7-6.

The Quick Start depends on the component you selected. For example, when adding an event to a Button component, the Quick Start will suggest an ojAction event (triggered by clicking the button). An input field will offer a value event (triggered when the value in the field is changed), and other components will offer other Quick Starts.

If you select New Custom Event, you will be presented with a dialog where you can select the event as shown in Figure 7-7.

The Suggested heading will show the most commonly used event for that component, but the General Events heading allows you to react to double-click, mouse enter/leave, and much more. If you scroll down, there are more headings with more events you can react to.

The Quick Start automatically creates, connects, and opens a new action chain as described in the section on action chains later in this chapter. If you create a custom event, you will be prompted to select an existing action chain, or you can create a new one.

Once you have created events, you can access them either from the Property Inspector for the specific component or from the Events tab of the page.

Lifecycle Events

Some events are not tied to a specific component but are automatically triggered as the user works with the application. These are called lifecycle events and belong to pages or flows.

Associating an action chain with one of these events allows you to intercept and augment the default VBCS page and flow processing.

You add a lifecycle event to a flow or a page on the Events tab. This tab shows all the lifecycle and component events for the page or flow, and you can add a new lifecycle event by clicking the + Event Listener button.

Variables and Types

Like other applications, a Visual Builder Cloud Service application holds its data in variables. These can either be simple variables or larger data structures that VBCS calls types. Data retrieved from REST services are stored in variables, and the value of the variables is displayed to the user. When the user enters or changes data, this change is made to the variable and then made persistent by calling the underlying REST service.

You access variables from the Variables tab. When you have the entire application selected in the navigator, you can see and work with application scope variables. When you have a flow selected or are on the tab showing the flow, the Variables tab show flow variables. Similarly, when you select a page in the navigator or have the tab for the page selected, you see page variables. Action scope variables are only accessible from the tab showing the relevant action chain.

When you have a specific variable selected, the Property Inspector allows you to set various properties, for example, the default value.

Variable Types

At the top of the Variables tab, you can see both a Variables and a Types sub-tab as shown in Figure 7-8.

You can create new types by clicking the + Type button and selecting either a Custom type or a type based on a REST service by selecting From Endpoint. If you create a type from an endpoint, the Create Type From Endpoint dialog in Figure 7-9 is shown.

Here you select the specific REST service you want to use as the basis for your type. You can point to one of the services to get more details about what that service does. When you click Next, you are given the option to select which attributes from the endpoint you want to include in your type.

Using the Quick Starts normally saves you from having to worry about variables and types, but you do need to work with the types if you afterward decide you need another attribute from the REST endpoint. To edit an existing type created from a REST endpoint, you click the Edit From Endpoint link next to the type. If you refer back to Figure 7-8, you find this link next to the getAllTask1Response heading.

The Edit Type From Endpoint dialog looks like the step in the Quick Start where you select attributes. You have the option to check the checkbox for additional attributes, adding them to the type. The action chains use the type, so the logic to retrieve and store values does not need to be changed if you add additional attributes.

Action Chains

Action chains are visual representations of the UI logic in your application. They are mapped to events triggered by something in the user interface, whether a button click or the loading of a page. Similar to variables, action chains also have a scope. Usually, your action chains will be created at the page level, but if there are chains you might want to use in several places in your application, you can also create action chains at the flow level or the application level.

The Action tab for an object (application, flow, or page) shows a list of all action chains at that level. You can click + Action Chain to create a new action chain. After you have provided a name, the Action Chain editor appears as shown in Figure 7-10.

In this editor, you can drag and drop elements from the action palette to the left onto the visual representation of the flow. If you drop it on a line or a plus sign at the end of a line, the action is added to the flow at that point.

The actions in the General category all have two possible outcomes success and failure. If you drag a new action on the plus sign below a general action, that action goes on the success branch, that is, it will happen if the general action was successful. This is the default and is not indicated in the diagram. Note, however, that when you start dragging an action, a plus sign appears at the lower right corner of the general actions already in the diagram. If you drop the new action onto that plus sign, it will be added to a new failure branch. Figure 7-11 shows both failure and success branches and shows the plus signs being shown while dragging an action.

Different actions have different properties you can set. If you refer back to Figure 7-4, you see a Call REST Endpoint action step selected. The Property Inspector shows some properties to select the endpoint to call and various assignment of parameters. If you click the Assign hyperlink next to a parameter property, the visual assignment editor shown in Figure 7-12 appears.

Here you can drag and drop to connect value sources on the left with targets on the right.

Adding JavaScript

The visual action chain builder can handle many simple requirements, but for more complicated requirements, you are likely to have to write your own JavaScript functions.

In the editor, it looks as shown in Figure 7-13.

If you want to refer to your variables in your JavaScript, you can refer to them by scope and name. For example, to refer to a page scope variable, you use $page.myVar. Similarly, you can use $application and $chain to refer to application level and action chain level variables. The shortcut $variables refers to variables in the current scope, that is, in a page-level module, $variables is the same as $page.

To use your module in an action chain, you drop a Call Module Function action onto your flow. You use the Select link to select your function and the Assign link to assign variables as shown in Figure 7-14.

The return value from your function can be mapped in a subsequent Assign action. The result of your module call will appear in the source section to the left under the Id of the Call Module Function action as shown in Figure 7-15.

Conclusion

In this chapter, you learned about the way Visual Builder Cloud Service implements the functionality that magically appears in your application when you use the Quick Starts. You also saw how UI components, action chains, and variables work together to allow you to implement complex UI logic, and how to add your own JavaScript logic when the visual action chain builder doesn’t offer you enough functionality.

In the next chapter, you will see how to use the Visual Builder for Excel plugin, which is another way for your users to interact with data in your VBCS application.