Namespace: Composite

Methods

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

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>): Composite.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, and ViewModel 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 along with their types, and parameterize your composite ViewModel and methods based on 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 based 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>

Context object passed to the propertyChanged callback registered with the Composite's ViewModel. This context object has the following properties:

Property	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 optional property whose value is an object holding information about the subproperty that changed: Property 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.

Signature:

{ [K in keyof P]-?: { property: K; value: P[K]; previousValue: P[K]; updatedFrom: 'external' | 'internal'; subproperty?: { path: string; previousValue: any; value: any; }; } }[keyof P]

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.
bindingsApplied	((context: Composite.ViewModelContext<P>) => void)	<optional>	Invoked after the bindings are applied on this View.
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.
disconnected	((element: Element) => void)	<optional>	Invoked when this composite component is disconnected from the DOM.
propertyChanged	((context: Composite.PropertyChangedContext<P>) => void)	<optional>	Invoked when properties are updated and before the [property]Changed event is fired.

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.