Working with Application Extensions

Applications can be extended through the use of custom resources that can be shared between applications.

About Application Extensions

Application extensions are custom resources that can be created and shared between applications in the tenant space.

An application extension is a collection of files that provide a custom function or resource that can be used to extend an application. For example, an extension can be used to provide a custom look and feel that can be applied to pages in an application, or it could provide a custom UI component that can be added to a page. Extensions can be shared between applications in the tenant space. You use the Extensions manager to import extensions from an archive or from other applications that have enabled extension sharing.


Description of extension-theme-referenced.png follows
Description of the illustration extension-theme-referenced.png

Note:

You cannot modify the sources for extensions that are shared by other applications. When you add a shared extension to your application, the Extensions manager displays the name of the application that contains the extension’s sources.

Types of Extensions

There are four types of extensions that you can add to your application.

Type Description
UI Component

UI components are extensions that can be integrated into the UI of an application by dragging the extension from the Components palette. These extensions can be data bound to business objects and fields, and can have properties that can be modified in the Property Inspector.  They can also be included in collection objects like lists and tables.

Resource

Resources are JavaScript objects that are loaded by the application at runtime. These objects will typically be used by other extensions.

Business Object Provider

Business Object Providers (BOP) are extensions that facilitate connecting to external web services, which are then exposed as business objects that can be used in your application and bound to UI components.

Theme

Themes are extensions that can provide an alternate look and feel to an application by modifying the wrapper around the page content. For example, a theme can be used to change how the navigation, header and footer elements in the page are displayed. Available themes are listed in the Themes palette in the Page Designer.

Adding Shared Extensions

The extensions framework enables an extension created in one application to be shared and reused in other application within the tenant space. Applications can import extensions from published applications that have enabled resource sharing. All the applications that use the shared extension can be updated by updating the sources of the shared extension. For example, you might want to use a shared theme in your application to provide consistency between a set of applications in your tenant space. Alternatively, if you cannot or do not want to use a shared extension you can add an extension by importing a zip containing the sources.

To add a shared extension, select Share from another application from the menu in the Extensions page.


Description of extensions-new-share.png follows
Description of the illustration extensions-new-share.png

The Import Extension From Another Application dialog box displays a list of extensions of the same type that are available in the tenant space. By default, only extensions in published applications with sharing enabled are listed in the dialog box. If you want to add extensions to your application that are still in development, you can select Show in-development in the dialog box to see extensions available in applications that are not published. You can add in-development extensions to your application, but they may still change, and your published application can only use extensions that are published.

Description of extensions-import-dev.png follows
Description of the illustration extensions-import-dev.png

Note:

Sources for shared extensions can only be edited in the application containing the sources. The sources of extensions shared from other applications are not visible.

Updating Shared Extensions

When a new version of an application sharing extensions you are using is published, all extensions in that application are updated to the new version regardless of whether changes were made to the extension or not. A message is displayed in the Extensions manager when a new version of an extension is available.


Description of extensions-update-notification.png follows
Description of the illustration extensions-update-notification.png

Extensions in your application are not updated automatically. To apply the update you must explicitly update the extension in the Overview tab of the extension.


Description of extensions-update.png follows
Description of the illustration extensions-update.png

Using a Shared UI Component

Use the Extensions manager to add a shared UI component to your application.

UI components are extensions that can be integrated into the UI of an application by dragging the extension from the Components palette. UI component extensions can be data bound to business objects and fields, and can enumerate properties to the property inspector.  They can also be included in collection objects like lists and tables.

