4 Work with Oracle JET VComponent-based Web Components
Oracle JET VComponent-based Web Components are reusable pieces of user interface code that you can embed as custom HTML elements. Web Components can contain Oracle JET components, other Web Components, HTML, JavaScript, and CSS. You can create your own Web Component or add one to your page.
Create Web Components
Oracle JET supports a variety of custom Web Component component types. You can create standalone Web Components or you can create sets of Web Components that you intend to be used together and you can then assemble those in a JET Pack, or pack component type. You can enhance JET Packs by creating resource components when you have re-usable libraries of assets that are themselves not specifically UI components. And, if you need to reference third-party code in a standalone component, you can create reference components to define pointers to that code.
Create Standalone Web Components
Use the Oracle JET command-line interface (CLI) to create an Oracle JET Web Component template that you can populate with content. If you’re not using the CLI, you can add the Web Component files and folders manually to your Oracle JET application.
The procedure below lists the high-level steps to create a Web Component.
Before you begin:
- Familiarize yourself with the list of reserved names for a Web Component that are not available for use, see valid custom element name
-
Familiarize yourself with the list of existing Web Component properties, events, and methods, see HTMLElement properties, event listeners, and methods
-
Familiarize yourself with the list of global attributes and events, see Global attributes
To create a Web Component:
Create JET Packs
Create JET Packs to simplify project management for consumers who might pick up a component that is related to one or more components. You may require specific versions of the referenced components for individual JET Packs.
Fundamentally, the JET Pack is a library of related Web Components that does not directly include those assets, but is as an index to a particular versioned stripe of components.
Note:
Note there is one exception to the pack as a reference mechanism for related components. A pack might include one or more RequireJS bundle files which package up optimized forms of the component set into a small number of physical downloads. This, however, is always in addition to the actual components being available as independent entities in Oracle Component Exchange.
The components referenced by the JET Pack are intended to be used together and their usage is restricted by individual component version. Thus the JET Pack that you create will tie very specific versions of each component into a relationship with very specific, fixed versions of the other components in the same set. Thus a JET Pack itself has a "version stripe" which determines the specific components that users import into their apps. Since the version number of individual components may vary, the JET Pack guarantees the consumer associates their app with the version of the pack as a whole, and not with the individual components contained by the pack.
Create Resource Components for JET Packs
Create a resource component when you want to reuse assets across web components that you assemble into JET Packs. The resource component can be reused by multiple JET Packs.
When dealing with complex sets of components you may find that it makes sense to share certain assets between multiple components. In such cases, the components can all be included into a single JET Pack and then a resource component can be added to the pack in order to hold the shared assets. There is no constraint on what can be stored in a pack, typically it may expose shared JavaScript, CSS, and JSON files and images. Note that third party libraries should generally be referenced from a reference component and should not be included into a resource component.
You don't need any tools to create the resource component. You will need to create a folder in a convenient location. This folder will ultimately be zipped to create the distributable resource component. Internally this folder can then hold any content in any structure that you desire.
To create a resource component:
Create Reference Components for Web Components
Create a reference component when you need to obtain a pointer to third-party libraries for use by Web Components.
Create the Reference Component
You don't need any tools to create the reference component. You will need to create a folder in a convenient location where you will define metadata for the reference component in the component.json
file. This folder will ultimately be zipped to create the distributable reference component.
Reference components are generally standalone, so the component.json
file you create must not be contained within a JET Pack.
To create a reference component:
Consume the Reference Component
When your Web Components need access to the third party library defined in one of these reference components, you use the dependency attribute metadata in the component.json
to point to either an explicit version of the reference component or you can specify a semantic range. Here's a simple example of a component that consumes two such reference components at specific versions:
{
"name":"calendar",
"pack":"oj-sample",
"displayName": "JET Calendar",
"description": "FullCalendar wrapper with Accessibility added.",
"version": "1.0.2",
"jetVersion": "^9.0.0",
"dependencies": {
"oj-ref-moment":"2.24.0",
"oj-ref-fullcalendar":"3.9.0"
},
...
When the above component is added to an Oracle JET or Oracle Visual Builder project this dependency information will be used to create the correct RequireJS paths for the third party libraries pointed to be the reference component.
Alternatively, when you install a Web Component that depends on a reference component and you use Oracle JET CLI, the tooling will automatically do an npm install for you so that the libraries are local. However, with the same component used in Oracle Visual Builder, a CDN location must be used and therefore the reference component must exist on the CDN in order to be used in Visual Builder.
Add Web Components to Your Page
To use a VComponent-based Web Component, you import the loader module that provides the entry point to the Web Component in the TSX page where you will use the Web Component.
Those of you who previously built Web Components using the Composite Component
Architecture will be familiar with the use of the loader module to import the Web Component.
VComponent-based Web Components also use this convention of a loader
module
serving as the main entry point to the Web Component. It allows the Oracle JET CLI, Visual
Builder, and the Component Exchange to work with VComponent-based Web Components.
If you import the Web Component into a VDOM app, you can choose between importing the Web Compoent through the use of the component class name or the custom element name for the Web Component. If you import the VComponent-based Web Component into an MVVM JET app, you must use the custom element syntaxt. If importing a component from a JET Pack, you’ll also need to identify the JET Pack in the import statement. The following commented example illustrates the syntax to use for each option.
import { h } from "preact";
// Import standalone components.
// Import as a custom element.
import "doc-hello-world/loader";
// Import as a component class.
import { DocBonjourWorld } from "doc-bonjour-world/loader";
// Import components from a JET Pack
// Import as a custom element.
import "my-component-pack/my-widget-1/loader";
// Import as a component class.
import { MyWidget2 } from "my-component-pack/my-widget-2/loader";
export function Content() {
return (
<div class="oj-web-applayout-max-width oj-web-applayout-content">
{/* Standalone component's custom element */}
<doc-hello-world></doc-hello-world>
{/* Standalone component's component class */}
<DocBonjourWorld />
{/* JET Pack component's custom element */}
<my-component-pack-my-widget-1></my-component-pack-my-widget-1>
{/* JET Pack component's component class */}
<MyWidget2 />
</div>
);
}
The following image shows each example rendering in the content component of the starter template.
![Web Components and Custom Elements Web Components and Custom Elements](img/vdom-webcomp.png)
Generate API Documentation for VComponent-based Web Components
The Oracle JET CLI includes a command (ojet add docgen
) that
you can use to assist with the generation of API documentation for the VComponent-based web
components (VComponent) that you develop.
When you run the command from the root of your project, the JSDoc NPM package
is installed and an apidoc_template
directory is added to the
src
directory of your project. The apidoc_template
directory contains the following files that you can customize with appropriate titles,
subtitles, and footer information, such as copyright information, for the API reference
documentation that you'll subsequently generate for your VComponent(s).
footer.html
header.html
main.html
You write comments in the source file of your VComponent, as in the following example:
import { ExtendGlobalProps, registerCustomElement } from "ojs/ojvcomponent";
. . .
type Props = Readonly<{
message?: string;
address?: string;
}>;
/**
*
* @ojmetadata version "1.0.0"
* @ojmetadata displayName "A user friendly, translatable name of the component"
* @ojmetadata description "<p>Write a description here.</p>
<p>Use HTML tags to put in new paragraphs</p>
<ul>
<li>Bullet list item 1</li>
<li>Bullet list item 2</li></ul>
* <p>Everything before the closing quote is rendered</p>
* "
*
*/
function StandaloneVcompFuncImpl({ address = "Redwood shores",
message = "Hello from standalone-vcomp-func" }: Props) {
return (
<div>
. . .
</div>
);
}
Once you have completed documenting your VComponent’s API in the source
file, you run the build
command for your component or the JET Pack, if
the component is part of a JET pack (ojet build component
component-name
or ojet build component
jet-pack-name
) to generate API reference doc in the appRootDir/web/components/component-or-pack-name/vcomponent-version/docs
directory.
The following /docs
directory listing shows the files that
the Oracle JET CLI generates for a standalone VComponent. You can’t generate the API
documentation by building the Oracle JET app that contains the component. You have to
build the individual VComponent or the JET Pack that contains VComponents. Note too that
you can’t generate API doc for CCA-based web components using the Oracle JET CLI
ojet add docgen
command.
appRootDir/web/components/standalone-vcomp-func/1.0.0/docs
| index.html
| jsDocMd.json
| standalone-vcomp-func.html
| standalone.StandaloneVcompFunc.html
|
+---scripts
| | deprecated.js
| |
| \---prettify
| Apache-License-2.0.txt
| lang-css.js
| prettify.js
|
\---styles
| jsdoc-default.css
| prettify-jsdoc.css
| prettify-tomorrow.css
|
\---images
bookmark.png
linesarrowup.png
linesarrowup_blue.png
linesarrowup_hov.png
linesarrowup_white.png
oracle_logo_sm.png
One final thing to note is that if you want to include an alternative logo and/or CSS
styles to change the appearance of the generated API doc, you update the content in the
following directory
appRootDir/node_modules/@oracle/oraclejet/dist/jsdoc/static/styles/
.
Build Web Components
You can build your Oracle JET Web Component to optimize the files and to generate a minified folder of the component that can be shared with the consumers.
When your Web Component is configured and is ready to be used in different apps, you can build the Web Components of the type: standalone Web Component, JET Pack, and Resource component. Building these components using JET tooling generates a minified content with the optimized component files. This minified version of the component can be easily shared with the consumers for use. For example, you would build the component before publishing it to Oracle Component Exchange. To build the Web Component, use the following command from the root folder of the JET app containing the component:
ojet build component my-web-component-name
For example, if your Web Component name is hello-world
, use the following
command:
ojet build component hello-world
For a JET Pack, specify the pack name.
ojet build component my-pack-name
Note that the building individual components within the pack is not supported, and the whole pack must be built at once.
This command creates a /min
folder in the web/components/hello-world/x.x.x/
directory of your Oracle JET web app, where x.x.x
is the version number
of the component. The /min
folder contains the minified (release)
version of your Web Component files.
Reference component do not require minification or bundling and therefore do not need to be built.
When you build Web Components:
-
If your JET app contains more than one component, you can build the containing JET app to build and optimize all components together. The
build component
command with the component name provides the capability to build a single component. -
You can optionally use the
--release
flag with the build command, but it is not necessary since thebuild
command generates both the debug and minified version of the component. -
You can optionally use the
--optimize=none
flags with thebuild
command when you want to generate compiled output that is more readable and suitable for debugging. The component'sloader.js
file will contain the minified app source, but content readability is improved, as line breaks and white space will be preserved from the original source.
Package Web Components
You can create a sharable zip file archive of the minified Oracle JET Web Component from the Command-Line Interface.
components
subfolder of the app's
/web
. After you build a standalone Web Component or a Resource
component, you use the JET tooling to run the package
command and
create a zip file that contains the Web Component compiled and minified
source.ojet package component my-web-component-name
/jet-composites/<packName>
subfolder contains nested
component folders and the tooling ensures that each component has its own zip
file.ojet package pack my-JET-Pack-name
The package
command packages the component's minified source from
the /web/components
directory and
makes it available as a zip file in a /dist
folder at the root of the
containing app. This zip file will contain both the specified component and a minified
version of that component in a /min
subfolder.
Reference components do not require minification or bundling and therefore do not need to be built. You can archive the Reference component by creating a simple zip archive of the component's folder.
The zip archive of the packaged component is suitable to share, for example, on
Oracle Component Exchange, as described in Publish Web
Components to Oracle Component Exchange. To help organize components that you
want to publish, the JET tooling appends the value of the version
property from the component.json
file for the JET pack and the
individual components to the generated zip in the dist
folder. Assume,
for example, that you have a component pack, my-component-pack
, that
has a version
value of 1.0.0
and the indiviudal
components (my-widget-1
, and so on) within the pack also have version
values of 1.0.0
, then the zip file names for the generated files will
be as follows:
appRootDir/dist/
my-web-component-name_1-0-0.zip
my-component-pack_1-0-0.zip
my-component-pack-my-widget-1_1-0-0.zip
my-component-pack-my-widget-2_1-0-0.zip
my-component-pack-my-widget-3_1-0-0.zip
You can also generate an archive file when you want to upload the component to a CDN. In the CDN case, additional steps are required before you can share the component, as described in Upload and Consume Web Components on a CDN.