name |
no |
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 |
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:
- 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.
|
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 dynamicSlotDef
metadata in order to map the dynamic template slot name to the additional metadata in the dynamicSlots object.
Note:
By convention, an empty object is sufficient for specifying that the component supports dynamic slots.
Conversely, if the dynamicSlots 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:
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 |
{Object} |
Identifies 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. 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.
Note
- Strings in the
implements array may not contain any hyphen characters.
Example
The 'oj-foo' JET Pack includes a number of components that implement a FooContentElement 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:
{
"name": "newsfeed",
"version": "1.0.0",
"jetVersion": "^10.0.0",
"pack": "oj-foo"
"displayName": "Foo News Feed",
"type": "composite",
"implements": ["FooContentElement"],
...
}
|
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.
|
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:
"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"]
}
]
|
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>
|
Array.<MetadataTypes.StyleGroup>
|
<optional>
|
|
Optional array of style classes, style class sets, and style class templates that are applicable to this component.
- Deprecated:
-
| Since |
Value |
Description |
8.0.0 |
Array<MetadataTypes.StyleGroup> |
The MetadataTypes.StyleGroup type is deprecated. Use instances of the MetadataTypes.StyleClass, MetadataTypes.StyleSet, and MetadataTypes.StyleTemplate types for the content of the styleClasses array. |
|
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:
| Value |
Description |
| data |
Identifies this sub-component as providing data at runtime in the form of property values within a corresponding template slot.
|
| patternImpl |
Identifies this sub-component as providing the implementation for a broader Visual Builder pattern.
|
| packPrivate |
Identifies this sub-component as a private base class implementation that is extended by other public Web Components in a JET Pack.
|
|
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.
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.
|