Namespace: Composite

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

Fields

oj. Composite

Version:
  • 3.2.0

A composite component is a reusable piece of UI that can be embedded as a custom HTML element and can be composed of other composites, JET components, HTML, JavaScript, or CSS.

Packaging and Registration

Composite components should be packaged as a standalone module in a folder matching the tag name it will be registered with, e.g. 'my-chart'. An application would use a composite by requiring it as a module, e.g. 'jet-composites/my-chart/loader'. The composite module could be stored locally in the app which is the recommended approach, but could also be stored on a different server, or a CDN. Note that there are XHR restrictions when using the RequireJS text plugin which may need additional RequireJS config settings. Please see the text plugin documentation for the full set of limitations and options. By using RequireJS path mappings, the application can control where individual composites are loaded from. See below for a sample RequireJS composite path configuration. Note that the 'jet-composites/my-chart' mapping is only required if the 'my-chart' composite module maps to a folder other than 'someSubFolder/jet-composites/my-chart' using the configuration below.


requirejs.config(
{
  baseUrl: 'js',
  paths:
  {
    'jet-composites': 'someSubFolder/jet-composites',
    'jet-composites/my-chart': 'https://someCDNurl',
    'jet-composites/my-table': 'https://someServerUrl'
  }
}

All composite modules should contain a loader.js file which will handle registering and specifying the dependencies for a composite component. We recommend using RequireJS to define your composite module with relative file dependencies. Registration is done via the oj.Composite.register API. By registering a composite component, an application links an HTML tag with provided Metadata, View, ViewModel and CSS which will be used to render the composite. These optional pieces can be provided via a descriptor object passed into the register API which defines how each piece will be loaded, either inline or as a Promise. See below for sample loader.js file configurations.

Note that in this example we are using a RequireJS plugin for loading css which will load the styles within our page so we do not need to pass any css into the register call.

define(['text!./my-chart.html', './my-chart', 'text!./my-chart.json', 'css!./my-chart'],
  function(view, viewModel, metadata) {
    oj.Composite.register('my-chart',
    {
      metadata: {inline: JSON.parse(metadata)},
      view: {inline: view},
      viewModel: {inline: viewModel}
    });
  }
);

This example shows how to pass inline CSS to the register call.

define(['text!./my-chart.html', './my-chart', 'text!./my-chart.json'],
  function(view, viewModel, metadata) {
    oj.Composite.register('my-chart',
    {
      metadata: {inline: JSON.parse(metadata)},
      view: {inline: view},
      viewModel: {inline: viewModel},
      css: {inline: 'my-chart {font-size:20px; color:blue;}'}
    });
  }
);

This example shows how to register a custom parse function which will be called to parse attribute values defined in the metadata.

define(['text!./my-chart.html', './my-chart', 'text!./my-chart.json'],
  function(view, viewModel, metadata) {
    var myChartParseFunction = function(value, name, meta, defaultParseFunction) {
      // Custom parsing logic goes here which can also return defaultParseFunction(value) for
      // values the composite wants to default to the default parsing logic for.
      // This function is only called for non bound attributes.
    }

    oj.Composite.register('my-chart',
    {
      metadata: {inline: JSON.parse(metadata)},
      view: {inline: view},
      viewModel: {inline: viewModel},
      parseFunction: myChartParseFunction
    });
  }
);

Usage

Once registered within a page, a composite component can be used in the DOM as a custom HTML element like in the example below. Currently, composites need to be in a knockout activated subtree, but this requirement may change in future releases.


<my-chart type="bubble" data="{{dataModel}}"></my-chart>

Metadata

Metadata can be provided via JSON format which will be used to define the composite component. The Metadata can be extended by appending any extra information in an "extension" field except at the first level of the "properties", "methods", "events" or "slots" objects. Any metadata in an extension field will be ignored.

The Metadata JSON object should have the following required properties: "name", "version", "jetVersion" and the following optional properties: "description", "compositeDependencies", "icon", "displayName", "properties", "methods", "events", or "slots". See the tables below for descriptions of these properties.

Keys defined in the "properties" top level object should map to the composite component's properties following the same naming convention described in the Property-to-Attribute mapping section. Non expression bound composite component attributes will be correctly evaluated only if they are a primitive JavaScript type (boolean, number, string) or a JSON object. Note that JSON syntax requires that strings use double quotes. Attributes evaluating to any other types must be bound via expression syntax. Boolean attributes are considered true if set to the case-insensitive attribute name, the empty string or have no value assignment. JET composite components will also evalute boolean attributes set explicitly to 'true' or 'false' to their respective boolean values. All other values are invalid.

Not all information provided in the Metadata is required at run time and those not indicated to be required at run time in the tables below can be omitted to reduce the Metadata download size. Any non run time information can be used for design time tools and property editors and could be kept in a separate JSON file which applications can use directly or merge with the run time metadata as needed, but would not be required by the loader.js file. For methods and events, only the method/event name is required at run time.

Metadata Properties

Key Required Type Description
name yes {string} The component tag name.
version yes {string} The component version. Note that changes to the metadata even for minor updates like updating the jetVersion should result in at least a minor composite version change, e.g. 1.0.0 -> 1.0.1.
jetVersion yes {string} The semantic version of the supported JET version(s). Composite authors should not specify a semantic version range that includes unreleased JET major versions as major releases may contain non backwards compatible changes. Authors should instead recertify composites with each major release and update the composite metadata or release a new version that is compatible with the new release changes.
compositeDependencies no {Object} Dependency to semantic version mapping for composite dependencies. 3rd party libraries should not be included in this mapping. Not used at run time. {"composite1": "1.2.0", "composite2": ">=2.1.0"}
description no {string} A high-level description for the component. Not used at run time.
displayName no {string} A user friendly, translatable name of the component. Not used at run time.
icon no {Object} One or more optional images for representing the component within a design time environment's component palette. The object has the following properties:
Properties
Name Type Description
iconPath {string} A relative path to the default (enabled) icon.
selectedIconPath {string} A relative path to the icon that represents the selected state of the component.
hoverIconPath {string} A relative path to the icon that represents the hover state of the component.

Not used at runtime.
properties no {Object} See Properties table below for details.
methods no {Object} See Methods table below for details.
events no {Object} See Events table below for details.
slots no {Object} See Slots table below for details. Not used at run time.

Properties

Key Value
[property name] Object containing the following properties:
Properties
Name Type Description
description {string} A description for the property. Not used at run time.
displayName {string} A user friendly, translatable name of the property. Not used at run time.
displayOrder {number} Display ranking of the property (nth property). Not used at run time.
editable {boolean} Specifies whether the property can be changed within a design time environment. True by default. Not used at run time.
enumValues {Array} An optional list of valid enum values for a string property. An error is thrown if a property value does not match one of the provided enumValues.
max {number} Validation metadata for number type properties. Specifies the high end of a possible range of values. Not used at run time.
min {number} Validation metadata for number type properties. Specifies the low end of a possible range of values. Not used at run time.
priority {string} Sets the priority for this property. Valid settings are:
  • "required" - required to be set to a valid value at run time
  • "primary" - specifying a value for this property should be encouraged when creating an instance of this component in a design time environment (e.g., provide a field for this property in a popup dialog at create time when the component is dragged onto the page from the component palette).
  • "optional" - the default, if unspecified
Not used at run time.
propertyEditorHint {string} Hint to the design time regarding what UI element to use for editing this property in the design time. Valid settings:
  • "checkbox" (input form of type "checkbox")
  • "checkboxSet" (multiple checkboxes allowing multi select)
  • "combobox" (editable single selection)
  • "enumeration" (icon-based radio buttons)
  • "inputDate" (editable text field handling Date type input)
  • "inputText" (input form of type "text")
  • "none" (do not display in the property inspector)
  • "multiSelect" (multiple selection allowed if the property is an enum, non-editable)
  • "radioSet" (text-based radio buttons)
  • "select" (single select dropdown, non-editable values)
Not used at run time.
propertyEditorValues {Object} Additional design time metadata that enhances the enumValues run time metadata. The value is an Object with properties matching the values in the enumValues array. The corresponding value for each key is an Object with the following properties:
Properties
Name Type Description
displayName {string} A displayable, translatable label for the value.
icon {Object} One or more optional images for representing the value. The object has the following properties:
Properties
Name Type Description
iconPath {string} A relative path to the icon that represents the value.
selectedIconPath {string} A relative path to the icon that represents the selected state of the value.
hoverIconPath {string} A relative path to the icon that represents the hover state of the value.

Not used at run time.
properties {Object} A nested properties object for complex properties. Subproperties exposed using nested properties objects in the metadata can be set using dot notation in the attribute. See the Subproperties section for more details on working with subproperties.
propertyGroup {string} Identifies a grouping bucket for this property.  For example, design time tools would typically group properties associated with data binding under a "Data" propertyGroup. Ordering within a propertyGroup is determined by displayOrder. Not used at run time.
readOnly {boolean} Determines whether a property can be updated outside of the ViewModel. False by default. If readOnly is true, the property can only be updated by the ViewModel or by the components within the composite. This property only needs to be defined for the top level property, with subproperties inheriting that value.
translatable {boolean} True if the value of this property is eligible to be included when application resources are translated for Internationalization. False by default. Not used at run time.
type {string} The type of the property, following Google's Closure Compiler syntax. We will parse string, number, boolean, array and object types for non data-bound attributes, but will not provide type checking for array and object elements. However, for documentation purposes, it may still be beneficial to provide array and object element details using the Closure Compiler syntax.
value {object} An optional default value for a property.
writeback {boolean} Determines whether an expression bound to this property should be written back to. False by default. If writeback is true, any updates to the property will result in an update to the expression. This property only needs to be defined for the top level property, with subproperties inheriting that value.

Methods

Key Value
[method name] Object containing the following properties:
Properties
Name Type Description
description {string} A description for the method. Not used at run time.
displayName {string} A user friendly, translatable name of the method. Not used at run time.
internalName {string} An optional ViewModel method name that is different from, but maps to this method.
params {Array<{description: string, name: string, type: string}>} An array of objects describing the method parameter. Not used at run time.
return {string} The return type of the method, following Closure Compiler syntax. Not used at run time.

Events

Key Value
[event name] Object containing the following properties:
Properties
Name Type Description
bubbles {boolean} Indicates whether the event bubbles up through the DOM or not. Defaults to false. Not used at run time.
cancelable {boolean} Indicates whether the event is cancelable or not. Defaults to false. Not used at run time.
description {string} A description for the event. Not used at run time.
displayName {string} A user friendly, translatable name of the event. Not used at run time.
detail {object} Describes the properties available on the event's detail property which contains data passed when initializing the event. Not used at run time.

Properties
Name Type
[field name] {description: string, type: string}

Slots

Key Value
[slot name] Object containing the following properties:
Properties
Name Type Description
description {string} A description for the slot. Not used at run time.
displayName {string} A user friendly, translatable name of the slot. Not used at run time.

Example of Run Time Metadata

The JET framework will ignore "extension" fields. Extension fields cannot be defined at the first level of the "properties", "methods", "events", or "slots" objects.


{
 "name": "demo-card",
 "version": "1.0.2",
 "jetVersion": ">=3.0.0 <5.0.0",
 "properties": {
   "currentImage" : {
     "type": "string",
     "readOnly": true
   },
   "images": {
     "type": "Array"
   },
   "isShown": {
     "type": "boolean",
     "value": true
   }
 },
 "methods": {
   "nextImage": {
     "internalName": "_nextImg"
     "extension": "This is where a composite can store additional data."
   },
   "prevImage": {}
  },
  "events": {
    "cardclick": {}
  }
}

Properties

Properties defined in provided Metadata will be made available through the $props property of the View binding context and through the props property on the context passed to the provided ViewModel constructor function or lifecycle listeners if an object instance is passed. Unlike the $props property for the View, the props property made available to the ViewModel will be a Promise which will contain the properties object when resolved. The application can access the composite component properties by accessing them directly from the DOM element. Using the DOM setAttribute and removeAttribute APIs will also result in property updates. Changes made to properties will result in a [propertyName]Changed event being fired for that property regardless of where they are modified.

Property-to-Attribute Mapping

The following rules apply when mapping property to attribute names:

  • Attribute names are case insensitive and are considered to be all lower case. Properties with camelCase are mapped to attribute names by inserting a dash before the uppercase letter and converting that letter to lower case, e.g. a "chartType" property will be mapped to a "chart-type" attribute.
  • The reverse occurs when mapping a property name from an attribute name.

Subproperties

Subproperties can be exposed and documented by adding nested properties objects in the composite metadata. Event listeners should be added for the top level property, with applications checking the event's subproperty field to access information about the subproperty changes. Subproperties can be set declaratively using dot notation, e.g. person.first-name="{{name}}". Setting overlapping attributes, e.g. person="{{personInfo}}" person.first-name="{{name}}" will cause an error to be thrown.

Subproperties can also be set programmatically using the set/getProperty methods. Note that while setting the subproperty using dot notation via the element's top level property is allowed, the setProperty method must be used in order to trigger a property change event.


element.setProperty("person.firstName", Fred);
var firstName = element.getProperty("person.firstName");

Styling

Composite component styling can be done via provided css. The application should note that CSS will not be scoped to the composite component and selectors will need to be appropriately selective. The JET framework will add the oj-complete class to the composite DOM element after metadata properties have been resolved. To prevent a flash of unstyled content before the composite properties have been setup, the composite css can include the following rule to hide the composite until the oj-complete class is set on the element.


my-chart:not(.oj-complete) {
  visibility: hidden;
}

Events

Composite components fire the following events. Any custom composite events should be created and fired by the composite's ViewModel and documented in the metadata for design and run time environments as needed. In addition to standard add/removeEventListener syntax, declarative event listeners will also be supported for custom composite events and [propertyName]Changed events. As a result, if a composite declares an event of type "customType", applications can listen by setting the "onCustomType" property or the "on-custom-type" attribute. Similarly, property change listeners can be set via the appropriate "on[PropertyName]Changed" property or "on-[property-name]-changed" attribute. Expression syntax can be used in the on-[event-name] attributes, but we do not support executing arbitrary JavaScript like those for native event attributes like onclick.

  • pending (Deprecated) - Fired to notify the application that a composite component is about to render. This event is deprecated. The application should use the page's oj.BusyContext to determine when the composite is ready.
  • ready (Deprecated) - Fired after bindings are applied on the composite component's children. Child pending events will be fired before the parent composite component's ready event. Note that this does not gaurantee that its children are ready at this point as they could be performing their own asynchronous operations. Applications may use the pending and ready events to determine when a composite component and its children are fully ready (i.e. when the number of received ready events matches the number of received pending events). This event is deprecated. The application should use the page's oj.BusyContext to determine when the composite is ready.
  • [propertyName]-changed (Deprecated) - Fired when a property is modified and contains the following fields in its event detail object:
    • previousValue - The previous property value
    • value - The new property value
    • updatedFrom - Where the property was updated from. Supported values are:
      • default - The default value specified in the metadata.
      • internal - The View or ViewModel
      • external - The DOM Element either by its property setter, setAttribute, or external data binding.
    • subproperty - An object containing information about the subproperty that changed with the following fields:
      • path - The subproperty path that changed
      • previousValue - The previous subproperty value
      • value - The new subproperty value
    This event is deprecated. Applications should listen to [propertyName]Changed events instead.
  • [propertyName]Changed - Fired when a property is modified and contains the following fields in its event detail object:
    • previousValue - The previous property value
    • value - The new property value
    • updatedFrom - Where the property was updated from. Supported values are:
      • default - The default value specified in the metadata.
      • internal - The View or ViewModel
      • external - The DOM Element either by its property setter, setAttribute, or external data binding.
    • subproperty - An object containing information about the subproperty that changed with the following fields:
      • path - The subproperty path that changed
      • previousValue - The previous subproperty value
      • value - The new subproperty value

Lifecycle

If a ViewModel is provided for a composite component, the following optional callback methods can be defined on its ViewModel and will be called at each stage of the composite component's lifecycle. The ViewModel provided at registration can either be a function which will be treated as a constructor that will be invoked to create the ViewModel instance or an object which will be treated as a singleton instance.

initialize(context)

This optional method may be implemented on the ViewModel to perform initialization tasks. This method will be invoked only if the ViewModel specified during registration is an object instance as opposed to a constructor function. If the registered ViewModel is a constructor function, the same context object will be passed to the constructor function instead. This method can return 1) nothing in which case the original model instance will be used, 2) a new model instance which will replace the original, or 3) a Promise which resolves to a new model instance which will replace the original and delay additional lifecycle phases until it is resolved.
Parameters:
Name Type Description
context Object An object with the following key-value pairs:
Properties:
Name Type Description
element Node DOM element where the View is attached.
props Promise A Promise evaluating to the composite component's properties.
slotNodeCounts Promise A Promise evaluating to a map of slot name to assigned nodes count for the View.
unique string A unique string that can be used for unique id generation.

