Namespace: MetadataTypes

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

QuickNav


MetadataTypes

Version:
  • 7.1.0
Since:
  • 7.0.0
Module:
  • ojmetadata

Module usage

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

Typescript Import Format
//This namespace exports multiple static methods or members. To import 
import * as MetadataTypes from "ojmetadata";

//Now you can access the methods as MetadataTypes.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.

Type Definitions

ComponentMetadata

Properties:
Key Used at Runtime Type Argument Default Description
name yes string The component name must meet the following requirements (based upon the W3C Custom Element spec):
  • The name can include only letters, digits, '-', and '_'.
  • The letters in the name should be all lowercase.
  • The name must start with a lowercase letter.
  • The name cannot be one of the following reserved names:
    • annotation-xml
    • color-profile
    • font-face
    • font-face-src
    • font-face-uri
    • font-face-format
    • font-face-name
    • missing-glyph
Note:
The full name of a component consists of its pack metadata value (if specified) and its name metadata value, appended together with a hyphen separating them:  [pack_value]-[name_value]. This full name corresponds to the Component's custom element tag name. The names of standalone custom JET Web Components (i.e., custom components that are not members of a JET Pack, nor are JET Packs themselves) have the following additional requirements:
  • At least one hyphen is required.
  • The first segment (up to the first hyphen) is a namespace prefix. The namespace prefix 'oj' is reserved for components that are bundled with the JET release.
  • The first hyphen must be followed by at least one character.
version yes string The component version (following semantic version rules). Note that changes to the metadata even for minor updates like updating the jetVersion should result in at least a minor component version change, e.g. 1.0.0 -> 1.0.1.
jetVersion yes string The semantic version of the supported JET version(s). JET Component 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 components with each major release and update the metadata or release a new version that is compatible with the new release changes.
properties yes {[key:string] : MetadataTypes.ComponentMetadataProperties} <optional>
Object containing the properties defined by the component. Each key represents a component property name, and its value is an object with additional metadata for that property. See the Properties table below for details.
methods yes {[key:string] : MetadataTypes.ComponentMetadataMethods} <optional>
Object containing the methods defined by the component. Each key represents a component method name, and its value is an object with additional metadata for that method. See the Method table below for details.
events yes {[key:string] : MetadataTypes.ComponentMetadataEvents} <optional>
Object containing events defined by the component. Each key represents a component event name, and its value is an object with additional metadata for that event. See the Events table below for details.
slots yes {[key:string] : MetadataTypes.ComponentMetadataSlots} <optional>
Object containing the slots defined by the component. Each key represents a component slot name, and its value is an object with additional metadata for that slot. See the Slot table below for details.
Note:
By convention, the slot name for a component's Default slot is the empty string: "".
dependencies no {[key:string] : string} <optional>
Dependency to semantic version mapping for JET Component dependencies. 3rd party libraries should not be included directly in this mapping; instead, define the 3rd party library with a JET Reference Component and include the dependency upon that Reference Component.
Example:
dependencies:  {"oj-foo-composite1": "1.2.0", "oj-foo-composite2": "^2.1.0"}
Note:
  • Always use the full name of the component when declaring a dependency upon it.
  • Dependencies upon JET Custom Components, JET Reference Components, and JET Resource Components may use semantic version range syntax to specify the range of versions that are acceptable to fulfill the dependency requirement.
description no string <optional>
A translatable high-level description for the component. Content should typically consist of one or two sentences.
displayName no string <optional>
A user friendly, translatable name of the component.
extension no object <optional>
Placeholder for Extension metadata. Each section is identified by a key that specifies the downstream tool that will process this metadata.
For example:
Name Type Description
vbdt {string} Indentifies an object with Visual Builder design time metadata

Please consult the documentation for the downstream tool to determine what (if any) extension metadata is supported.
help no string <optional>
Specifies a URL to detailed API documentation for this component.
icon no MetadataTypes.Icon <optional>
One or more optional images for representing the component within a design time environment's component palette.
license no string <optional>
A reference to the license under which use of the component is granted. The value can be:
  • the name of the license text file packaged with the component
  • a URL to a remote license file

If unspecified, downstream consumers can look for a default, case-insensitive license file at the root of the component package.
pack no string <optional>
Identifies the component as belonging to the specified JET Component Pack, or JET Pack.

