Build Redwood Design System Interfaces with Visual Builder
Introduction
A change request was created by the business to streamline the end of the quarter update made by the Sales Managers.
Currently, the application displays too many fields, which make it difficult to zero in on the data to make needed updates.
As a developer you have been asked to extend the Oracle Fusion Cloud Applications and simplify the data entry to accelerate the process for the Sales Managers. To adhere to the corporate standards (in terms of look and feel), you will use the Oracle's Redwood User Experience.
About Oracle Visual Builder Studio
Oracle Visual Builder (VB) Studio is included as one of the configuration tools that come with Oracle Fusion Cloud Apps. We will use VB Studio to create and manage a project where we will develop extensions.
Lab Objectives
Upon completion of this Lab you will be able to:
- Use Oracle Visual Builder Studio
- Create extensions for Oracle Fusion Cloud Applications
- Leverage Oracle Redwood templates and components
- Interact with data in Oracle SaaS
Click the next button below to begin.
Task 1: Create a New Extension
Starting in Oracle Fusion Cloud Applications, we will navigate to Visual Builder Studio and create a new workspace where we can begin to develop our SaaS extension.
Start by signing to the Fusion Cloud Application.
On the Oracle Linux desktop, open the html page for the sign in information and the credentials.
Click the tab Demo Cloud.
Note the credentials (username and password), you will need them later.
Scroll down until you see Fusion Launchpad. Click the ERP and SCM Cloud Login link.
Use the credentials provided to login.
Successfully login to the Fusion Cloud Application.
Start the Visual Builder Studio.
You may need to sign in again. Click the link for Oracle Application Sign In.
Go to the hamburger menu at the top left corner, then find Configuration --> Visual Builder.
Visual Builder Studio started.
Click + Create to create a project.
Enter a project name then click Next.
Keep Empty Project as the selected template and click Next, then hit Finish.
Your project is being created. It might take a few minutes.
When ready you will be taken to the project home page.
Click Create Environment.
Enter "development" as the Environment Name.
On the Environments page, click the Add Instance button to add a new server instance to our environment.
On the left side, filter the Instance Type for Oracle Cloud Applications. This should pull up the Fusion Cloud App instance in your tenancy.
Once it is located, check the checkbox next to it, then press the Add button to add this instance to your environment.
You will be redirected back to the project's home page. Wait for the green check mark. You are now ready to create a new app extension on this instance.
Click Workspaces in the left navigation menu to create a New Application Extension.
Click New, then select New Application Extension to create a workspace for your extension.
In the New Application Extension dialog, populate the fields with these values:
Field Value Explanation Extension Name YourName-Accounts To keep the names distinct, use your first name plus the first initial of your last name, as in MaryC-Accounts Development Environment Choose the option available Mapped to your SaaS instance Base Oracle Cloud Application None Not needed in this scenario Sandbox No sandbox selected Not needed in this scenario Git repository Use scratch repository For now, you can just work in a private Git repository Your screen should look like this:
When ready click Create.
It may take a couple of minutes to create the workspace. When VB Studio is finished, you will be taken into the Designer.
Congratulations on completing this task!
You can begin to create your application (webpage).
Click Next to continue.
Task 2: Create Your First Page
You should now be in the Designer, VB Studio's visual editor. We will start by creating an App UI, which is simply an application that includes a user interface within Visual Builder pages and flows.
With App UIs, you can create new interfaces that address specific business needs for your company.
On the left side of the Designer, click + App UI.
Provide a name in the format [YourName]-Accounts.
Click Create when ready.
In the Diagram view on the right, you can see the flows and pages for this App UI.
A flow contains pages that relate to each other. An application can contain multiple flows, and a flow can contain many pages.
In this case we have one flow, main; and one page, main-start.
Double-click main-start to open the page in the Page Designer.
Before we get started, let's explore the Designer UI a bit.
There are lots of tabs you can click to expand/collapse different areas and give yourself more room to work.
Here are the key areas of the Designer you will use throughout this workshop.
# Tab Functionality 1 Components UI components you can add to a page, sorted into categories 2 Data Data objects you can work with, based on connections you create to SaaS objects 3 Structure Hierarchical view of the page's structure 4 Properties Declarative area to define properties for the component selected in your page 5 Canvas Displays a design/live view (or code view) of your page content Note
You can collapse and expand tabs to better manage your working area. When collapsed the tab will show as a vertical tab on the side of the editor. To expand/collapse a tab click that specific tab.
In the header area (the black bar along the top), you will find the Undo and Redo buttons. If you make a mistake, click Undo to back out of the last step you did.
The Components Palette contains over a hundred UI components that you can drag and drop onto your pages to design your interfaces.
In this workshop, we are going to use page templates designed by Oracle's Redwood Design team to accelerate the development.
These templates provide a responsive user experience, which means your app will adjust to the device accessing it.
Use the search term "welcome", then expand to Search Exchange to locate Welcome Page Template.
If not installed, click Install on the search result. In the popup, accept the license agreement, then click Install to confirm.
Drag the template from the Component palette and drop it on the canvas.
Let's set some properties for the template to customize it a bit.
Click the All tab in the Properties pane and modify these properties:
# Property Value 1 Background Color Choose your preferred color 2 Description Search and edit accounts 3 Page Title Accounts For the Illustration foreground source URL enter the following:
https://static.oracle.com/cdn/fnd/gallery/2107.1.0/images/illust-welcome-banner-fg-03.pngYour screen should look like this:
Next we will add a search component and define a variable to keep track of the search terms.
In the Components Palette, enter the search term "search", then locate the component Input Search.
Drag this component and drop it on the page in the canvas and choose Search slot.
This field is where users will enter a search term to locate an account. We need to keep track of these terms, so we will use a page variable to do that.
Select the Input Search in the canvas and click the Data tab in the Properties pane.
Click the little arrow at the top right of the Value field to display a list of current variables. (You might need to hover your mouse over the field for it to pop up.) Now, we need to create a new variable.
Next to the Page category, click Create Variable to create a page-level variable.
Notice that there are multiple scopes for variables, which helps to share their values across pages and flows in the application.
In Create Variable --> ID, enter "searchString", leave Type as String. Click Create when done.
The Value field in the Properties pane now contains a reference to our new variable.
Add a Collection Container.
In the Components palette, enter the search term "collection", then locate the component Collection Container.
To explore a different way to add components to your page, drag the component to the Structure pane and drop it on Welcome Page Template.
Then select Default slot.
The layout of our first page is now ready. Our next step is to add some data to the page from Oracle Fusion Cloud Apps.
At this point your screen should look like this:
Except for the background color, which should reflect the choice you made earlier in the template.
Congratulations on completing this task!
Next, we will retrieve data from Oracle SaaS.
Click Next to continue.
Task 3: Connect to Oracle Fusion Cloud Apps
This lab you will create a connection to data that resides in Oracle Fusion Cloud Applications.
It will show you how to use the service catalog in VB Studio to browse the available REST services, pick one, then display data from it on our page.
About Oracle Fusion Cloud Apps REST APIs
Oracle Fusion Cloud Apps provides REST-based access to its data.
VB Studio is built to use those endpoints by leveraging single sign-on, a service catalog, and knowledge of the services' advanced functionality, such as filtering and pagination.
Let's begin by browsing the Service Catalog.
Up until now we've worked on the UI (front end) of your application, but now it's time to work with the data, the backend. VB Studio's built-in service catalog automatically connects to your Oracle Fusion Cloud Apps catalog of services, which makes it easy to create a connection to those Apps.
On the far left side of the Designer's navigator, click the third tab, Services.
Click + Service Connection.
About Service Connections
There are three options for defining the source of your REST service connection:- Select from Catalog: choose from the service catalog of Oracle SaaS REST Services.
- Define by Specification: based on their OpenAPI/Swagger description. This can be useful when working with custom objects you created with the Application Composer in Oracle SaaS.
- Define by Endpoint: point to the url of an endpoint. This option allows you connect to any REST service available over the internet, which can be useful for integrating with third-party apps.
Click Select from Catalog --> Sales and Service.
From the list of objects, using the search filter at the top, choose accounts (Accounts).
Click Create. This creates a connection to the data object and adds it to your app.
A tab with information about the service is displayed.
We will keep all the default definitions here, so you can close this tab and return to the tab displaying the main-start page.
In this section we will add data to your page.
In the Designer, click the Data tab on the left and expand the Services node until you can see the accounts service. (If you don't see any services, click the Refresh icon next to the Filter box at the top of the pane.)
Drag the accounts service to the Structure pane and drop it on Collection Container.
In the Render as pop-up, choose the second Table option (not Table Dynamic):
VB Studio can display data in many different formats, including some that let your users modify data. In this case, we just want to display data in a table.
Choose the first getMany endpoint on the list/accounts.
A dialog displays all the fields that are available for the accounts business object — quite a long list!
Using the filter field at the top, locate each of these fields and click each field name to add it as a column in our table. Leave all as type Text. Click Next when you are done.
# Fields 1 OrganizationName 2 CEOName 3 CurrentFiscalYearPotentialRevenueAmount 4 NextFiscalYearPotentialRevenueAmount Fields are added.
In the app we want to be able to filter the list of accounts by defining a filterCriterion for the REST endpoint.
On the right, under Target, click FilterCriterion. This displays the filter builder at the bottom of the dialog.
Click the Click to add condition link.
In the Attribute field, start typing "OrganizationName" until you can it listed in the drop down list, then select it
Leave the operator as contains ($co).
In the next field, enter "searchString" and choose $variable.searchString from the drop down list.
When ready, click done.
The filter we just built essentially does this... If the organization name contains the user's search string (that is, the variable name), then filter the data in the table to show that row.
Click Finish to close the dialog.
Now a table with the selected fields has been added to your page. The data for this table will be fetched from Oracle SaaS using the service connection we defined earlier.
To use the service's pagination capabilities (as opposed to fetching all the records available on start-up), let's add a scroll policy to the table.
While we can do this by setting the property directly in the property inspector, for the purpose of learning, we will modify your application at the code level instead.
Switch to Code view by clicking Code button at the top of the preview.
Locate the line that starts with "<oj-table", which is the definition for the table.
There's already a scroll policy here, but we are going to add another one.
Position your cursor in the space right after "<oj table" and type "sc".
Notice how VB Studio's code completion feature lists the available properties.
Choose scroll-policy-options.scroller and set the attribute to "html":
The code for this line should now look similar to this:
<oj-table scroll-policy-options.scroller="html" scroll-policy="loadMoreOnScroll" ...>If you want to use the property inspector instead, go to the property inspector for the table, locate the scroll policy options property and drill down to the sub properties by clicking the right arrow. Then set the scroller to html.
Click Design so we can see our table populated with data.
Take a closer look at the app by using the Preview feature.
In the Designer's header, click Preview in the top right. This opens a new tab in your browser where you can see your running app, complete with our new table.
You can play around with your app, using different keywords to filter the list by organization name. Also, notice the smart pagination that occurs when you scroll through the records in the table, records are fetched only as needed.
Congratulations on completing this task!
Now that we have a running page that fetches data, the next step is to add pages that will allow us to edit the data, which means updating the Oracle's SaaS business object behind the scenes.
Click Next to continue.
Task 4: Add Edit and Details Pages
VB Studio Quick Starts are guided dialogs that help you create user interfaces in a step-by-step fashion, pages that update, insert, delete, and view data.
In this task you will use the Quick Starts feature to create additional pages for your app.
We start by creating an edit page.
In Design view, select the table in either the Structure pane or on the canvas.
When the table is selected, in the Properties pane, click the Quick Start tab.
As you can see, there are different types of Quick Starts to help us create pages with different functions.
Click Add Edit Page.
In the Add Edit Page dialog the accounts object is already selected, click Next.
Next, select the object that will be updated. As the accounts is already selected, click Next.
Next, choose the specific fields we want to present on the Edit Page.
There are four columns in our table, so let's use the filter field at the top to help us find those fields.
Filter on name, then revenue, and select the following fields
# Fields 1 OrganizationName 2 CEOName 3 CurrentFiscalYearPotentialRevenueAmount 4 NextFiscalYearPotentialRevenueAmount The four fields have been selected.
Click Finish to complete the Quick Start.
We are back on the Accounts search page in the Designer. Notice that there's now an Edit accounts button at the top of the page. We will come back to this later.
Lets create the page to display (and edit) more details about each account.
In Design view, select the table in either the Structure pane or on the canvas.
In the Properties pane, click the Quick Start tab --> Add Detail Page.
The Add Detail Page allow you to edit the details of a row selected from the table.
Identifies the object from which users will pick a specific record.
As the accounts object is already selected, click Next.
On the Page Details screen, use the filter field to search for and select the following fields:
# Fields 1 OrganizationName 2 CEOName 3 OwnerName 4 AddressLine1 5 AddressLine2 6 AddressLine3 7 AddressLine4 8 City 9 County 10 Country The fields are selected.
Click Finish to complete the Quick Start and create the page.
Preview the app. Click Preview in the header.
When the page loads, experiment with searching for a specific record, selecting that record, then clicking the Edit accounts button.
Try updating some fields, such as the CEO Name or adding a Revenue value, then click Save.
You'll see a pop-up confirming that this data has been submitted to Oracle Fusion Cloud Apps. It will be reflected in your table, too:
Click another record, then click the "account Details" button to find out the address of the account:
Use the browser's back button to return to the search page.
Congratulations on completing this task!
The application is functioning quite well now.
In the next step we will improve the usability by adding buttons to the table rows.
Click Next to continue.
Task 5: Add Buttons and Action Chains
Add Empty Columns to the Table
While the Quick Starts added buttons for editing and displaying details, it might be nicer to have buttons in each row of the table for those functions, so you don't have to select the row first.
Lets add these features to each row.
First, add two columns to the table, to hold each of the buttons.
In Design view, select the table in either the Structure pane or the canvas:
In the Properties pane, click the Data tab, then click the Edit Columns icon next to the Table Columns heading.
Click New Empty Column twice to add two empty columns to your table, then click anywhere outside the pop-up to dismiss it.
The new columns are represented by the vertical lines, under the word Revenue.
Select the first column and click the arrow to see the details.
In the Columns, Header Text field, enter "Edit", then click the Table Columns back arrow to go back to the Data tab.
Repeat for the second column, enter "Info", then click the Table Columns back arrow to go back to the Data tab.
You have now added two columns to our table, which you can see in the canvas area.
We will add an icon button that looks like a pencil (for Edit) and an exclamation point (for Details).
Then wire up these buttons to some actions so that they will do something when the user clicks them.
In Design view, click Components and enter a search term "button".
Drag the Button component and drop it into the Edit column.
The editor highlights the location you can drop the button into; make sure you drop it into the middle of the column.
Drag another Button component into the Info column.
Back in the Components Palette, locate the Icon component.
Drag the Icon component and drop it on to the first Edit button. When prompted, choose startIcon as the slot for the icon.
Select an image for the Edit icon.
In the Properties pane, click the image under Icon.
Search for Edit, select the icon Edit and click Select.
For the info icon, drag the Icon component onto the second button in Structure view.
Use the Properties palette to select the Information icon.
In the canvas area, click any Edit button, then use the Properties pane to set these properties.
Property Value Display Icons Chroming Borderless Your screen should look like this.
Repeat for the Information button.
You now have a nice looking icon-based buttons for each row, but so far they don't do anything.
In order to make the icons do something when clicked, we need to define the Action Chains.
VB Studio apps are event-driven, which means that an event is fired when an end user performs an operation in the user interface. You can create an action chain that kicks off a series of actions in response to an event.
In Design view, select the Edit button, then click Events in the Properties pane.
Click + New Event --> On ojAction.
If you see an onClick event instead, it means you selected the icon instead of the button. Make sure the button itself is highlighted.
You're now in the Action Chain Editor.
On the left side, you can see all the actions you can define, including calling REST endpoints, invoking JavaScript functions, and many more.
The Quick Starts we used to create the Edit and Details pages already created action chains for us.
All you need to do is call those action chains from the new action chain you are defining.
Drag Call Action Chain and drop it onto the + sign.
In the Properties pane, click the arrow in the Action Chain ID field and select navigateToEditAccountsChain from the drop-down list.
We have set things up so that when the Edit button is clicked, we will navigate to the Edit page created for us by the Quick Start.
However, as we can see from the Properties pane, this action chain expects a value for the input parameter accountsId.
Click the Not Mapped label.
Under Sources, look under Action Chain --> Variables for the variable key. Drag and drop it onto the accountsid parameter in the Target area on the right. When done, click Save.
Click Page Designer to go back to the visual view of the main-start page.
Repeat the same steps for the Info button.
- Creating your On ojAction action chain, use the Call Action Chain action.
- Select navigateToAccountsDetailChain in the Action Chain ID field.
- Map the key variable to the accountsId input parameter.
Take another look at the app to see the changes in action.
Click Preview in the header, then open the new browser tab.
You can now click the Edit and Info icons in a row to open the Edit and Detail pages for the organization selected. Pretty cool!
We don't need the buttons at the top of the page anymore, so let's remove them.
Back in the Page Designer, go to the Structure pane. Under Toolbar, right-click each button and click Delete to remove it from the page.
Congratulations on completing this task!
Your table now has buttons that are attractively rendered and that work as expected.
The next task is to fine-tune the look and feel by applying some Redwood templates to them.
Click Next to continue.
Task 6: Apply Redwood page templates
In this task you will apply the Redwood template to the edit page.
The Live mode allows you to interact with your app as if it were actually running.
In Design view, click the Live button.
Click the edit icon for one of the rows.
The Edit page opens, with data for the account you selected displayed.
Switch to Design mode so you can edit the page.
In the Components Palette, enter the search term "edit", then locate the component Simple Create and Edit Template.
Drag it to the top of the page hierarchy in the Structure pane, and drop it when you see a blue line above the first Grid Row.
In the Properties pane, enter the following details.
Property Value Page Title Edit Account Page Subtitle Add missing information Display Mode for the Header Mixed Primary action label Save Your screen should look like this.
Now that the template is set, we can move the page objects in to it.
In the Structure pane, locate the Grid Row that corresponds to the Form Layout.
Drag the Grid Row and drop it onto the Simple Create and Edit Page Template.
The page content should be back in place.
The template we applied already supplies a heading and toolbar, so we can remove the grid rows for those elements in the Structure pane.
Select the Heading Grid Row, right-click, then click Delete.
Do the same thing for the Toolbar Grid Row:
Your page should now look something like this:
Now, we will hook up the template's actions.
The Simple Create and Edit Page Template has a primary action built in, Save, but we need to make it functional.
Select in the Structure pane --> Simple Create and Edit Page Template.
In the Properties pane --> Events tab --> + New Event --> spPrimaryAction.
spPrimaryAction will map the built-in action to the main button on the page.
In the Action Chain editor, click + icon --> General --> Call Action Chain.
In the Properties pane, click Action Chain ID --> saveAccountsChain.
saveAccountsChain action chain was created by the Quick Start.
Add an action to handle the cancel button.
Switch to the Designer view and in the Structure pane, select Simple Create and Edit Page Template.
In the Properties pane, click Events --> + New Event --> On spCancel.
In the Action Chain editor, click the + icon --> General --> Call Action Chain.
In the Properties pane, click Action Chain ID --> goBackChain.
goBackChain action chain was created by the Quick Start.
Click the Page Designer tab and switch to Live mode to test it.
In the Revenue field, enter a value, the click the Save button.
You should see the value you just entered reflected in the canvas area.
Apply the foldout template for the detail page. It creates a foldout effect for the page.
In the Page Designer, click the info icon for one of the rows.
You should see the Accounts Detail page.
In the Components palette, use the search term "fold", then expand to Search Exchange to locate Foldout Layout Horizontal Template Pattern.
Drag it to the top of the page hierarchy in the Structure pane, and drop it when you see the blue line above the first Grid Row.
A pattern applies more than just a new look and feel to the user interface; it can add variables and actions to your page as well.
In the Properties pane, notice that many template properties have been mapped to variables, but they may not be the values we want.
To change the values of these properties, we will need to update the variables' default values.
In the tab row containing the Page Designer tab, click the Variables tab.
Locate each of the following five variables and modify the Default Value.
Variable Default Value biDirectionalNavigation false goToParent false pageTitle Account Info panelOneTitle Company panelTwoTitle Address Here is a sample screenshot for one of the variables:
Click Page Designer to see the effect of your changes.
Now that the template is set, we can move the page objects in to it.
In the Structure pane, locate the Form Layout, then drag and drop it onto the first div in the first Foldout Panel in the Structure pane.
The first panel is displaying too much information, so lets move some of it to the next panel.
In the Components Palette, find the Form Layout component, then drag it to the second Foldout Panel and drop it onto the first div, selecting the Default slot.
In the Structure pane, find the first Form Layout (the one with ten children). Click the fourth field in the Form Layout, and shift-select it and the below fields.
Drag them into the new Form Layout you created in the second foldout panel.
Make this form look like the other form.
Select this second Form Layout in the Structure pane.
In the Properties pane, change the Label Edge property to Start.
You can delete the original "accounts Details" header that is at the bottom of the screen.
Switch back to the tab for the main-start page, click Preview to see the completed application.
Congratulations on completing this lab!
In the real world, at this point you would likely do user acceptance testing (UAT), then once it has gone through the change management process, deploy to your Oracle Fusion Cloud Applications instance (production).
Before you close your browser completely, please do tell us what you think about this lab.
Firstly, click the End Session icon on the Luna tool bar.
Then click this icon to send us your feedback. Thank you!