activated(context)

This optional method may be implemented on the ViewModel and will be invoked after the ViewModel is initialized. This method can return a Promise which will delay additional lifecycle phases until it is resolved and can be used as a hook for data fetching.
Parameters:
Name Type Description
context Object An object with the following key-value pairs:
Properties:
Name Type Description
element Node DOM element where the View is attached.
props Promise A Promise evaluating to the composite component's properties.
slotNodeCounts Promise A Promise evaluating to a map of slot name to assigned nodes count for the View.
unique string A unique string that can be used for unique id generation.

attached(context)

This optional method may be implemented on the ViewModel and will be invoked after the View is inserted into the document DOM.
Parameters:
Name Type Description
context Object An object with the following key-value pairs:
Properties:
Name Type Description
element Node DOM element where the View is attached.
props Promise A Promise evaluating to the composite component's properties.
slotNodeCounts Promise A Promise evaluating to a map of slot name to assigned nodes count for the View.
unique string A unique string that can be used for unique id generation.

bindingsApplied(context)

This optional method may be implemented on the ViewModel and will be invoked after the bindings are applied on this View.
Parameters:
Name Type Description
context Object An object with the following key-value pairs:
Properties:
Name Type Description
element Node DOM element where the View is attached.
props Promise A Promise evaluating to the composite component's properties.
slotNodeCounts Promise A Promise evaluating to a map of slot name to assigned nodes count for the View.
unique string A unique string that can be used for unique id generation.

