Element: <oj-module>

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

Since:
  • 4.2.0
Module:
  • ojmodule-element

QuickNav

Attributes

Events


JET Module

The oj-module custom element is used for binding a view and a corresponding view model to an element to provide content replacement within a particular region of the page. In case of a single page application the element config attribute defines navigation within a region. 


<oj-module config='[[moduleConfig]]' animation='[[moduleAnimation]]'>
</oj-module>

ModuleElementUtils - You can use ModuleElementUtils helper methods in conjunction with oj-module to generate a configuration object for the element. See the demos and documentation for the ModuleElementUtils class for details on the available methods.

View Models

Lifecycle

If a ViewModel is provided as a part of configuration for the oj-module element, it should implement the ModuleViewModel interface to provide lifecycle callbacks. See the lifecycle methods that could be implemented on the view model that will be called at each stage of the component's lifecycle.

Best Practices

We recommend using non-singleton ViewModels for modules that may contain child modules. If the parent module's ViewModel has to be a singleton, application developers have to ensure that a new view is being returned every time the child module is re-rendered (this can be achieved by binding the child module's config object to a function call).

When the parent module is cleaning its view, it will not stop at the boundary of the child module, i.e. the entire DOM hierarchy will be cleaned. This creates problems when the cleaned child module's view is cached. To avoid this issue, only cache child modules if their parent modules are also being cached, or ensure that the child module's cache is emptied when the parent module's view is about to be cleaned (see the disconnected callback and the ojViewDisconnected event).


Usage

Signature:

interface ModuleElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { ModuleElement } from "ojs/ojmodule-element";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojmodule-element";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Attributes

animation :ModuleElementAnimation

Instance of the oj.ModuleElementAnimation duck-typing interface that will manage animation effects during View transitions. Note that during the animation transition, the original View and the View that is being transitioned to may both be simultaneously attached to the DOM. Consequently, it is the application's responsbility to ensure that element IDs are unique across Views.
Default Value:
  • null
Names
Item Name
Property animation
Property change event animationChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-animation-changed

config :Object|Promise

Configuration object that defines a view and a corresponding view model responsible the markup section under oj-module. An application can also specify a clean up mode for the view as a part of the configuration object. See details for each attribute. The configuration object can be specified either directly or via a Promise.
Names
Item Name
Property config
Property change event configChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-config-changed

(nullable) config.cleanup-mode :string

Defines the clean up mode for the view. The setting allows an application to use an external cache for the view and view model. By default the oj-module element will clean up and release the view nodes when the view is removed from the DOM. If an application wants to keep the view and view model in memory for faster access, it should set the cleanupMode to "none" and retain references to the view and viewModel to be used when the module is reloaded. Note, when the cached view is no longer needed, the application should call the Knockout ko.cleanNode() method on all the top-level nodes in the view. Also, if the cached view might receive observable changes, it must be kept connected in the DOM (perhaps with the CSS display:none style).
Supported Values:
Value Description
none Use the setting to preserve the view, e.g. if the view and view model will be stored in external cache.
onDisconnect The View nodes will be destroyed on disconnect.
Default Value:
  • "onDisconnect"
Names
Item Name
Property config.cleanupMode

config.view :Array.<Node>

Defines the view for the ojModule.

Note that oj-module will not be cloning the node array before using it as the module's View and applying bindings to it. If the application needs to have an access to the original node array, it should be setting the 'view' property to a cloned copy.

Default Value:
  • null
Names
Item Name
Property config.view

config.view-model :(oj.ModuleViewModel|null)

Defines model for the view.

The following optional lifecycle methods can be defined on the ViewModel object and will be called at the corresponding lifecycle stage. See View Model Lifecycle section

Default Value:
  • null
Names
Item Name
Property config.viewModel

Events

ojTransitionEnd

Triggered after transition to the new View is complete. That includes any possible animation between the old and the new View.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
viewModel oj.ModuleViewModel ViewModel for the new View.

ojTransitionStart

Triggered before transition to the new View is started - before View is inserted into the DOM.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
viewModel oj.ModuleViewModel ViewModel for the new View.

ojViewConnected

Triggered after the View is inserted into the DOM.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
viewModel oj.ModuleViewModel ViewModel for the View being attached to the DOM.

ojViewDisconnected

Triggered after the View is removed from the DOM
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
view Array.<Node> ViewModel for the new View.
viewModel oj.ModuleViewModel An array of DOM nodes that represent the disconnected View. The application can use the nodes to store them in cache.