Add components to an Oracle JET virtual DOM app

Introduction

This tutorial shows you how to add Oracle JavaScript Extension Toolkit (Oracle JET) components to the Content component in the basic starter template of your Oracle JET virtual DOM app.

Oracle JET is a development toolkit that you use to build client-side virtual DOM apps. To use Oracle JET components in your virtual DOM app, use the Oracle JET Cookbook to locate the component samples that illustrate the specific functionality you want to add to your app. Although not optimized for JSX (the tag syntax used by virtual DOM apps), the Cookbook shows you the Oracle JET components and TypeScript code that you can use to infer the JSX equivalent in your Oracle JET virtual DOM app by, for example, showing the import statement that you need to use to include the component in your virtual DOM app.

Objectives

In this tutorial, you will learn how to use the Oracle JET Cookbook to add Oracle JET Select Single and Chart components to the Content component of your virtual DOM app. You will also learn how to connect these two components to add interactivity between them.

Prerequisites

Task 1: Add Style Classes

It is good practice to place styles that you want to apply to components in a separate CSS file rather than use the inline style attribute demonstrated in the following example:

<oj-select-single
  id="basicSelect"
  style="max-width:20em"
  data="{chartTypesDP}"
></oj-select-single>

Before we add the Select Single and Chart components to our page, we’ll create style classes in our app’s CSS file that the components can then reference.

  1. Navigate to the JET-Virtual-DOM-app/src/styles directory and open the app.css file in an editor.

  2. At the end of the app.css file, add the following style classes that will determine style properties for the Select Single and Chart components.

    .selectSingleStyle {
  max-width: 20em;
}

.chartStyle {
  max-width: 500px;
  width: 100%;
  height: 350px;
}

    Later in this tutorial, the Select Single and Chart components reference these styles using the component’s class attribute:

    <oj-select-single id="basicSelect" . . . class="selectSingleStyle"
  >. . .
  <oj-chart id="barChart" . . . class="chartStyle"
    >. . .</oj-chart
  ></oj-select-single
>

Task 2: Add a Select Single Component

  1. Navigate to the JET-Virtual-DOM-app/src/components/content directory and open the index.tsx file in an editor.

  2. At the top of the index.tsx file, import the Oracle JET modules for the MutableArrayDataProvider, the Label and Select Single components, plus the type definition for the Select Single component.

    import { h } from "preact";
import "ojs/ojlabel";
import "ojs/ojselectsingle";
import { ojSelectSingle } from "ojs/ojselectsingle";
import MutableArrayDataProvider = require("ojs/ojmutablearraydataprovider");

  3. Within the HTML div element of the Content() function, add an HTML h1 element to display the header Product Information.

    . . .
import MutableArrayDataProvider = require("ojs/ojmutablearraydataprovider");

export function Content() {
   return (
      <div class="oj-web-applayout-max-width oj-web-applayout-content">
         <h1>Product Information</h1>
      </div>
   );
}

  4. Within the HTML div element of the Content() function, add another div element and, within this newer div element, add an oj-label element and an oj-select-single element. Also add an id attribute with a value of itemDetailsContainer to the new div element.

    . . .
<div class="oj-web-applayout-max-width oj-web-applayout-content">
<h1>Product Information</h1>
<div id="itemDetailsContainer">
 <oj-label for="basicSelect">Select Chart:</oj-label>
 <oj-select-single
      id="basicSelect"
      value="pie"
      class="selectSingleStyle"
      data={chartTypesDP}
   ></oj-select-single>
 </div>
 </div>

  5. Before the Content() function, add a type alias for the chart types (ChartType) and a chart type data array (chartTypesData). Also before the Content() function, add an instance of the MutableArrayDataProvider class (chartTypesDP) to allow binding of the chart type data by the Select Single component.

    . . .
import MutableArrayDataProvider = require("ojs/ojmutablearraydataprovider");

type ChartType = {
   id: number;
   value: string;
   label: string;
};

const chartTypeData = [
   { value: "bar", label: "Bar" },
   { value: "pie", label: "Pie" }
];

const chartTypesDP: MutableArrayDataProvider<ChartType["value"], ChartType>
   = new MutableArrayDataProvider(chartTypeData, { keyAttributes: "value" });

