Add components to an Oracle JET web app

Introduction

This tutorial shows you how to add Oracle JavaScript Extension Toolkit (Oracle JET) components to the navdrawer starter template of your Oracle JET web app.

Oracle JET is a development toolkit that you use to build client-side web apps. To create your web app, use the Oracle JET Cookbook to locate the component samples that illustrate the specific functionality you want to add to your app. The Oracle JET Cookbook also provides instructions that you can follow to support behavior specific to the components.

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 Dashboard tab of your web 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]]"
  value=""
></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_Web_Application/src/css 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_Web_Application/src/ts/views directory and open the dashboard.html file in an editor.

  2. Within the HTML div element of the Dashboard Content Area, add an oj-label custom HTML element and an oj-select-single element. Also add an id attribute with a value of itemDetailsContainer to the div element.

       
<h1>Dashboard Content Area</h1>
<div id="itemDetailsContainer">
  <oj-label for="basicSelect">Select Chart:</oj-label>
  <oj-select-single
    id="basicSelect"
    class="selectSingleStyle"
    data="[[chartTypesDP]]"
    value="{{val}}"
  >
  </oj-select-single>
</div>

    The square brackets surrounding the chartTypesDP observable on the data attribute means the value can be read but not updated by the component. The curly braces surrounding the val observable on the value attribute means the value can be read and updated by the component. Thus, square brackets surrounding an observable define a one-way binding, whereas curly braces surrounding an observable define a two-way binding.

  3. Edit the HTML h1 element to display the header Product Information.

    <h1>Product Information</h1>

  4. Save the dashboard.html file. Your dashboard.html code snippet should look similar to add-select-single-dashboard-html.txt.

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

  6. At the top of the dashboard.ts file, import the Knockout library, the Oracle JET mutable array data provider module, and the Oracle JET modules for the Label component and the Select Single component.

    
import * as ko from "knockout";
import MutableArrayDataProvider = require("ojs/ojmutablearraydataprovider");
import "ojs/ojselectsingle";
import "ojs/ojlabel";

  7. Before the DashboardViewModel() class, add a type alias for the chart types (ChartType). Within the DashboardViewModel() class, add a chart type data array (chartTypes) and an instance of mutable array data provider (chartTypesDP) to allow binding of the chart type data by the Select Single component.

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

class DashboardViewModel {
   chartTypes: Array<Object>;
   chartTypesDP: MutableArrayDataProvider<ChartType["value"], ChartType>;

   constructor() {
   this.chartTypes = [
      { value: "pie", label: "Pie" },
      { value: "bar", label: "Bar" },
      ];

   this.chartTypesDP = new MutableArrayDataProvider<
      ChartType["value"],
      ChartType
      >(this.chartTypes, {
      keyAttributes: "value",
      });
  } // End constructor

  8. Add the ko.observable method to display the pie chart type as the default value for the Knockout observable of the Select Single component.

    class DashboardViewModel {
   val: ko.Observable<string>;
   . . .

      constructor() {
        this.val = ko.observable("pie");
        . . .

  9. Save the dashboard.ts file. Your dashboard.ts code snippet should look similar to add-select-single-dashboard-ts.txt.

  10. Open a terminal window, change to the JET_Web_Application directory, and run the app.

    npx ojet serve

    The browser displays the navdrawer starter template with the Select Single component visible in the Dashboard tab of your web app.

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

  11. Leave the terminal window and the browser that displays your web app open.

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

Task 3: Add a Chart Component

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

  2. Add the oj-chart custom HTML element below the oj-select-single custom HTML element such that the two elements appear inside the same HTML div element of the Dashboard content area.

    <oj-select-single id="basicSelect"
  . . .
 </oj-select-single>
<oj-chart id="barChart"
          type="bar"
          data="[[chartDataProvider]]"
          animation-on-display="auto"
          animation-on-data-change="auto"
          hover-behavior="dim"
          class="chartStyle">
</oj-chart>

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

    <oj-chart id="barChart" . . . class="chartStyle">
  <template slot="itemTemplate" data-oj-as="item"> </template>
</oj-chart>

  4. Within the template element, add an oj-chart-item custom HTML element with attributes that use one-way bindings to get the chart data from the current object.

    <oj-chart id="barChart" . . . class="chartStyle">
  <template slot="itemTemplate" data-oj-as="item">
    <oj-chart-item
      value="[[item.data.value]]"
      group-id="[[ [item.data.group] ]]"
      series-id="[[item.data.series]]"
    >
    </oj-chart-item>
  </template>
</oj-chart>

  5. Save the dashboard.html file. Your dashboard.html code snippet should look similar to add-chart-dashboard-html.txt.

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

  7. Add the chartDataProvider observable set to a new Oracle JET MutableArrayDataProvider object that will contain the chart data.

    class DashboardViewModel {
. . .
   chartDataProvider: MutableArrayDataProvider<string, {}>;

constructor() {

   . . .
   this.val = ko.observable("pie");

   this.chartDataProvider = new MutableArrayDataProvider(this.chartData, {
   keyAttributes: "id",
   });
   . . .
}

  8. Within the DashboardViewModel() class, add the chartData array below the Knockout observable. You declare the type of this array to be Array<Object>.

    chartTypesDP: MutableArrayDataProvider<ChartType["value"], ChartType>;
chartData: Array<Object>;

constructor() {
   this.val = ko.observable("pie");

   this.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 }
   ];

  9. Import the module for the Oracle JET Chart component.

    import "ojs/ojchart";

  10. Save the dashboard.ts file. Your dashboard.ts file should look similar to final-chart-dashboard-ts.txt.

  11. Return to the browser to view the changes in your web app.

    The browser displays the navdrawer starter template with the Bar Chart component visible in the Dashboard tab of your web app.

    Image showing a Chart component.

    Notice that the Dashboard tab displays only the bar chart format for each Select Chart dropdown list option. You must add a dependency between the two components to display each chart format.

  12. Leave the terminal window and the browser that displays your web app open.

Task 4: Connect the Two Components

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

  2. In the dashboard.html file, edit the oj-chart custom HTML element to connect the type attribute of the Chart component to the value attribute of the Select Single component with a one-way binding.

    <oj-chart id="barChart"
       type="[[val]]"
       . . .
 </oj-chart>

    The square braces surrounding the val observable on the type attribute means the value can be read but not updated by the component. Square braces surrounding an observable define a one-way binding.

  3. Save the dashboard.html file. Your dashboard.html file should look similar to final-connect-dashboard-html.txt.

  4. Return to the browser to view the changes in your web app.

    The browser now displays the navdrawer starter template with the Select Single and Pie Chart components visible in the Dashboard tab of your web app.

    Image showing a pie format of the Chart component.

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

  6. Close the browser window or tab that displays your running web app.

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

  8. 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 Web Application.

You can return to the learning path’s main page to access all the modules on building web 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.