X

The Visual Builder Cloud Service Blog

Adding Your Own Application Templates to Oracle Visual Builder

Duncan Mills
Architect

Last updated for Oracle Visual Builder 19.4.3

Introduction

When you create a new Visual Builder application, you have the option to select a template as shown here:

Screen shot of the create application screen in Oracle Visual Builder

When you select the Change template you will be taken to another dialog which allows you to select from one of the available templates.  For example:

Screen shot of the template selection screen in Oracle Visual Builder

The question therefore arises, can I create my own templates to add to this list?  The answer is, of course, yes!  In this article I'll take you through the steps required to do this. 

Step 1 - Prepare your Visual Builder Environment 

The templates displayed within the dialog shown above are listed from the Component Exchange (as we'll see later, templates are just a type of component).  By default your Visual Builder environment will be associated with the central read-only Component Exchange that contains the components and templates shipped by Oracle as samples or as part of particular products.  So the first step, and one that only needs to be done once, is to create a private Component Exchange for your tenancy and then associate your Visual Builder instance with that private Exchange. 

This process is covered in the Visual Builder Administration Guide which you can reach from the Help menu on the Visual Builder Application List screen. So for customers using Visual Builder in the context of Oracle Integration you will need to locate the Administering Oracle Visual Builder in Oracle Integration guide in the help and then navigate to Chapter 2 Manage Instance SettingsManage Your Component Exchange

In a Visual Builder Studio environment the same information is available in Chapter 5 of the Administering Visual Builder Studio guide

This documentation will take you through the process of creating a new private Component Exchange instance that can be used to contain your own components (as well as the Oracle supplied ones) and then setting up your Visual Builder instance(s) to use that Exchange.

When going through this process you will need to keep a note of three pieces of information:

  1. The URL of the Component Exchange project - the same one that you will configure on the Visual Builder settings that has the format of https://{hostname}/{org_id}/s/{project_id}/compcatalog/0.2.0/
  2. The username of a member of the project that you created to hold the Component Exchange
  3. The password for that user

Step 2 - Install the Required Tooling

Having set up a private Component Exchange you'll see no difference at all in the day to day operation of Visual Builder.  Your private Component Exchange will have been pre-seeded with the same initial set of components and templates that are present on the global Component Exchange. So the next step is working out how to add your own content.  Well to do this, the simplest way is to use the Oracle JET command line tooling which provides a simple command to achieve this. You will need Oracle JET tooling version 9 or above for this task.  If you don't already have JET 9 or above installed then follow these steps:

2.1 Install Node and Node Package Manager

Node and npm can be downloaded and installed for all platforms from nodejs.org. Download the LTS version for your operating system.

2.2 Install Oracle Jet Tooling 

Now that Node is installed open a command shell and install the Oracle Jet Tooling using the command:

npm install @oracle/ojet-cli

This will install the latest available version of the JET tooling on your machine.

2.3 Verify Oracle Jet Tooling Version

To make sure that you have successfully installed type the following into your command shell: 

Verify

ojet --version

This should display:

Oracle JET Command Line Interface, version: 9.0.0

(or higher)

Step 3 - Create your Candidate Visual Builder Application

Next, of course, we need to think about the content of the template.  All you need to do here is just build a new Visual Builder application with the content that you want for the template.  This can be as simple or complex as you desire.  When you are ready just export the application to a zip file ready for the next step.

Step 4 - Create and Publish the Template

The final task is to wrap the zip export of your candidate project as a component and we'll use the Oracle JET ojet tool to do this. Follow these steps: 

4.1 Create a JET project to Define the Template

From the command line, use the ojet tool to create a new project using the command:

ojet create MyTemplateProject 

Once the project has been created change to the project folder (the name of the project)

4.2 Configure the Component Exchange

We are going to publish the template from this project so we need to configure the project to point at your private Component Exchange that was created in Step 1. So, ensuring that you are in the project root, issue the following command, using the correct URL for your Component Exchange instance:

ojet configure --exchange-url=https://{hostname}/{org_id}/s/{project_id}/compcatalog/0.2.0/

When issuing this command note that there are two dashes before exchange-url and be sure to include the training slash on the URL itself. You can verify that the connection to the Component Exchange is working by issuing the following command:

ojet search exchange oj-sample-template-fusion-theme

You will be prompted for a username and password, enter the values for the user you recorded in Step 1.  When the command returns it. will  return something like:


Searching for 'oj-sample-template-fusion-theme' in the Exchange ...
<fullname>                               <displayname>  
oj-sample-template-fusion-theme          Oracle SaaS R13 Light Theme for VBCS    

4.3 Create a New Component

Next you can create a new component to hold the template. To do this issue the following command from the root of the JET project:

ojet create component <template-name>

The name you choose for the component is up to you.  However, I recommend that you use a prefix of to help namespace it in the same way that all Oracle components start with oj-. It goes without saying that you should not use the oj- prefix for any of your own components. The name of the component must include a hyphen

This command will create a new component under /src/js/jet-composites/<template-name>, so change to that folder. 

By default the create component command assumes that you are creating a new UI component and so it has scaffolded a lot of files for you as part of that process.  In fact, the only one that you need is the component.json file, and you can remove all of the other files and folders under the component directory, so that you're just left with that file. 

4.4 Copy in the Visual Builder Export ZIP

Next take the export zip file that you created in Step 3 and place it in the component folder. It can be called anything you want at this stage, but for convenience I'll refer to it as template.zip.

4.5 Edit the component.json file 

Next you need to correctly configure the template definition and this is done  in the component.json file.  Edit that file and replace the default contents as follows:

{
  "name": "<template-name>",
  "displayName": "My Custom Template",
  "description": "Your description here will show up in the template dialog",
  "type": "vbcs-template",
  "version": "1.0.0",
  "icon":{
    "iconPath": "templateIcon.png"
  },
  "extension": {
    "vbcs": {
      "vbcsVersion": "19.4.3",
      "template": {
        "sortPriority": 50,
        "archive": "template.zip"
      }
    }
  }
}

Ensure that the name attribute matches the name that you used for the component, e.g. "name":"my-template" and fill in the displayName, description and version as required. 

The archive attribute names the Visual Builder export zip file that you placed into the root of the component folder.  The icon section is optional, but if you provide the iconPath attribute as shown here (and include the named image in the root of the component folder) then that image will be used in the template dialog. 

Finally the sortPriority determines the ordering of the templates in the selection dialog. If you set this value to less than 10 then your template will become the default when creating new applications.

4.6 Publish the Component 

All that remains is to push this new template component to your private Component Exchange.  You use the ojet publish command to do this, e.g.

ojet publish component <template-name>

Again you will have to provide the username and password from Step 1. (if the token has expired since you last authenticated). 

At this point, your new custom template will be available:

Screenshot of template selection dialog showing the custom templateAt this point you might want to save the JET project into source control so that you can update the template over time. 

Step 5 - Updating the Template

As your needs evolve you may want to update the template.  To do this all you need to do is amend the source application in Visual Builder and export it back into a zip in your component project.  Then be sure to update the version number (use semantic versioning)  in the component.json and repeat the publication process. Only the latest version of the component will be displayed in the template selection screen. 

Note that updates to a template will only be effective for new applications that are created after the new version is published.  Existing applications will be untouched by a template update. 

 

 

Join the discussion

Comments ( 2 )
  • Kumar Thursday, August 13, 2020
    Dear Duncan,
    This is very nice article, I was looking for this. Thank you.
    I have a qq - Can we move the application template from one template to another template after creating the application?

    Thanks.
  • Duncan Friday, August 14, 2020
    Not quite sure as to what you are asking - but if you want to create a new template then you need to repeat the process - so you can create an app from a template - make some changes and then publish the result as a brand new template (or a new version of the original template)
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.