Create an Oracle JET web component

Introduction

A web component is a reusable piece of user interface that you can embed as a custom HTML element in your web app. Web components can contain Oracle JavaScript Extension Toolkit (Oracle JET) components, other web components, HTML, JavaScript, TypeScript, and Cascading Style Sheets (CSS). You use Oracle JET tooling to create the web component. You can use an Oracle JET starter template to generate the HTML and JavaScript or TypeScript files that you modify to add the web component.

Objectives

In this tutorial, you will create and configure an Oracle JET web component in a web app that uses the navdrawer starter template. You also learn how to modify the web component files to add a Form Layout component with four input text fields.

Prerequisites

A development environment set up to create Oracle JET web apps that includes an installation of Node.js
Access to the Oracle JET Developer Cookbook

Task 1: Create an Oracle JET Web App

Use the navdrawer starter template and Oracle JET tooling to create the app folder where you will create the Oracle JET web component.

Open a terminal window, and create a web app named JET_Web_Component_Application with the navdrawer starter template.
```
npx @oracle/ojet-cli create JET_Web_Component_Application --template=navdrawer --typescript
```
Change to the JET_Web_Component_Application directory and run the app.
```
npx ojet serve
```
The browser displays the navdrawer starter template with the default content visible in the Dashboard tab of your web app.

Description of the illustration dashboard_default_message.png
Close the browser window or tab that displays your running web app.

Task 2: Create an Oracle JET Web Component

In the terminal window, press Ctrl+C, and if prompted, enter y to exit the Oracle JET tooling batch job.
In the JET_Web_Component_Application directory, create the demo-update-item web component.
```
npx ojet create component demo-update-item
```
Oracle JET tooling creates the demo-update-item web component in the JET_Web_Component_Application/src/ts/jet-composites directory. The web component name contains a hyphen and is in lowercase, as required by the W3C naming conventions for web components.

Task 3: Add the Web Component to Your App

To use the web component in your web app, add the web component loader module to the TypeScript file of your web app and add the web component element to the HTML file of your web app.

Navigate to the JET_Web_Component_Application/src/ts/viewModels directory and open the dashboard.ts file in an editor.

At the top of the dashboard.ts file, import the web component loader module.

import * as AccUtils from "../accUtils";
import "demo-update-item/loader";

Save the dashboard.ts file.
Navigate to the JET_Web_Component_Application/src/ts/views directory and open the dashboard.html file in an editor.

Replace the content of the div element in the Dashboard Content Area with the demo-update-item element.

<div class="oj-hybrid-padding">
   <h1>Dashboard Content Area</h1>
      <div>
         <demo-update-item></demo-update-item>
      </div>
</div>

Edit the h1 element to display Update Item Details as the title, and add the oj-header-border class.

<div class="oj-hybrid-padding">
   <h1 class="oj-header-border">Update Item Details</h1>
      <div>
         <demo-update-item></demo-update-item>
      </div>
</div>

Add a div with an oj-panel class around the content you have modified, in order to display a selection border for the web component.

<div class="oj-hybrid-padding">
   <div class="oj-panel oj-sm-margin-2x demo-mypanel">
      <h1 class="oj-header-border">Update Item Details</h1>
      <div>
         <demo-update-item></demo-update-item>
      </div>
   </div>
</div>

Save the dashboard.html file.
In the terminal window, change to the JET_Web_Component_Application directory and run the app.
```
npx ojet serve
```
The browser displays the Update Item Details panel of your web component in the Dashboard tab of your web app. The panel displays a border and a default message.

Description of the illustration update_item_details_message.png
Leave the terminal window and the browser window or tab that displays your web app open.

The npx ojet serve command allows you to make changes to your app code that are immediately reflected in the browser.

Task 4: Add a Form to the Web Component

Configure your web component to display a form with four input text fields. Modify the web component TypeScript and HTML files to add a Form Layout component.

Open the Oracle JET Cookbook and navigate to the Cookbook Home page, and then click Forms in the menu bar and select the Form Layout component. Read about how to manage the layout of labels and fields in a form.
Navigate to the JET_Web_Component_Application/src/ts/jet-composites/demo-update-item directory and open the demo-update-item-view.html file in an editor.

Replace the content of the demo-update-item-view.html file with the Oracle JET Form Layout component and four Oracle JET Input Text fields to display in the Update Item Details panel.

<oj-form-layout id="form-container" label-edge="[[labelEdge]]">
   <oj-input-text value="ID number" label-hint="Item ID"></oj-input-text>
   <oj-input-text value="Name" label-hint="Item Name"></oj-input-text>
   <oj-input-text value="Price" label-hint="Item Price"></oj-input-text>
   <oj-input-text value="Description" label-hint="Item Description"></oj-input-text>
</oj-form-layout>

Save the demo-update-item-view.html file.
In the JET_Web_Component_Application/src/ts/jet-composites/demo-update-item directory, open the demo-update-item-viewModel.ts file in an editor.

In the ViewModel class, add a Knockout observable isSmall that uses the ResponsiveKnockoutUtils utility with the createMediaQueryObservable() method to create an observable based on the screen width.

export default class ViewModel implements Composite.ViewModel<Composite.PropertiesType> {
   busyResolve: (() => void);      
   . . .
   res: { [key: string]: string };
   smallQuery = ResponsiveUtils.getFrameworkQuery( ResponsiveUtils.FRAMEWORK_QUERY_KEY.SM_ONLY);
   isSmall: ko.Observable = ResponsiveKnockoutUtils.createMediaQueryObservable(this.smallQuery!);

Also add a Knockout computed observable that returns top if the screen size is small and start otherwise.

. . .
isSmall: ko.Observable = ResponsiveKnockoutUtils.createMediaQueryObservable(this.smallQuery!);
   
// For small screens: labels on top
// For medium or bigger: labels at the start
labelEdge: ko.Computed = ko.computed(() => {
  return this.isSmall() ? "top" : "start";
   
}, this);
. . . 

At the top of the demo-update-item-viewModel.ts file, import the following modules that are needed to execute the code that you added in the previous steps.

"use strict";
. . .
import "ojs/ojknockout";
import * as ResponsiveUtils from "ojs/ojresponsiveutils";
import * as ResponsiveKnockoutUtils from "ojs/ojresponsiveknockoututils";
import "ojs/ojformlayout";
import "ojs/ojinputtext";
. . . 

Save the demo-update-item-viewModel.ts file. Your demo-update-item-viewModel.ts code should look similar to demo-update-item-viewmodel-ts.txt.
Return to the browser to view the changes in your web app.

The browser displays the web component with four input text fields in the Dashboard tab of your web app.

Description of the illustration update_item_details_formlayout.png
Close the browser window or tab that displays your running web app.
In the terminal window, press Ctrl+C, and if prompted, enter y to exit the Oracle JET tooling batch job.

Next Step

To proceed to the next tutorial in this learning path, click here.

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

Title and Copyright Information

Create an Oracle JET web component

F11864-07

February 2024