Namespace: Composite

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

QuickNav


Composite

Version:
  • 7.1.0
Since:
  • 2.0.0
Module:
  • ojcomposite

Module usage

See JET Module Loading for an overview of module usage within JET.

Javascript Import Format
define(['ojs/ojcomposite'], function(Composite) {
 // Application should call API on Composite 
})
Typescript Import Format
//This namespace exports multiple static methods or members. To import 
import * as Composite from "ojcomposite";

//Now you can access the methods as Composite.methodName and so on

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.

JET allows developers to create custom components which can be composites of other components, HTML, JavaScript, or CSS. These reusable pieces of UI can be embedded as custom HTML elements and are registered using the Composite APIs described below. These custom components will be referred to as "composites" throughout the rest of this doc. Please see the JET Custom Components concept doc for more information on how to create and use these custom components.

Methods

(static) getComponentMetadata(name) → {(MetadataTypes.ComponentMetadata|null)}

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Returns the composite metadata with the given name or null if the composite has not been registered.
Parameters:
Name Type Description
name string The component name, which should contain a dash '-' and not be a reserved tag name.
Since:
  • 5.0.0
Returns:
Type
(MetadataTypes.ComponentMetadata|null)

(static) register<P extends Composite.PropertiesType= PropertiesType>(name: string, descriptor: { metadata: MetadataTypes.ComponentMetadata; view: string; viewModel?: {new(context: Composite.ViewModelContext<P>): ViewModel<P>}; parseFunction?: ((value: string, name: string, meta: MetadataTypes.ComponentMetadataProperties, defaultParseFunction?: (value: string) => any) => any);}): void

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. The composite resources should be mapped directly to each descriptor key. See the registration section above for a sample usage.
Properties
Name Type Argument Description
metadata Object A JSON formatted object describing the composite APIs. See the metadata documentation for more info.
view string A string representing the HTML that will be used for the composite.
viewModel function(Composite.ViewModelContext):void <optional>
This option is only applicable to composites hosting a Knockout template with a ViewModel and ultimately resolves to a constructor function.
parseFunction function(string, string, Object, function(string):any):any <optional>
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):any} 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 parameter the value to parse.
Returns:
Type
void

Type Definitions

PropertiesType

If you are writing your composite in TypeScript and wish to have stricter type checking done for your composite properties, you can optionally define a type in your ViewModel which lists all component properties, their types, and parameterize your composite ViewModel and methods based that type.

For example, if you are writing a composite with two properties customTitle and help,


// Create a type representing all the properties of your composite
type ExampleComponentProperties = {
  'customTitle': string,
  'help' : {
     definition: string
   }
}
// Parameterize your ViewModel and methods on this type
class ExampleComponentModel implements ViewModel<ExampleComponentProperties>{
  activated = (context: ViewModelContext<ExampleComponentProperties>) => {
    let title = context.properties.customTitle; //guranteed to be string
    let helpDef = context.properties.help.definition; //guranteed to be string
  }
}
If no type is provided, this default type will be used and you need not parameterize your ViewModel.

Signature:

{[key:string] : any;}

PropertyChangedContext<P extends Composite.PropertiesType= PropertiesType>

Properties:
Name Type Argument Description
property keyof P The property that changed.
value P[keyof P] The current value of the property that changed.
previousValue P[keyof P] The previous value of the property that changed.
updatedFrom "external" | "internal" Indicates how the property update occurred. The value will be "external" if the update occured from the application, e.g. the element's property setter, setAttribute, or a data binding update. The value will be "internal" if the update occurred from the component, e.g. after user interaction with a text field or selection.
subproperty Object <optional>
An object holding information about the subproperty that changed.
Properties
Name Type Description
path string The subproperty path that changed, starting from the top level property with subproperties delimited by '.'.
value any The current value of the subproperty that changed.
previousValue any The previous value of the subproperty that changed.

ViewModel<P extends Composite.PropertiesType= PropertiesType>

Properties:
Name Type Argument Description
activated ((context: Composite.ViewModelContext<P>) => Promise<any> | void) <optional>
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.
connected ((context: Composite.ViewModelContext<P>) => void) <optional>
Invoked after the View is first inserted into the DOM and then each time the composite is reconnected to the DOM after being disconnected. Note that if the composite needs to add/remove event listeners, we recommend using this and the disconnected methods.
bindingsApplied ((context: Composite.ViewModelContext<P>) => void) <optional>
Invoked after the bindings are applied on this View.
propertyChanged ((context: Composite.PropertyChangedContext<P>) => void) <optional>
Invoked when properties are updated and before the [property]Changed event is fired.
disconnected ((element: Element) => void) <optional>
Invoked when this composite component is disconnected from the DOM.

ViewModelContext<P extends Composite.PropertiesType= PropertiesType>

Properties:
Name Type Description
element Element The composite element.
properties P A map of the composite component's current properties and values.
slotCounts {[key: string]: number} 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.
uniqueId string The ID of the composite component if specified. Otherwise, it is the same as unique.