detached(element)

This optional method may be implemented on the ViewModel and will be invoked when this composite component is detached from the DOM.
Parameters:
Name Type Description
element Node The composite component DOM element.

dispose(element)

Deprecated: use the detached method instead. This optional method may be implemented on the ViewModel and will be invoked when this composite component is being disposed.
Parameters:
Name Type Description
element Node The composite component DOM element.

Data Binding and Expression Writeback

Besides string literals, composite attributes can be set using expression syntax which is currently compatible with knockout expression syntax. Applications can control expression writeback in the composite component by using {{}} syntax for two-way writable binding expressions or [[]] for one-way only expressions. In the example below, the salesData expression will not be written back to if the 'data' property is updated by the composite component's ViewModel. The 'data' property will contain the current value, but the salesData expression will not be updated. Alternatively, if the 'axisLabels' property is updated by the ViewModel, both the 'axisLabel' property and the showAxisLabels expression will contain the updated value. Updating a readOnly property will disconnect the expression binding since the expression will no longer be in sync with the property value. The property will still update and a property change event, [propertyName]Changed, will still be fired when the property value changes regardless of whether the expression is written back to.


<my-chart data="[[salesData]]" axis-labels={{showAxisLabels}} ... >
</my-chart>

readOnly

The composite component Metadata also defines properties to control expression writeback and property updates. If a property's readOnly option is omitted, the value is false by default, meaning the property can be updated outside of the composite component. If readOnly is true, the property can only be updated inside of the composite component by the ViewModel or View.