A JET Pack is a versioned set of JET Components with additional metadata that enables applications to easily install and configure path mappings to the components and shared resources in that JET Pack.

  • If specified, then there should exist a JET Pack whose name is the pack value, and which lists this component's full name in its dependencies metadata.
  • If unspecified, then this is a standalone JET Component that is not a member of any JET Pack.

paths no {cdn: MetadataTypes.Paths} <optional>
Specifies path metadata that is used to generate RequireJS path mappings for loading this component at runtime from a Content Delivery Network, or CDN. It is strongly recommended that CDN urls be specified with https:, as this is required for HTTP/2 and the consuming app may be configured to disallow non-secure urls.
Note:
The information in the paths property is ignored for JET Custom Components that are part of a JET Pack – only the JET Pack itself will be path mapped.
propertyLayout no Array.<MetadataTypes.PropertyLayoutGroup> <optional>
An optional ordered array of one or more PropertyLayoutGroup objects. A propertyLayoutGroup enables a component author to order and shape the groupings of their properties in the design time environment for their component.

Reserved groupings include:

  • "common" - an ordered group of properties that are commonly used for configuring this component, so they should be prominently highlighted and the design time environment should provide extra assistance
  • "data" - an ordered group of properties associated with data binding
Notes
  • Component authors are not required to map all of their properties within their component's propertyLayout object. Design time environments are expected to implement designs that enable access to both mapped and unmapped properties.
  • Nested propertyLayoutGroups enable support for design time environments that expose collapsible sections of related properties – in which case, a section heading is suggested by that propertyLayoutGroup's displayName.
  • If the design time environment does not support nested property groupings, then the assumption is that nested propertyLayoutGroups will be inlined within their common parent propertyLayoutGroup.
Example
A typical Property Inspector layout for the oj-input-text component might look as follows:

 "propertyLayout":
   [
     {
       "propertyGroup": "common",
       "displayName": "Common",
       "items": ["labelHint", "placeholder", "required", "disabled", "readonly"]
     },
     {
       "propertyGroup": "data",
       "displayName": "Data",
       "items": ["value"]
     }
   ]
 
status no Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this component.
styleClasses no Array.<object> <optional>
Optional array of groupings of style class names that are applicable to this component. Each grouping object has the following properties:
Properties
Name Type Description
styleGroup Array.<string> Array of mutually exclusive style class names that belong to this group.
description string A translatable high-level description for this group of styleClasses. Content should typically consist of one or two sentences.
type no "composite" | "core" | "pack" | "reference" | "resource" <optional>
"composite" Identifies the type of this JET Component.

Supported values are:

Value Description
composite Identifies the component as a custom JET Web Component, also known as a "Composite Component". This is the default, if type is unspecified.
core Identifies the component as a JET Web Component that is bundled with a particular version of JET.
pack Identifies the component as a JET Component Pack, or JET Pack. A JET Pack is a versioned set of JET Web Components with additional metadata that enables applications to easily install and configure path mappings to the artifacts in that JET Pack.

The dependencies metadata property is used to specify the versioned components that make up the JET Pack.

reference Identifies the component as a JET Reference Component, which describes a versioned external 3rd party library.

A JET Reference Component can be referenced in the dependencies metadata of a JET Pack, a JET Resource Component, or an individual JET Web Component.

resource Identifes the component as a JET Resource Component, which describes a versioned set of shared resources (such as shared CSS, JavaScript base classes & utility code, icons, translation bundles, etc.)

A JET Resource Component can be referenced in the dependencies metadata of a JET Pack, another JET Resource Component, or an individual JET Web Component.

Metadata for JET Packs, JET Reference Components, and JET Resource Components are described in more detail in the JET Packs topic.

Since:
  • 7.0.0

ComponentMetadataEvents

Properties:
Name Type Argument Description
bubbles boolean <optional>
Indicates whether the event bubbles up through the DOM or not. Defaults to false.
cancelable boolean <optional>
Indicates whether the event is cancelable or not. Defaults to false.
description string <optional>
A translatable high-level description for the event. Content should typically consist of one or two sentences.
detail {[key:string] : MetadataTypes.EventDetailItem} <optional>
Describes the properties available on the event's detail property, which contains data passed when initializing the event. Each key represents an event detail item, and the value is an object with additional metadata for that particular event detail item.
displayName string <optional>
A user friendly, translatable name of the event.
eventGroup string <optional>
Optional group name for this event in a design time environment. Reserved values are:
  • "common" - Applications will commonly want to invoke application logic in response to this event, so it should be prominently highlighted and the design time environment should provide extra assistance.