To add a shared UI component to your application:

  1. Open Extensions from the Application Settings page.
    The Extensions page has tabs for the different types of extensions.
  2. Select the UI Component tab in the Extensions manager.
  3. Click New UI Component and select Import Shared Resource from another application.
    The Import Extension from Another Application dialog box displays a list of shared UI component extensions that can be added and the name of the application sharing the extension.
    Description of extension-ui-add.png follows
    Description of the illustration extension-ui-add.png
  4. Select the UI component that you want to add. Click OK.
    The new UI component is added to the list of UI components that are used by your application.
    Description of extension-ui-add2.png follows
    Description of the illustration extension-ui-add2.png
  5. Open the Components palette in the Page Designer.
    To use the UI component you need to drag the component onto the canvas.
    Description of extension-ui-add3.png follows
    Description of the illustration extension-ui-add3.png
  6. Locate the UI component in the palette and drag the component into the page where you want to use it.
    You can use the Property Inspector to configure the component properties.

Using a Shared Resource

Use the Extensions manager to add a shared resource to your application.

Resources are JavaScript objects that can be loaded by the application at runtime. These objects will typically be used or required by other extensions.

To add a shared resource to your application:
  1. Open Extensions from the Application Settings page.
    The Extensions page has tabs for the different types of extensions.
  2. Select the Shared Resource tab in the Extensions manager.
  3. Click New Shared Resource and select Share from another application.
  4. Select the resource that you want to add. Click OK.
    The Import Extension from Another Application dialog box displays a list of shared resource extensions that can be added and the name of the application sharing the extension.
    Description of extension-resource-add.png follows
    Description of the illustration extension-resource-add.png
The new resource is added to the list of resources that are used by your application.
Description of extension-resource-add2.png follows
Description of the illustration extension-resource-add2.png

Using a Shared Business Object Provider

Use the Extensions manager to add a shared business object provider to your application.

Business object providers are used to establish a connection with a specific external REST service. After adding a business object provider you can select the service in the Service Catalog and create business objects from the service in your application. See Creating Custom Connectors for REST Services.

To add a shared business object provider:
  1. Open Extensions from the Application Settings page.
    The Extensions page has tabs for the different types of extensions.
  2. Select the Business Object Provider tab in the Extensions manager.
  3. Click New Business Object Provider and select Share from another application.
  4. Select the resource that you want to add. Click OK.
    The Import Extension from Another Application dialog box displays a list of shared resource extensions that can be added and the name of the application sharing the extension.
    Description of extensions-bop-shared-add.png follows
    Description of the illustration extensions-bop-shared-add.png
The business object provider is added to the list in the Business Object Provider tab.
Description of extensions-bop-shared.png follows
Description of the illustration extensions-bop-shared.png

You can now create business objects from the service by selecting the service in the Service Catalog.

Using a Shared Theme

Use the Extensions manager to add a shared theme to your application.

Themes specify the look and feel of applications by modifying the wrapper around the page content. Your application is provided with two default themes, but you can add themes to customize the look and feel of your pages. The simplest way to add a theme is by importing it from another application in your tenant space. Creating new themes is a task best left to experienced JavaScript developers.

Note:

You cannot modify shared themes that you add to your application. Every theme is owned and maintained by the developer of the application that is sharing the theme. If an update to a theme is available you must explicitly apply the update in the Themes tab.

To add a shared theme to your application:

  1. Open Extensions from the Application Settings page.
    The Extensions page has tabs for the different types of extensions.
  2. Select the Theme tab in the Extensions manager.
  3. Click New Theme and select Import Theme from another application.
    The Import Extension from Another Application dialog box displays a list of shared themes that can be added and the name of the application sharing the theme.
    Description of extension-theme-add.png follows
    Description of the illustration extension-theme-add.png
  4. Select the Theme that you want to add to your application. Click OK.
    The new theme is added to the list of themes that can be used in your application. To use the new theme you must select the theme in the Page Designer.
    Description of extension-theme-add2.png follows
    Description of the illustration extension-theme-add2.png
  5. Open the Themes palette in the Page Designer.
  6. Select the new theme in the palette.
    The theme is applied to your application when you select the theme in the palette.

Creating an Application Extension

Experienced JavaScript and web developers can use the source browser and editor in the Extensions manager to create extensions for applications.

The extensions framework allows a JavaScript/CSS developer to extend applications programmatically, and to create custom resources that can be shared and reused in other applications by developers who might not be programmers. An extension can be a functional element, such as a UI component, but it may also be a resource used by other extensions.