writeback

If a property's Metadata defines its writeback property as true (false by default), any bound attribute expressions will be updated when the property is updated unless the attribute binding was done with a one-way "[[]]"" binding syntax.

Slotting

Complex composite components which can contain additional composites and/or content for child facets defined in its associated View can be constructed via slotting.

Definitions

Assignable Node

Properties
  • Nodes with slot attributes will be assigned to the corresponding named slots (if present) and all other assignable nodes (Text or Element) will be assigned to the default slot (if present).
  • The slot attribute of a node is only applied once. If the View contains a composite and the node's assigned slot is a child of that composite, the slot attribute of the assigned slot is inherited for the slotting of that composite.
  • Nodes with slot attributes that reference slots not present in the View will not appear in the DOM.
  • If the View does not contain a default slot, nodes assigned to the default slot will not appear in the DOM.
  • Nodes that are not assigned to a slot will not appear in the DOM.

Slot

Properties
  • A default slot is a slot element whose slot name is the empty string or missing.
  • More than one node can be assigned to the same slot.
  • A slot can also have a slot attribute and be assigned to another slot.
  • A slot can have fallback content which are its child nodes that will be used in the DOM in its place if it has no assigned nodes.
  • A slot can also also have an index attribute to allow the slot's assigned nodes to be individually slotted (e.g. in conjunction with a Knockout foreach binding).

