JET Metadata
Oracle® JavaScript Extension Toolkit (JET)
18.0.0
G12199-01
Overview
Metadata for a JET Web Component consists of a JSON formatted object which defines the properties, methods, slots, dynamic slots, and events fired by that component. The names of the JET Web Component's properties, events, and methods should avoid collision with the existing HTMLElement properties, events, and methods. Additionally, the JET Web Component should not re-define any global attributes or events. Please refer to the HTML Living Standard for the latest guidance.
The Metadata JSON object should have the following required properties: "name", "version", "jetVersion" and the following optional properties: "description", "dependencies", "icon", "displayName", "properties", "methods", "events", "slots", and "dynamicSlots". See the tables below for descriptions of these properties. The Metadata can be extended by appending any extra information in an "extension" field except at the first level of the "properties", "methods", "events", "slots" or "dynamicSlots" objects. Any metadata in an extension field will be ignored.
Keys defined in the "properties" top level object should map to the JET Web Component's properties following the same naming convention described in the Property-to-Attribute mapping section. Non expression bound JET Web 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 Web 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.
Note that the JET release includes a 'metadata/components'
directory with metadata for each JET Web Component that is bundled
as part of that release. JET Web Components that are bundled as part of a JET release are also referred to as JET Core Components. The
JSON for each JET Core Component uses the exact same format as the metadata packaged with JET Custom Components (also known as
composite components), such that design time tools and property editors can leverage a common metadata format
when integrating any JET Web Component into their environments.
Metadata Structure
Top Level Keys
- 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
- 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 lowercase letter.
- By convention, the slot name for a component's Default slot is the empty string:
""
. - Slots should follow a logical ordering representing their preferred presentation in a design-time environment:
- The Default slot should always be first.
- Slots that are rendered in specific locations should be ordered from top-start to bottom-end.
- Slots that are more typically used should be ordered ahead of slots that are used in more specialized use cases.
- 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.
- Strings in the
implements
array may not contain any hyphen characters. - the name of the license text file packaged with the component
- a URL to a remote license file
- If specified, then there should exist a JET Pack whose name is the
pack
value, and which lists this component's full name in itsdependencies
metadata. - If unspecified, then this is a standalone JET Component that is not a member of any JET Pack.
"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- 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.
- Since:
- 7.0.0
Properties:
Key | Used at Runtime | Type | Argument | Default | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name |
no |
string | The component name must meet the following requirements (based upon the W3C Custom Element spec):
Note:The full name of a component consists of itspack 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:
|
||||||||||||||
version |
no |
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 patch component version change, e.g. 1.0.0 -> 1.0.1. | ||||||||||||||
jetVersion |
no |
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 Methods 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 Slots table below for details.
Note: |
|||||||||||||
dynamicSlots |
yes |
{[key:string] : MetadataTypes.ComponentMetadataSlots} |
<optional> |
Optional object containing information about dynamic slots supported by the component. (Dynamic slot names are specified by the application,
and are not known by the component until runtime.) Each key represents a dynamic slot definition, and its value is an object
with additional metadata describing a dynamic template slot.
A component property whose value is a dynamic template slot name can specify a dynamic slot definition key in its corresponding Note:By convention, an empty object is sufficient for specifying that the component supports dynamic slots. Conversely, if thedynamicSlots metadata element is unspecified, then the component does not support dynamic slots.
|
|||||||||||||
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:
Note: |
|||||||||||||
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:
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. The value is either an absolute URL or it is relative to a base URL
as specified by the help metadata property of the containing JET Pack.
|
|||||||||||||
icon |
no |
MetadataTypes.Icon |
<optional> |
One or more optional images for representing the component within a design time environment's component palette. | |||||||||||||
implements |
no |
Array.<string> |
<optional> |
An optional array of strings, where each string represents a "duck type" or interface contract that this JET Web Component will fulfill.
NoteExampleThe 'oj-foo' JET Pack includes a number of components that implement aFooContentElement TypeScript interface.
This interface describes the contract that the oj-foo-dashboard container requires of its children in order to perform layout.
An oj-foo-newsfeed component can advertise its adherence to the FooContentElement contract through its metadata:
|
|||||||||||||
license |
no |
string |
<optional> |
A reference to the license under which use of the component is granted. The value can be:
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. |
|||||||||||||
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 thepaths property is ignored for JET Custom Components that are part of a JET Pack – only the JET Pack itself will be path mapped.
|
|||||||||||||
preferredParent |
no |
Array.<MetadataTypes.PreferredParent> |
<optional> |
An optional array of one or more PreferredParent objects, specifying the container preferences for this custom element. | |||||||||||||
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: NotesExampleA typical Property Inspector layout for the oj-input-text component might look as follows:
|
|||||||||||||
since |
no |
string |
<optional> |
The JET version (or, for custom components, the JET Pack version) in which this component was first introduced. The version string must follow semantic version rules. Only production version numbers should be used. | |||||||||||||
status |
no |
Array.<MetadataTypes.Status> |
<optional> |
Optional array of status objects that are applicable to this component. | |||||||||||||
styleClasses |
no |
Array<MetadataTypes.StyleClassItem> |
<optional> |
Optional array of style classes, style class sets, and style class templates that are applicable to this component. | |||||||||||||
styleVariables |
no |
Array.<MetadataTypes.StyleVariable> |
<optional> |
Optional array of CSS variables that are applicable to this component. | |||||||||||||
subcomponentType |
no |
"data" | "patternImpl" | "packPrivate" |
<optional> |
Identifies this JET Component as a sub-component (in other words, a component that is expected to function
within a containing parent component). The value of this metadata property specifies the role of this
sub-component within its container.
Supported values are:
|
|||||||||||||
type |
no |
"composite" | "core" | "pack" | "reference" | "resource" |
<optional> |
"composite" | Identifies the type of this JET Component.
Supported values are:
Metadata for JET Packs, JET Reference Components, and JET Resource Components are described in more detail in the JET Packs topic. |
Property Keys
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
[property name] |
Object containing the following properties:
Properties:
|
Method Keys
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
[method name] |
Object containing the following properties:
Properties:
|
Event Keys
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
[event name] |
Object containing the following properties:
Properties:
|
Slot Keys
Key | Value | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
[slot name] |
Object containing the following properties:
Properties:
|
Note:
- By convention, the slot name for a component's Default slot is the empty string:
""
. - Slots should follow a logical ordering representing their preferred presentation in a design-time environment:
- The Default slot should always be first.
- Slots that are rendered in specific locations should be ordered from top-start to bottom-end.
- Slots that are more typically used should be ordered ahead of slots that are used in more specialized use cases.
Dynamic Slot Keys
Key | Value | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
[dynamic slot definition key] |
Object containing the following dynamic template slot properties:
Properties:
|
Note:
An empty object is sufficient for specifying that the component supports dynamic slots. Conversely, if thedynamicSlots
metadata element is unspecified, then the component does not support dynamic slots.