If an event is mapped to an eventGroup, then members of that event's detail metadata can be also be flagged with that same eventGroup name – this enables the design time environment to map event payload details with any extra assistance afforded by that grouping.
extension object <optional>
Placeholder for Extension metadata. Each section is identified by a key that specifies the downstream tool that will process this metadata.
For example:
Name Type Description
vbdt {string} Indentifies an object with Visual Builder design time metadata

Please consult the documentation for the downstream tool to determine what (if any) extension metadata is supported.
help string <optional>
Specifies a URL to detailed API documentation for this component method. The value can be either an absolute URL, or an anchor string to be appended at the end of the Component-level help value after a hash ('#') character.
status Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this event.
visible boolean <optional>
Specifies whether the method should be visible at design time. True by default.
Since:
  • 7.0.0

ComponentMetadataMethods

Properties:
Key Used at Runtime Type Argument Description
internalName yes string <optional>
An optional ViewModel method name that is different from, but maps to this method.
description no string <optional>
A translatable high-level description for the method. Content should typically consist of one or two sentences.
displayName no string <optional>
A user friendly, translatable name of the method.
extension no object <optional>
Placeholder for Extension metadata. Each section is identified by a key that specifies the downstream tool that will process this metadata.
For example:
Name Type Description
vbdt {string} Indentifies an object with Visual Builder design time metadata

Please consult the documentation for the downstream tool to determine what (if any) extension metadata is supported.
help no string <optional>
Specifies a URL to detailed API documentation for this component method. The value can be either an absolute URL, or an anchor string to be appended at the end of the Component-level help value after a hash ('#') character.
params no Array.<MetadataTypes.MethodParam> <optional>
An array of objects describing the method parameters.
return no string <optional>
The return type of the method, typically following Google Closure Compiler syntax. The metadata also supports TypeScript data types.
status no Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this method.
visible no boolean <optional>
Specifies whether the method should be visible at design time. True by default.
Since:
  • 7.0.0

ComponentMetadataProperties

Properties:
Key Used at Runtime Type Argument Description
enumValues yes Array.<string> <optional>
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.
properties yes {[key:string] : MetadataTypes.ComponentMetadataProperties} <optional>
A nested properties object for complex properties. Each key represents a subproperty name, and its value is an object with additional metadata for that subproperty. 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.
readOnly yes boolean <optional>
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 component. This property only needs to be defined for the top level property, with subproperties inheriting that value.
type yes string The type of the property, following Google Closure Compiler syntax. The runtime 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 yes Array | object | boolean | number | null | string <optional>
An optional default value for a property. This default value must be expressible as valid JSON. For complex properties, the default value can be specified as an object for the top level property, or else at the leaf subproperty levels, but not both.
writeback yes boolean <optional>
Applicable when the application uses two-way data binding to bind an expression to a property. If writeback is true, the JET Web Component can directly update the value of the bound expression after a user interaction like selection. False by default. This property only needs to be defined for the top level property, with subproperties inheriting that value.
description no string <optional>
A translatable high-level description for the property. Content should typically consist of one or two sentences.
displayName no string <optional>
A user friendly, translatable name of the property.
eventGroup no string <optional>
Optional group name for this property's corresponding [property]Changed event in a design time environment. Reserved values are:
  • "common" - Applications will commonly want to react to changes to this property at runtime, so its corresponding property change event should be prominently highlighted and the design time environment should provide extra assistance.
exclusiveMaximum no number | string <optional>
Validation metadata - specifies the exclusive high end of a possible range of values (e.g., "exclusiveMaximum": 1.0 → valid property value is <1.0). 8601 if the value is a string, then it assumed to represent datetime in iso extended date time format. < td>
exclusiveMinimum no number | string <optional>
Validation metadata - specifies the exclusive low end of a possible range of values (e.g., "exclusiveMinimum": 0.0 → valid property value is >0.0). If the value is a string, then it is assumed to represent a dateTime value in the ISO 8601 extended date/time format.
extension no object <optional>
Placeholder for Extension metadata. Each section is identified by a key that specifies the downstream tool that will process this metadata.
For example:
Name Type Description
vbdt {string} Indentifies an object with Visual Builder design time metadata