Applying Bindings

The following steps will occur when processing the binding for a composite component:

  1. Apply bindings to children using the composite component's binding context.
  2. Create a slot map assigning component child nodes to View slot elements.
    1. At this point the component child nodes are removed from the DOM and live in the slot map.
  3. Insert the View and apply bindings to it with the ViewModel's binding context.
    1. The composite's children will be 'slotted' into their assigned View slots.
    2. The oj-slot's slot attribute, which is "" by default, will override its assigned node's slot attribute.

Example #1: Basic Usage

Note that the IDs are provided for sample purposes only.
Initial DOM

<oj-a>
 <div id="A" slot="foo"></div>
 <div id="B" slot="bar"></div>
 <div id="C"></div>
 <div id="D" slot="foo"></div>
 <div id="E" slot="cat"></div>
</oj-a>

View

<!-- oj-a View -->
<div id="outerFoo">
 <oj-slot name="foo"></oj-slot>
</div>
<div id="outerBar">
 <oj-slot name="bar"></oj-slot>
</div>
<div id="outerBaz">
 <oj-slot name="baz">
   <!-- Default Content -->
   <img id="F"></img>
   <div id="G"></div>
 </oj-slot>
</div>
<div id="outerDefault">
 <oj-slot>
   <!-- Default Content -->
   <div id="H"></div>
 </oj-slot>
