Create the master view in an Oracle JET virtual DOM app

Introduction

This tutorial discusses how to read master-detail hierarchical data from a local JavaScript Object Notation (JSON) document and display the data in a List View component of an Oracle JavaScript Extension Toolkit (Oracle JET) virtual DOM app.

In Oracle JET, you can use the Oracle JET API to create a data provider object. The object represents a data array that you populate from the parent objects of a JSON document data store. The data attribute of Oracle JET custom HTML elements binds to the data through an instance of a MutableArrayDataProvider data provider object that you create.

Objectives

In this tutorial, you will data bind multiple items of the parent data objects in a local JSON document and populate the rows of an Oracle JET List View component in the Activity Container component with that data.

Prerequisites

Task 1: Download the Starter Virtual DOM App

Skip this task if you’re continuing to work in an app that you created in the previous learning path.

  1. Rename jet-virtual-dom-app-temp.zip as JET-Virtual-DOM-app.zip. Extract the contents to the JET-Virtual-DOM-app directory.

  2. In the terminal window, navigate to the JET-Virtual-DOM-app directory, and restore the Oracle JET app.

    npm install

    Your app is ready to use.

Task 2: Download the Product Images

Skip this task if you downloaded the starter app in jet-virtual-dom-app-temp.zip.

  1. If the Oracle JET tooling server batch job is running in the terminal window, press Ctrl+C, and if prompted, enter y to exit the server batch job.

    The server batch job only recognizes revisions that you make to existing app files. After you create new files, you must run the virtual DOM app again.

  2. Download the product_images.zip file to the JET-Virtual-DOM-app/src/styles/images directory.

  3. Extract the content of the zip file into a new product_images directory in the images directory.

    The path to the new directory is JET-Virtual-DOM-app/src/styles/images/product_images, and the directory contains the images that your app uses.

Task 3: Create a Mutable Array Data Provider in Parent Container 1

  1. Open the Oracle JET Cookbook and navigate to the Cookbook Home page. Click Framework, then Data Provider, and then Mutable Array Data Provider. In the Cookbook toolbar, click API Doc.

  2. In the API documentation, read about the MutableArrayDataProvider class. Note how you can use the optional argument keyAttributes to create an instance of a MutableArrayDataProvider based on the key attribute of the passed-in data object.

  3. If you have not already done so in a previous learning path, download the store_data.json file to the JET-Virtual-DOM-app/src/components directory.

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

  5. At the top of the file, add import statements for the MutableArrayDataProvider class and the JSON data in the store_data.json file.

    import MutableArrayDataProvider = require('ojs/ojmutablearraydataprovider');
import * as storeData from 'text!./store_data.json';

  6. Create an Activity type alias.

    type Activity = {
  id: number;
  name: string;
  short_desc: string;
};

  7. Create an activityDataProvider instance of a MutableArrayDataProvider.

    const activityDataProvider = new MutableArrayDataProvider<Activity['id'], Activity>(
  JSON.parse(storeData),
  {
    keyAttributes: 'id',
  }
);

    The keyAttributes property of the MutableArrayDataProvider class populates an array based on the id attribute of the parent object. The id attribute is the key attribute for parent and child data objects in the JSON document.

  8. In the ParentContainer1 function, add a data attribute to the ActivityContainer element that passes the data provider object to the Activity Container component using props.

    return (
    <div id="parentContainer1" class="oj-flex oj-flex-init oj-panel oj-bg-warning-20">
        <ActivityContainer data={activityDataProvider} />
        <ParentContainer2 />
    </div>
    );
};

    Your code should look similar to parent-container1-1-tsx.txt.

Task 4: Create the Activity Container’s List View Component

Create an Oracle JET List View component in the Activity Container component to display multiple data items for each list row from the data provider object passed down via props from the ParentContainer1 component. To instantiate the contents of the list row data items at runtime, the List View component uses an HTML template element with a slot attribute as a placeholder.

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

  2. Add the following import statements for the Oracle JET List View component and MutableArrayDataProvider class to the top of the file.

    import 'ojs/ojlistview';
import { ojListView } from 'ojs/ojlistview';
import MutableArrayDataProvider = require('ojs/ojmutablearraydataprovider');

  3. Create Props and Activity type aliases.

    type Props = {
  data?: MutableArrayDataProvider<Activity['id'], Activity>;
  value?: string;
};

type Activity = {
  id: number;
  name: string;
  short_desc: string;
};

  4. Find the div element with id="activitiesContainer", and delete the oj-sm-only-text-align-end helper class to prevent realignment of the Activity Container’s contents.

  5. Create the listItemRenderer function that renders each list item and includes span and div elements to populate the List View component’s rows with a background image, name, and short description.

    Also define an image variable to ensure that the virtual DOM app can locate the product images in the app’s styles directory.

    const listItemRenderer = (item: ojListView.ItemTemplateContext) => {
  let image = item.data.image.replace('css', 'styles');
  return (
    <div class="oj-flex no-wrap">
      <span
        class="demo-thumbnail oj-flex-item"
        style={'background-image:url(' + image + ')'}></span>
      <div class="demo-content oj-flex-item">
        <div>
          <strong>{item.data.name}</strong>
        </div>
        <span class="demo-metadata">{item.data.short_desc}</span>
      </div>
    </div>
  );
};

  6. Underneath the listItemRenderer function, add the following ListViewProps type alias and two variables to define the gridline and scroll properties for the List View component.

    type ListViewProps = ComponentProps<'oj-list-view'>;
const gridlinesItemVisible: ListViewProps['gridlines'] = { item: 'visible' };
const scrollPolicyOpts: ListViewProps['scrollPolicyOptions'] = { fetchSize: 5 };

  7. Add props to the ActivityContainer function definition.

    const ActivityContainer = (props: Props) => {

  8. Inside the ActivityContainer function’s return statement, delete the div element where id="activitiesItems and the list inside of it. Replace them with the following List View component, where the data provider object is accessed via props in the List View’s data attribute.

    <h3 id="activitiesHeader">Activities</h3>
  <oj-list-view id="activitiesList" class="item-display" aria-labelledby="activitiesHeader"
                data={props.data} gridlines={gridlinesItemVisible} selectionMode="single"
                scrollPolicy="loadMoreOnScroll" scrollPolicyOptions={scrollPolicyOpts}>
  </oj-list-view>

  9. Within the List View component, add a template element with a slot attribute to render each item in the list.

    . . .
    <template slot="itemTemplate" render={listItemRenderer}></template>
</oj-list-view>

    Save the file. Your code should look similar to activity-container-tsx-1.txt.

Task 5: Run the App and Debug the App’s Cascading Style Sheet

  1. In the terminal window, navigate to the JET_Virtual_DOM_app directory and run the app.

    npx ojet serve

    Oracle JET tooling runs your virtual DOM app in your local web browser, where you can view the changes to the Activity Container component. The images displayed to the left of the activity names and short descriptions are only partially displayed because they are too large.

    If you resize your browser and still don’t see a page similar to this sample screenshot, confirm that you extracted the app images into the images/product_images directory.

    The thumbnail images are only partially displayed

  2. In your Google Chrome browser, right-click the partial image for the Soccer activity and select Inspect. The browser displays the Chrome Developer Tools (DevTools) where you can inspect the HTML page source.

  3. In the Elements panel, the span element where class="demo-thumbnail oj-flex-item" should be selected. In the Styles panel, locate the highlighted element.style background-image style. Right-click the URL for the jrsoccerball.jpg image, and select Reveal in Sources panel.

    Inspect the image source in the Sources panel

  4. The Chrome DevTools Sources panel shows that the image is 300 x 300 pixels, and therefore the size is too large to be displayed in the list view. To render a thumbnail-sized image from a full-sized image, you can define a Cascading Style Sheets (CSS) style class.

    View the image properties in the Sources panel

  5. Close the Chrome DevTools window and return to the app in the browser.

Task 6: Fix the CSS and View the Activities List Changes

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

  2. Define the properties for the .demo-thumbnail class selector. In the list of properties, set a background-repeat property to no-repeat to show the image only once.

    .demo-thumbnail {
  border-radius: 5px;
  background-size: 40px 40px;
  background-repeat: no-repeat;
  min-width: 40px;
  min-height: 40px;
  max-width: 40px;
  margin-right: 10px;
}

    In the listItemRenderer function in the ActivityContainer.tsx file, the span element references the class selector to format the Activities list images as thumbnails by setting the demo-thumbnail CSS style on the class attribute.

  3. Save and close the app.css file. Your file should look similar to app-css.txt.

  4. Return to the browser and view the updates.

    The app displays the Activities list with thumbnail images.

    The images in the Activity Container are displayed correctly

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

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

Next Step

Proceed to the next tutorial in this module.

This tutorial is part of the module Master Detail Views in Oracle JET.

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.