Please consult the documentation for the downstream tool to determine what (if any) extension metadata is supported.
format no string <optional>
Format hint for a primitive type that can be used for simple validation in the design time environment, or to invoke a specialized customizer control or set of controls. The following set of reserved format keywords are supported:
{number} type formats
Keyword Description
double floating point number with double precision
float floating point number with single precision
int32 signed 32-bit integer
int64 signed 64-bit integer
{string} type formats
Keyword Description
binary sequence of octets
byte sequence of base64-encoded characters
color CSS color value
date date in RFC 3339 format, using the "full-date" profile
date-time date-time in RFC 3339 format, using the "date-time" profile
email Internet email address in RFC 5322 format
time time in RFC 3339 format, using the "full-time" profile
password hint to UIs to obscure input
uri Uniform Resource Identifier in RFC 3986 format
help no string <optional>
Specifies a URL to detailed API documentation for this component property. The value can be either an absolute URL, or an anchor string to be appended at the end of the Component-level help value after a hash ('#') character.
maximum no number | string <optional>
Validation metadata - specifies the inclusive high end of a possible range of values (e.g., "maximum": 1.0 → valid property value is <=1.0). 8601 if the value is a string, then it assumed to represent datetime in iso extended date time format. < td>
minimum no number | string <optional>
Validation metadata - specifies the inclusive low end of a possible range of values (e.g., "minimum": 0.0 → valid property value is >=0.0). If the value is a string, then it is assumed to represent a dateTime value in the ISO 8601 extended date/time format.
pattern no string <optional>
Javascript regular expression that can be used to validate a string value at design time
Example:
To validate a string that matches the format of a U.S. Social Security number, you could specify the following: "pattern": "^\d{3}-?\d{2}-?\d{4}$"
placeholder no string <optional>
User-friendly, translatable hint text that appears in an empty input field at design time.
propertyEditorValues no {[key:string] : MetadataTypes.PropertyEditorValue} <optional>
Design time metadata that lists suggested property values, and optional information about each suggested value. Each key represents a suggested property value – if enumValues runtime metadata is specified, then it is expected that some or all of the keys will match the values in the enumValues array. Conversely, the absence of enumValues runtime metadata indicates that the property can accept values in addition to those suggested by its propertyEditorValues metadata.
propertyGroup no string <optional>
Optional group name for this property in a design time environment. Reserved values include:
  • "common" - This property is commonly used for configuring this component, so it should be prominently highlighted and the design time environment should provide extra assistance.
  • "data" - This property is commonly associated with data binding.

Nested group names can be specified using a period ('.') as a separator. For example, a Charting component can choose to prominently group properties relating to a business chart's Legend with the propertyGroup specified as "common.legend"
Notes
  • Component authors are not required to map all of their properties to a particular propertyGroup. Design time environments are expected to implement designs that enable access to both mapped and unmapped properties.
  • Component authors can optionally specify their preferred layout and ordering of component properties within a propertyGroup by providing additional Component-level propertyLayout metadata.
  • Conversely, if a property is mapped to a particular propertyGroup but is not referenced in the corresponding propertyLayout metadata, then its layout and ordering is undefined.
required no boolean <optional>
Specifies whether the property must have a valid value at run time. False by default. Note that required should not be set to true if a default value has been defined for the property already.
status no Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this property.
translatable no boolean <optional>
True if the value of this property (or its sub-properties, unless explicitly overridden) is eligible to be included when application resources are translated for Internationalization. False by default.
units no string <optional>
User-friendly, translatable text string specifying what units are represented by a property value -- e.g., "pixels".
visible no boolean <optional>
Specifies whether the property should be visible at design time. True by default.
Since:
  • 7.0.0

ComponentMetadataSlots

Properties:
Name Type Argument Description
data {[key:string] : MetadataTypes.SlotDataVariable} <optional>
An object whose keys are the variable names available on $current and whose values are objects that provide additional metadata about the variable. These variables extend what's available on the application context and will be exposed as subproperties on the $current variable and any application provided aliases.
Note:
This property only applies to template slots.
description string <optional>
A translatable high-level description for the slot. Content should typically consist of one or two sentences.
displayName string <optional>
A user friendly, translatable name of the slot.
extension object <optional>
Placeholder for Extension metadata. Each section is identified by a key that specifies the downstream tool that will process this metadata.
For example:
Name Type Description
vbdt {string} Indentifies an object with Visual Builder design time metadata

Please consult the documentation for the downstream tool to determine what (if any) extension metadata is supported.
help string <optional>
Specifies a URL to detailed API documentation for this component method. The value can be either an absolute URL, or an anchor string to be appended at the end of the Component-level help value after a hash ('#') character.
maxItems number <optional>
Specifies the maximum number of elements that the design time environment should allow to be added to this slot. If unspecified, the default is that there is no maximum.
minItems number <optional>
Specifies the minimum number of elements that the design time environment should allow to be added to this slot. If unspecified, the default is 0.
status Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this slot.
visible boolean <optional>
Specifies whether the method should be visible at design time. True by default.
Since:
  • 7.0.0

EventDetailItem

Properties:
Name Type Argument Description
description string <optional>
An optional, translatable description of this event detail item. Content should typically consist of one or two sentences.
type string The type of this event detail item's value, typically following Google Closure Compiler syntax. The metadata also supports TypeScript data types.
status Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this event detail item.
eventGroup string <optional>
Optional flag that maps this event detail item for special consideration in a design time environment -- the value should match the eventGroup value of the containing Event metadata element.
Since:
  • 7.1.0

Icon

Properties:
Name Type Argument Description
iconPath string <optional>
A relative path to an icon that represents the default (enabled) state.
selectedIconPath string <optional>
A relative path to the icon that represents the selected state.
hoverIconPath string <optional>
A relative path to the icon that represents the hover state.
Since:
  • 7.1.0

MethodParam

Properties:
Name Type Argument Description
description string <optional>
A translatable high-level description for the parameter. Content should typically consist of one or two sentences.
name string The name of the parameter.
status Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this parameter.
type string The type of the parameter, typically following Google Closure Compiler syntax. The metadata also supports TypeScript data types.
Since:
  • 7.1.0

Paths

Properties:
Name Type Argument Description
min string <optional>
Specifies the location of the optimized form of the artifact.
debug string <optional>
Specifies the location of the debug form of the artifact.
Since:
  • 7.1.0

PropertyEditorValue

Properties:
Name Type Argument Description
description string <optional>
A translatable high-level description for the value. Content should typically consist of one or two sentences.
displayName string <optional>
A displayable, translatable label for the value.
icon MetadataTypes.Icon <optional>
One or more optional images for representing the value.
Since:
  • 7.1.0

PropertyLayoutGroup

Properties:
Name Type Argument Description
propertyGroup string The property group name associated with this propertyLayoutGroup. Reserved values include:
  • "common" - an ordered group of properties that are commonly used for configuring this component, so they should be prominently highlighted and the design time environment should provide extra assistance
  • "data" - an ordered group of properties associated with data binding
displayName string <optional>
An optional user friendly, translatable name for this propertyLayoutGroup.
items Array<string | MetadataTypes.PropertyLayoutGroup> An ordered array of one or more items in this propertyLayoutGroup:
  • Items of type string represent the names of component properties or sub-properties.
  • Items of type PropertyLayoutGroup represent a nested layout structure.
Since:
  • 7.1.0

SlotDataVariable

Properties:
Name Type Argument Description
description string <optional>
A translatable high-level description for the slot data variable. Content should typically consist of one or two sentences.
status Array.<MetadataTypes.Status> <optional>
Optional array of status objects that are applicable to this slot data variable.
type string The slot data variable type, typically following Google Closure Compiler syntax. The metadata also supports TypeScript data types.
Since:
  • 7.1.0

Status

Properties:
Name Type Argument Description
type "deprecated" <optional>
The status type.
since string <optional>
The version (following semantic version rules) when the specified status was first established.
description string <optional>
A translatable high-level description for the specified status. For deprecated elements, this should ideally direct developers to an alternative solution. Content should typically consist of one or two sentences.
target "propertyType" | "parameterType" | "returnType" <optional>
The target of the specified status. If no target is provided, then the status applies to the current element.
value Array.<string> <optional>
Array of targetted values of the specified status (only applies if a 'target' property is also specified). For example, if 'type' is set to "deprecated" and 'target' is set to "propertyType", then 'value' is used to specify the particular types of a property's union type that have been deprecated.
Since:
  • 7.1.0