</div>

Final DOM

<oj-a>
 <div id="outerFoo">  
     <div id="A" slot="foo"></div>
     <div id="D" slot="foo"></div>
 </div>
 <div id="outerBar">
     <div id="B" slot="bar"></div>
  </div>
 <div id="outerBaz">
     <img id="F"></img>
     <div id="G"></div>
 </div>
 <div id="outerDefault">
     <div id="C"></div>
 </div>
</oj-a>

Example #2: Slot Attribute Evaluation

When a node is assigned to a slot, its slot value is not used for subsequent slot assignments when child bindings are applied. Instead that slot's slot attribute, which by default is "", overrides the assigned node's slot attribute. No actual DOM changes will be made to the assigned node's slot attribute, but its evaluated slot value will be managed internally and used for applying subsequent child bindings.

Initial DOM

<oj-a>
 <div id="A" slot="foo"></div>
</oj-a>

View

<!-- oj-a View -->
<oj-b>
 <oj-slot name="foo"></oj-slot>
</oj-b>

<!-- oj-b View -->
<div id="outerFoo">
 <oj-slot name="foo"></oj-slot>
</div>
<div id="outerDefault">
 <oj-slot></oj-slot>
</div>

When applying bindings for the oj-a View, the oj-slot binding will replace slot foo with div A. Slot foo's slot attribute ("") overrides div A's ("foo") so that the evaluated slot value ("") will be used when applying subsequent child bindings.


<!-- DOM -->
<oj-a>
 <!-- Start oj-a View -->
 <oj-b>
   <!-- Evaluated slot value is "" -->
   <div id="A" slot="foo"></div>
 </oj-b>
 <!-- End oj-a View -->
</oj-a>

When applying bindings for the oj-b View, the oj-slot binding will replace oj-b's default slot with div A since it's evaluated slot value is "".


<!-- DOM -->
<oj-a>
 <!-- Start oj-a View -->
 <oj-b>
   <!-- Start oj-b View -->
   <div id="outerFoo">
   </div>
   <div id="outerDefault">
     <div id="A" slot="foo"></div>
   </div>
   <!-- End oj-b View -->
 </oj-b>
 <!-- End oj-a View -->