Extension source files are stored in the extensions directory of your application. In addition to the files required for registering and loading the extension, the folder might contain JavaScript, CSS, HTML, JSON and image files. If you create an extension you can view, add and edit the source files in the Sources tab for the extension. You can also use other tools to edit files that you then add to your directory. For example, if you want to edit the sources in an editor on your local system, you can click Export in the Sources tab to download the sources as a zip archive. Select Import from ZIP in the Extensions manager to import the edited files.

Note:

Sources for extensions can only be edited in the application containing the sources. If you share an extension with other applications, you should carefully consider any changes that you make to the extension because your changes will be implemented in the applications where the extension is used. To prevent accidental changes, you might want to create and publish an application that serves as a container for your shared extensions.

When you create an extension you can use the basic skeleton template for your type of extension to create the initial directory structure and files. The Empty Extension template is the same for all extension types and creates the files EmptyTemplate.js and manifest.json. The manifest.json file contains the metadata for the extension, including its ID, name, description, type and package name, as well as a list of the assets provided by the extension. It also specifies the ExtensionManager that the extension should use (by default, the skeleton JavaScript file EmptyTemplate.js ).


Description of extension-json-editor.png follows
Description of the illustration extension-json-editor.png

The Empty Extension template creates only the most basic file skeletons and the structure for your extension. For each type of extension you can also choose a template that will create a sample extension that can help you get started with creating an application extension. For example, the simple template for a Theme extension generates various assets, including JavaScript files for registering the theme during initialization, HTML files used for the page layout and CSS files.

Tutorial iconCreating a Theme Tutorial


Description of extension-theme-editor.png follows
Description of the illustration extension-theme-editor.png

To create an extension:

  1. Open Extensions from the Application Settings page.
    The Extensions page has tabs for the different types of extensions.
  2. Open the tab for the type of extension you want to create.
    For example, open the Theme tab to create a theme extension.
    Description of extension-theme-new-create.png follows
    Description of the illustration extension-theme-new-create.png
  3. Click New Theme and select Create New Theme in the menu.
  4. Supply the details in the Create New Extension dialog box. Click Template.
    The details that you supply in the Create New Extension dialog box are used to generate the manifest.json file for the extension. The image is used to represent the extension in the UI, where possible. For example, when you create a theme, the image is used to represent the theme in the Themes palette.
    Description of extension-theme-new.png follows
    Description of the illustration extension-theme-new.png
  5. Select a template. Click OK.
    For each extension type you can choose an Empty Extension template or a template that creates an example of the extension.
    Description of extension-theme-template.png follows
    Description of the illustration extension-theme-template.png
The Extensions manager lists the new extension under the tab for the extension type. Use the Overview tab to view extension details and the Sources tab to browse and edit the source files.
Description of extension-theme-new2.png follows
Description of the illustration extension-theme-new2.png

Importing a Composite Component Architecture (CCA) Component

If you have access to a Composite Component Architecture (CCA) component, you can import it into Visual Builder as a custom UI component.

CCA components support the Oracle JavaScript Extension Toolkit (JET) Composite Component Architecture. See Composite Components in the JET Cookbook for an example of a CCA component. The example displays the code for each file in the component.

Note:

Oracle JET composite components are currently not backward-compatible. When importing composite components, and when upgrading composite components or your app, you need to ensure that your application and all composite 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 for Oracle Integration.

You can copy the code into files on your local system, zip the files, and then import the ZIP file into Visual Builder. A ZIP file for a CCA component contains the following files, which are described in more detail on the Oracle JET site.

File Description
loader.js A RequireJS module that defines the composite dependencies for its metadata, View, ViewModel, and CSS
component.json The composite metadata file that defines its available properties and methods
view.html The View for the composite
viewModel.js The ViewModel for the composite where methods defined in the composite metadata are defined
styles.css The custom styling for this composite
Graphics files Any images you use in the component

You can customize the names of the view.html, viewModel.js, and styles.css files.