export function Content() {
. . .

  6. Save the index.tsx file.

    Your index.tsx code should look similar to add-select-single-index-tsx.txt.

  7. Open a terminal window, change to the JET-Virtual-DOM-app directory, and run the app.

    npx ojet serve

    The browser displays the basic starter template with the Select Single component visible in your virtual DOM app.

    Image showing a JET virtual DOM app that renders a Select Single component with a dropdown list. Pie and Bar are the dropdown list options.

  8. Leave the terminal window and the browser that displays your virtual DOM app open.

    The Oracle JET command-line interface’s serve command lets you make changes to the code in the JET-Virtual-DOM-app/src directory that are immediately reflected in the browser. One exception is that if you add or delete a file, you need to run npx @oracle/ojet-cli serve again to see the change reflected in the browser. The serve command builds and serves the content of the JET-Virtual-DOM-app/src directory to the JET-Virtual-DOM-app/web directory. Do not make changes to the code in the JET-Virtual-DOM-app/web directory because you will overwrite these changes the next time that you run the npx @oracle/ojet-cli serve command.

Task 3: Add a Chart Component

  1. In the open index.tsx file from the JET-Virtual-DOM-app/src/components/content directory, import the module and the type definitions for the Oracle JET Chart component.

    import { h } from "preact";
import "ojs/ojlabel";
import "ojs/ojselectsingle";
import { ojSelectSingle } from "ojs/ojselectsingle";
import MutableArrayDataProvider = require("ojs/ojmutablearraydataprovider");
import "ojs/ojchart";
import { ojChart } from "ojs/ojchart";
. . .

  2. Before the Content() function, add a type alias for the chart data (ChartItem), a chart data array (chartData), and an instance of the MutableArrayDataProvider class (chartDataProvider) to reference the data that the Chart component renders.

    . . .

type ChartItem = {
   id: number;
   series: string;
   group: string;
   value: number;
   };

const chartData  = [
   { "id": 0, "series": "Baseball", "group": "Group A", "value": 42 },
   { "id": 1, "series": "Baseball", "group": "Group B", "value": 34 },
   { "id": 2, "series": "Bicycling", "group": "Group A", "value": 55 },
   { "id": 3, "series": "Bicycling", "group": "Group B", "value": 30 },
   { "id": 4, "series": "Skiing", "group": "Group A", "value": 36 },
   { "id": 5, "series": "Skiing", "group": "Group B", "value": 50 },
   { "id": 6, "series": "Soccer", "group": "Group A", "value": 22 },
   { "id": 7, "series": "Soccer", "group": "Group B", "value": 46 }
]

const chartDataProvider: MutableArrayDataProvider<ChartItem["id"], ChartItem> =
new MutableArrayDataProvider(chartData, { keyAttributes: "id" });

export function Content() {
. . .

  3. Within the HTML div element of the Content() function that has an id attribute value of itemDetailsContainer, add the oj-chart custom HTML element below the oj-select-single custom HTML element such that the two elements appear inside the itemDetailsContainer HTML div element.

    . . .
<div class="oj-web-applayout-max-width oj-web-applayout-content">
<h1>Product Information</h1>
<div id="itemDetailsContainer">
 <oj-label for="basicSelect">Select Chart:</oj-label>
 <oj-select-single . . .></oj-select-single>
   <oj-chart id="barChart" type="bar" data={chartDataProvider} animationOnDisplay="auto"
            animationOnDataChange="auto" hoverBehavior="dim" class="chartStyle"></oj-chart>
 </div>
</div>

  4. Within the oj-chart custom HTML element, add an HTML template element with a slot attribute to render each item in the chart.

    . . .
<div class="oj-web-applayout-max-width oj-web-applayout-content">
<h1>Product Information</h1>
<div id="itemDetailsContainer">
 <oj-label for="basicSelect">Select Chart:</oj-label>
 <oj-select-single . . .></oj-select-single>
  <oj-chart . . .>
      <template slot="itemTemplate" render={chartItem}></template>
   </oj-chart>
 </div>
</div>

  5. Before the return statement in the Content() function, add the following code to render the chart item data.

    . . .
export function Content() {

const chartItem = (
   item: ojChart.ItemTemplateContext<ChartItem["id"], ChartItem>
) => {
   return (
      <oj-chart-item
         value={item.data.value}
         groupId={[item.data.group]}
         seriesId={item.data.series}></oj-chart-item>
   );
};

return (

  6. Save the index.tsx file.

    Your index.tsx file should look similar to final-chart-index-tsx.txt.

  7. Return to the browser to view the changes in your virtual DOM app.

    The browser displays the basic starter template with the Chart component rendering a bar chart in your virtual DOM app.

    Image showing a Chart component

    Notice that the virtual DOM app displays only the bar chart format for each Select Chart dropdown list option. You must add a dependency between the two components so that the Chart component responds to the selection event in the Select Single component.

  8. Leave the terminal window and the browser that displays your virtual DOM app open.

Task 4: Connect the Two Components

  1. In the open index.tsx file from the JET-Virtual-DOM-app/src/components/content directory, import the useState and useCallback hooks and ComponentProps from Preact.

    import { h, ComponentProps } from "preact";
import { useState, useCallback } from "preact/hooks";
. . .

  2. Before the Content() function, add a type alias for the chart properties (ChartProps).

    type ChartProps = ComponentProps<"oj-chart">;

export function Content() {
. . .

  3. Within the Content() function, add code to set an initial value of bar for the Select Single component using Preact’s useState hook and include Preact’s useCallback hook to pass newly-selected chart types back to the useState hook.

    export function Content() {
   const [val, setVal] = useState("pie" as ChartProps["type"]);

   const valChangeHandler = useCallback(
      (event: ojSelectSingle.valueChanged<ChartType["value"], ChartType>) => {
         setVal(event.detail.value as ChartProps["type"]);
      },
      [val, setVal]
   );
. . .

  4. Within the itemDetailsContainer HTML div element of the Content() function, update the oj-select-single and oj-chart custom attribute values to reference the current selected value (val) and an event handler (valChangeHandler) that is called when a user selects a new chart type.

    <div id="itemDetailsContainer">
   . . .
   <oj-select-single
      id="basicSelect"
      . . .
      value={val}
      onvalueChanged={valChangeHandler}
   ></oj-select-single>

   <oj-chart
      id="barChart"
      type={val}
      . . .>

  5. Save the index.tsx file.

    Your index.tsx file should look similar to final-connect-index-tsx.txt.

  6. Return to the browser to view the changes in your virtual DOM app.

    The browser now displays the basic starter template with the Select Single and Pie Chart components visible in your virtual DOM app.

    Image showing the pie format of the Chart component

  7. To see the different chart formats, choose between the options in the Select Chart dropdown list.

  8. Close the browser window or tab that displays your running virtual DOM app.

  9. In the terminal window, press Ctrl+C, and, if prompted, enter y to terminate the Oracle JET tooling batch job.

  10. Leave the terminal window open for your next tutorial.

Next Step

Proceed to the next tutorial in this module.

This tutorial is part of the module Your First Oracle JET Virtual DOM App.

You can return to the virtual DOM learning path’s main page to access all the modules on building virtual DOM apps.

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.