X

Technical Articles relating to Oracle Development Tools and Frameworks

  • April 17, 2020

Visual Builder - Migrating Sample Components to the Latest Versions

Duncan Mills
Architect

Introduction

In Oracle Visual Builder we provide a capability to add additional custom components into the page designer component palette from a shared catalog. As part of this offering we have pre-seeded the catalog with a set of example components that you are free to use (unsupported) or copy and adapt (they are provided under the Universal Permissive Licence 1.0).  When we originally released this feature we partitioned these example components into three component packs (see this blog article to learn about packs). Those packs where prefixed oj-sample, oj-sample-mobile and  oj-ext.  As time has gone by we've realised that there is really no value in managing each of these component sets separately and so we've consolidated all of the components into the base oj-sample pack. 

The older packs, (oj-ext and oj-sample-mobile) are still available in the catalog but they will no longer be updated over time and the "newer" versions of the components are present in the oj-sample pack instead.  The following are the effected components and the names of the new versions:

Deprecated Component Replacement
oj-ext-checkbox-switch oj-sample-checkbox-switch
oj-ext-export-data oj-sample-export-data
oj-ext-export-utils oj-sample-utils
oj-ext-highlight-text oj-sample-highlight-text
oj-ext-input-email oj-sample-input-email
oj-ext-input-url oj-sample-input-url
oj-ext-metric oj-sample-metric
oj-ext-utils oj-sample-utils
oj-sample-mobile-online-detector oj-sample-online-detector
oj-sample-mobile-orientation-detector oj-sample-orientation-detector
oj-sample-mobile-pull-to-refresh oj-sample-pull-to-refresh

 

Currently both the old and the new components are visible from the cataog search, depending on the version of Visual Builder the deprecated ones (oj-ext-* and oj-sample-mobile-*) may be marked with a warning triangle to show that they are no longer compatible with the version of the JET toolkit being used by your version of Visual Builder.  For example from Visual Builder 19.4.3 if I search for "checkbox" in the catalog I will see both the old deprecated oj-ext-checkbox-switch and the replacement oj-sample-checkbox-switch.

As you can see, Visual Builder is warning me that the oj-ext version may not be compatible. 

A New Application - Choosing the Component to Use 

Fairly obviously, if you want to try out one of these components, you should only use the oj-sample versions.  Once all public cloud instances of Visual Builder have migrated onto 18.4.3. or above, the deprecated components will actually be hidden in the browser so you won't be able to get this wrong.  they will still be there to allow existing applications to continue to run, but you'll not be able to accidentally add them to a new application.   For now, however, before installing the component, click on it to see the readme document for the component and make sure that it is the oj-sample version that you are installing (as per the table above).

Migrating Existing Applications 

If you have an existing application that uses any of the deprecated components you should move to the new versions at a convenient time.  The deprecated components will continue to function, however, they will not be updated any more and there is no guarantee that they will continue to work in future versions. 

If you have installed a component into the component palette, but not actually used it in your application then you will simply be able to uninstall it from the browser. Just click the "Uninstall Component" button:

However, if you have used the component then things are slightly more involved let's go through the steps.

Note I have deliberately defined this set of instructions for use by someone who is not particularly familiar with working directly with the Visual Builder metadata so as to make the process as fool-proof as possible. These instructions are based on the use of Visual Builder 19.4.3 so I would not recommend embarking on that process until you are upgraded to that version. 

Step 0 - Back up the Application

It goes without saying that you should not start with these changes unless you have a backup that you can revert if you make a mistake.

Step 1 - Identifying the Components You Need to Migrate 

The step is very simple.  Visual Builder records the catalog components that you have consumed in a single place in the file <your app>/settings/dependencies.json. So switch the navigator to source view and navigate to that file:

In this example we can see that the application "webapp" is using checkbox-switch and export-data from oj-ext and pull-to-refresh from oj-sample-mobile. 

This tells us that the list of components to replace are:

  • oj-ext-checkbox-switch
  • oj-ext-export-data
  • oj-sample-mobile-pull-to-refresh

Step 2 - Installing the Replacement oj-sample Versions

Now that we have the list of components to fix up, the next step will be to simply switch to the component catalog browser view and search for the replacement and install that. e.g.

Search on the full name and click the entry in the browse panel so that you can confirm that it is indeed the one that you want.  Install as normal.

Step 3 - Replace Usages

Next we need to just switch any usages of the old deprecated version tags to the new oj-sample ones. The components themselves are drop in replacements so this is just a search and replace operation.  In Visual Builder 19.4.3 and above the Find In Files capability makes this trivial.  So for example we can search for "<oj-ext-"

In this case We can see that just one page contains components that need to be changed.  We don't have to worry about the usage of the component name in the component IDs or <oj-label> for= attributes, just change any instances of the actual component tags (e.g. <oj-ext-checkbox-switch ...>) to the new name (<oj-sample-checkbox-switch ...>), not forgetting to do the closing tag as well (</oj-ext-checkbox-switch> -> </oj-sample-checkbox-switch>).

Once you've updated the tags in the HTML code view , they will all be underlined with red squiggles for example:

So once you have updated all of the tags on the page, hover over any one of them and choose "Add all missing dependencies for this page". The squiggles will disappear.

For the same page open the page JSON file,  in the imports > components section of the metadata you will now see entries for both the old components that you have replaced and the new ones:

"imports": {
  "components": {
    "oj-label": {
      "path": "ojs/ojlabel"
    },
    "oj-ext-checkbox-switch": {
      "path": "oj-ext/checkbox-switch/loader"
    },
    "oj-ext-export-data": {
      "path": "oj-ext/export-data/loader"
    },
    "oj-sample-mobile-pull-to-refresh": {
      "path": "oj-sample-mobile/pull-to-refresh/loader"
    },
    "oj-sample-export-data": {
      "path": "oj-sample/export-data/loader"
    },
    "oj-sample-pull-to-refresh": {
      "path": "oj-sample/pull-to-refresh/loader"
    },
    "oj-sample-checkbox-switch": {
      "path": "oj-sample/checkbox-switch/loader"
    }
  }
}

You can just delete the entries for the unused deprecated components so you might end up with just: 

"imports": {
  "components": {
    "oj-label": {
      "path": "ojs/ojlabel"
    },
    "oj-sample-checkbox-switch": {
      "path": "oj-sample/checkbox-switch/loader"
    },
    "oj-sample-export-data": {
      "path": "oj-sample/export-data/loader"
    },
    "oj-sample-pull-to-refresh": {
      "path": "oj-sample/pull-to-refresh/loader"
    }
  }
}

Step 4 - Clean up

At the moment, the component palette in the page designer will be showing both the deprecated and the new components which will be confusing, so we can now clean that up.

This will involve opening the <your app>/settings/dependencies.json file again (See Step 1). Simply remove the oj-ext and oj-sample-mobile entries from that file. e.g. in my case I'll end up with just the references to the oj-sample components: 

{
    "component-dependencies": {
        "oj-sample": {
            "version": "3.1.2",
            "components": {
                "checkbox-switch": "3.0.0",
                "export-data": "3.0.3",
                "pull-to-refresh": "4.0.2"
            }
        }

    }
}

You may have other entries in here, so be sure to delete the packs for the deprecated components only

Now switch to the Component Browser and you will be able to click on Uninstall Component button for each of the deprecated components. Once you have done this then component palette will only show the new oj-sample versions.

Finally you can tidy up the app-flow.json file as well. Open it up and search for the requirejs > paths section.  It will look something like this: 

  "requirejs": {
    "paths": {
      "oj-ext": "build/components/oj-ext/2.2.3",
      "oj-sample-mobile": "build/components/oj-sample-mobile/3.0.0",
      "oj-sample": "build/components/oj-sample/3.1.2"
    }
  }

You can just delete the entries for oj-ext and oj-sample-mobile as these are no longer needed. Leaving these paths in will not do any harm but they are now redundant so I recommend that you remove them. 

Once you have completed all of these steps then you're done and you will be able to automatically receive future upgrades as we push them out. 

 

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.