To import a CCA component:

  1. Open the application into which you want to import the component.
  2. Select Application Settings in the main menu, then select Extensions.
  3. In the UI Component tab, click New UI Component and select Import from ZIP.
    Description of extension-cca-import.png follows
    Description of the illustration extension-cca-import.png
  4. In the Import Extension from ZIP dialog box, click Upload a ZIP file and select the file you are importing, then click Done.
  5. Click the Sources tab to view the files.
    Description of extension-cca-files.png follows
    Description of the illustration extension-cca-files.png

Note:

The contents of this CCA component are not identical to what you would see if you copied and zipped the files from the JET demo and imported them as is. The component.json file has some properties specific to Visual Builder, the component has been renamed from demo-card to employee-card, and the images have been added.

When Visual Builder creates an extension from a CCA ZIP file, it also creates a manifest.json file to describe the component, and it places the imported files in a component subdirectory. For example, if the loader.js file registers the component as employee-card, Visual Builder creates a folder under user/extensions named oracle.abcs.composite.employee-card. Within this folder are the manifest.json file and the component subdirectory. The imported files are in the component subdirectory.

This example component has two image files that will be used in the Components Palette of the Page Designer. Their use is specified by the icon property in component.json.

The manifest.json file looks like this:

{
    "description": "This is a demo showing an employee card.",
    "displayName": "Employee Card",
    "extensionManager": "components.cca.dt/js/CCAExtensionManager",
    "id": "employee-card",
    "image": "",
    "package": "oracle.abcs.composite.employee-card",
    "runtime": {
        "resources": [
            "component/loader.js",
            "component/employee-card.html",
            "component/component.json",
            "component/employee-card.js",
            "component/employee-card.css",
            "component/people-icon-bw.png",
            "component/people-icon-colour.png"
        ]
    },
    "type": "uicomponent"
}

The file takes the description and displayName values from the component.json file. The extensionManager property is set to the API class components.cca.dt/js/CCAExtensionManager. (This class is internal and is not published.) The id property value is taken from the name value in component.json. The image property has no value. The package property specifies the folder where the component is placed. The runtime resources are the files in the component ZIP file, and the type property is set to uicomponent.

See Adding an Oracle JET Composite Component to a Page for information on activating an imported CCA component and using it in an application.

Sharing Your Extension With Other Applications

You can allow other applications in the tenant space to reuse your extensions by sharing your application resources.

When you share the resources in your application you allow all other applications to reuse the extensions in your application. Applications can add and use any extensions in the tenant space that are shared, but they cannot edit the sources. The extension sources can only be modified from the application that maintains the sources. You might consider only enabling resource sharing when development of the extension is finished and the application is published. For example, you might create an application that is used for developing and maintaining shared extensions.

An application containing an extension must be published before other applications can use its shared extensions. Once published, the sources for the extension are read-only. To update an extension you must create a new version of the application containing the extension. New versions of the extensions in the application are released each time that you publish a new version of the application. After publishing the new version, applications using the shared extension can be updated to use the new version. The updated extension is not automatically implemented in other applications. Application developers must explicitly choose to update the extension to the newer version.

When you enable sharing for your application, all the extensions in your application are shared and available to other applications when the application is published. You cannot individually select the extensions in your application that you want to share. You can, however, individually select which extensions are active.

Important:

Deleting an extension that you are sharing with other applications might cause the applications using the extension to stop working or make them inaccessible to other developers.

To share an extension:

  1. Locate the Overview tab for the extension you want to share.
  2. Toggle Extension Active to activate the extension.
  3. Open General from the Application Settings page.
  4. Enable Application Shares Resources.
    After you enable resource sharing, any other application in the tenant space can reuse any of the extensions that you created.
    Description of extensions-appsettings-share.png follows
    Description of the illustration extensions-appsettings-share.png

    Attention:

    If you disable resource sharing, your extensions will be inaccessible to all applications that have added them. This can result in unpredictable behavior and it is possible that some applications might stop working.
  5. Stage and publish the application.