</oj-a>

Automation

The JET framework will by default expose getNodeBySubId/getSubIdByNode implementations on the composite element, using the presence of data-oj-subid(-map) attribute markup within the composite View to determine which elements to expose. The data-oj-subid attribute takes a single string which maps that element to the given subid The data-oj-subid-map attribute takes a JSON object containing custom subIds that map to component subIds when the component is another composite or JET component. If both attributes are specified, the data-oj-subid-map value takes precedence and data-oj-subid will be ignored as we do not recommend exposing both. If the composite can expose all necessary subIds via the data-oj-subid(-map) attributes then it does not need to provide its own implementation. However, for cases like exposing subIds on stamped items, the composite can provide its own implementation on the composite ViewModel. For an example and more details, please see the "Preparing Oracle JET Composite Components for Automation Testing" section of the Developer's Guide. The composite does not need to define getNodeBySubId/getSubIdByNode methods in the metadata except for documentation purposes.

Source:

Fields

<static> defaults

Default configuration values. Composite component conventions may be overridden for the entire application after the ojs/ojcomposite module is loaded. For example:

oj.Composite.defaults.bindingsAppliedMethod = 'applied';

Properties:
Name Type Description
initializeMethod string The name of the initialialization method. Defaults to 'initialize'.
activatedMethod string The name of the method invoked after the Model is instantiated. Defaults to 'activated'.
attachedMethod string The name of the method invoked when the View is inserted into the document DOM. Defaults to 'attached'.
bindingsAppliedMethod string The name of the method invoked after the bindings are applied on the View. Defaults to 'bindingsApplied'.
detachedMethod string The name of the method called when the composite is detached from the DOM. Defaults to 'detached'.
disposeMethod string Deprecated: Use the detached method instead. The name of the method called when the composite is disposed. Defaults to 'dispose'.
Deprecated:
  • Since composites are designed to be reusable components, we do not recommend overriding the default lifecycle listener names and potentially breaking consumed composites.
    Source:

    Methods

    <static> getMetadata(name) → {Promise}

    Returns a Promise resolving with the composite metadata with the given name.
    Parameters:
    Name Type Description
    name string The component name, which should contain a dash '-' and not be a reserved tag name.
    Source:
    Returns:
    Type
    Promise

    <static> register(name, descriptor)

    Registers a composite component
    Parameters:
    Name Type Description
    name string The component name, which should contain a dash '-' and not be a reserved tag name.
    descriptor Object The registration descriptor. The descriptor will contain keys for Metadata, View, ViewModel and CSS that are detailed below. At a minimum a composite must register Metadata and View files, but all others are optional. See the registration section above for a sample usage. The value for each key is a plain Javascript object that describes the loading behavior. One of the following keys must be set on the object:
    • promise - specifies the promise instance
    • inline - provides the object inline
    Properties
    Name Type Description
    metadata Object Describes how component Metadata is loaded. The object must contain one of the keys documented above and ultimately resolve to a JSON object.
    view Object Describes how component's View is loaded. The object must contain one of the keys documented above and ultimately resolve to a string, array of DOM nodes, or document fragment.
    css Object Describes how component's CSS is loaded. If specified, the object must contain one of the keys documented above and ultimately resolve to a string if loaded inline or as a Promise.
    viewModel Object Describes how component's ViewModel is loaded. If specified, the object must contain one of the keys documented above. This option is only applicable to composites hosting a Knockout template with a ViewModel and ultimately resolves to a constructor function or object instance. If the initial ViewModel resolves to an object instance, the initialize lifecycle listener will be called. See the initialize documentation for more information.
    parseFunction function(string, string, Object, function(string)) The function that will be called to parse attribute values. Note that this function is only called for non bound attributes. The parseFunction will take the following parameters:
    • {string} value: The value to parse.
    • {string} name: The name of the property.
    • {Object} meta: The metadata object for the property which can include its type, default value, and any extensions that the composite has provided on top of the required metadata.
    • {function(string)} defaultParseFunction: The default parse function for the given attribute type which is used when a custom parse function isn't provided and takes as its parameters the value to parse.
    Source: