Prerequisites

What you are going to build

In this lab you will be starting with the Oracle JET NavDrawer starter template, and then adding a couple of Data Visualization Chart components. You will connect the two components together so that you have Associated Views. When you hover over one chart, the highlighted value will show in both charts at the same time. The completed page will look like the image below.

Getting things set up

Using the Oracle JET Starter Templates

You can generate the JET NavDrawer starter template by using the following command line syntax:

yo oraclejet <projectname> --template=navdrawer

For details on how to setup the Oracle JET CLI tools, please reference the JET Developer Guide

An overview of the starter template structure

1. The file structure for the template application will look similar to image 1 below. Notice how the HTML templates for each page are kept in the /js/views directory, while the corresponding JavaScript file is kept under the /js/viewModels directory.
   
   
   Image 1: file structure
   
   
   
2. Looking at the index.html file will show you how the project uses the JET ojModule feature to load templates into various parts of the application
   
   
   Image 2: index.html
   

3. You can now run the application (the index.html file) in a browser and see the default look and feel of the NavDrawer Starter Template

   Running the application

   When running a JavaScript application from the filesystem, not all browsers will work the same. Firefox will allow you to run the index.html file directly from the filesystem, while Chrome and Safari will throw an error. To work with Chrome or Safari, you will need to run the files from a web server of some kind. Please refer back to the "Getting things setup" section above for instructions on how to start and run a smaller web server from your HOL machine.

   
   
   
4. All Oracle JET Starter Templates are setup to be responsive in nature. It has breakpoints set at Desktop (over 1024px), iPad Landscape, iPad Portrait, and Phone (smaller than 768px). Resize the browser window to see the various behaviors for each section of the application. Images 3 - 6 show how the application will look at each of the device sizes.
   
   
   Image 3: Desktop layout
   
   
   
   Image 4: Mobile layout
   
   
   
   Image 5: Mobile with drawer
   
   
   

Getting the basic layout

For this Hands on Lab, you are going to add content to the Dashboard content page of the starter template. You can work with the other pages of the template on your own at a later time if you like.

JET provides a collection of CSS helper classes to work with CSS3 Flexbox. By using these classes you can quickly setup your pages to be responsive to the device sizes your customers will view it from. Follow the steps below to setup the basic layout for your page.

1. Open the dashboard.html file in your editor. This file is located in the /js/views folder.
2. Just below the <h3> page title, add the following DOM structure
   

   <div class="oj-flex oj-flex-items-pad">
      <div class="oj-flex-item">
   
      </div>
      <div class="oj-flex-item">
   
      </div>
   </div>
                                               

For more details on working with CSS3 Flexbox, a good reference is CSS-Tricks.com

Adding the first Oracle JET Chart

Continuing with the dashboard.html file, you are now going to add the first of two Data Visualization components. You will copy the HTML code from the Oracle JET Cookbook page.

1. Copying content from Cookbook to the editor

   1. Next you are going to copy and paste some content from the Cookbook page, into the dashboard.html file.
   2. Open the dashboard.html file from the /js/views folder in your editor
   3. Open the corresponding JavaScript module (dashboard.js) from the /js/viewModels folder, in your editor as well. This will leave you with two files open in the editor. You are going to focus on the dashboard.html file first
   4. Copy all of the HTML code shown in the HTML Editor section of the Cookbook page (look at image 6 below to see what the HTML Editor selection looks like).
      
      
      Image 6: bar chart selection from cookbook
      
      
   5. In the dashboard.html file, paste the copied HTML code inside of the first oj-flex-item <div> element that you created in the steps above.

   6. The dashboard.html file will look like image 7 below at this point
      
      
      Image 7: dashboard.html with new content pasted from cookbook
      
      

   7. Now that you have the first chart added to the page, let's move on to the second chart. Go to the Bubble Chart Cookbook page and copy the HTML from that page into the second oj-flex-item <div> element this time. See image 8 below for what the HTML selection looks like.
      
      
      Image 8: bubble chart selection from cookbook
      
      
   8. Once you have both charts pasted into the dashboard.html file, it should look like image 9 below.
      
      
      Image 9: dashboard html with new content
      
      

2. Working with JavaScript

   1. When working with a Knockout.js based application you will use what is called a ViewModel to connect the data in your View (HTML page) with some JavaScript that can manipulate the Model (data) and set the specific values that you want displayed on the page. Knockout.js provides the two-way binding that allows you to change something in the Model and have it automatically updated on the View. This type of application architecture is referred to as Model - View - ViewModel or MVVM
   2. Take a look at the JS Editor section of the Bar Chart Cookbook page. See image 10 below for a reference.
   3. There are two things that you will want to use from this example.
      1. The reference to the component module that you are going to be using on the page. For the Chart components this is ojs/ojchart
      2. The content of the ViewModel, which in this example is named ChartModel(). The content you are interested in is the definition of barSeries, barSeriesValue, barGroups, barGroupsValue
         
         

         Knockout.js observables

         An "observable" or "observableArray" is a special type of two-way binding variable used by Knockout.js. When the value is changed by either the UI, or the JavaScript ViewModel, the other references to the observable are automatically updated as well.

         
         Image 10: JS editor section of Bar Chart cookbook page
         
         

   4. You are going to add both of these sections of code to the corresponding sections of the dashboard.js file (shown in the white areas of image 11 below, along with the clean ups that you will do in the next steps).
      The ojs/ojchart line goes on to the end of define() method, and the Array and Knockout observableArray definitions go into the DashboardViewModel function further down in the file.
   5. Make sure you add the new module reference to the end of the define() method and not in the middle some where.
      
      
      Image 11: dashboard.js with bar chart
      
      
   6. Repeat the same copy and paste for the bubble chart JavaScript. You will not need to copy the ojchart module again as that is only needed once. Just copy the Array and two knockout observable definitions like you did for the Bar Chart.

   Working with AMD modules

   Notice with the examples in Images 10 and 11 above, you are NOT copying the entire code section. The Cookbook uses a "require" call to just load and use the needed libraries in one page. The starter template page that you are pasting into, is an AMD module which uses "define" to create a module that can be used by other parts of your application.

   
   
   

3. A little clean up

   • In the dashboard.html file, remove the orientation and stack options from both of the chart definitions. When you're done, your file should looks like image 9 above.

4. Run the project

   • You can now run the application (the index.html file) in a browser and see the two charts shown side by side. The charts are automatically styled to use the Oracle Alta theme. If you hover over any of the chart items, you will see that the other items are faded to make your value stand out.

Tying everything together

1. You should now see the two types of charts and they should work fine by themselves, but you want them to be integrated.
2. If you look at the dashboard.js file, you will see that the names for the series in each chart's dataset, are the same. We can define this dataset once as an array and then reference it in each of the components data definitions. Copy the code below and add it to DashboardViewModel function, just under the var self = this; line.
   

    // Categories
    var categories = ["Initial", "Qualification", "Meeting", "Proposal", "Close"];                                                
   
                                               

3. Next, update both the chartSeries and bubbleSeries arrays with the code below.

   /* chart data */
   var barSeries = [{name: categories[0], items: [42, 34]},
       {name: categories[1], items: [55, 30]},
       {name: categories[2], items: [36, 50]},
       {name: categories[3], items: [22, 46]},
       {name: categories[4], items: [22, 46]}];                                                
                                               

   /* chart data */
   var bubbleSeries = [{name: categories[0], items: [{x: 15, y: 25, z: 5}, {x: 25, y: 30, z: 12}, {x: 25, y: 45, z: 12}]},
       {name: categories[1], items: [{x: 15, y: 15, z: 8}, {x: 20, y: 35, z: 14}, {x: 40, y: 55, z: 35}]},
       {name: categories[2], items: [{x: 10, y: 10, z: 8}, {x: 18, y: 55, z: 10}, {x: 40, y: 50, z: 18}]},
       {name: categories[3], items: [{x: 8, y: 20, z: 6}, {x: 11, y: 30, z: 8}, {x: 30, y: 40, z: 15}]},
       {name: categories[4], items: [{x: 4, y: 17, z: 2}, {x: 35, y: 10, z: 15}, {x: 22, y: 22, z: 13}]}];                                                
                                               

4. You can run the code at this point and you should still see the two charts, but with the new series names
5. Finally you are going to connect the two charts together with a feature called Associated Views.
   1. Staying in the dashboard.js file, add this line of code just below the categories array definition

      self.highlightedCategoriesValue = ko.observableArray([]);                                                        
                                                          

   2. In the dashboard.html file, add the following option to both chart definition blocks

      highlightedCategories: highlightedCategoriesValue                                                        
                                                          

6. Save your changes and run the page. You should now see that when you hover over any value in one chart, both charts will highlight that series and fade all other series.

7. Explaining a bit of the magic

   The Associated Views feature of ojCharts takes advantage of the Knockout two-way binding. When you bind both charts highlightedCategories: option to the same knockout observableArray, it causes any changes to the highlighting in one chart, to be propogated to the second one. When you hover over one chart item, that chart updates the value of it's highlightedCategories option. Because that option is bound to a knockout observableArray, an event is sent notifying any other DOM elements that are also bound to that observableArray, that the value has changed and that they should update their values to match.

8. If you've gotten this far in the HOL and you still have some time left, try adding the hiddenCategories: and hideAndShowBehavior: options to both charts and then define hiddenCategoriesValue in the dashboard.js file just like it was done for the highlighting option. If it all works correctly, you should see something different when you click on any of the Legend items on either chart.

Next Steps

Obviously you have not learned all there is to know about Oracle JET while taking this short Hands on Lab. We encourage you to explore more about Oracle JET by visiting the many resources found on the Internet. Look in the footer of the Oracle JET website for links to many other resources like, YouTube, Twitter, Developers Guide, and Community discussion forums.

We wish you all the best in your adventures and....

Happy Coding!!

---

Related articles

• Learn Knockout.js
• Learning jQuery
• Learning advanced JavaScript
• Understanding RequireJS
• W3Schools CSS Tutorial
• The Best way to learn CSS