Create a dashboard using RequireJS

In this walk-through tutorial, you will create a CTools dashboard using RequireJS. These instructions assume that you are familiar with the main features in CDE and the basic steps of creating a dashboard in CDE. In addition, these instructions assume that you have activated the CDE plugin.

The process is broken down into six basic steps.

• Step 1: Set up folders in User Console and create the dashboard

• Step 2: Add layout

• Step 3: Add external resources

• Step 4: Add data sources

• Step 5: Add components

• Step 6: Preview the dashboard

Step 1: Set up folders in User Console and create the dashboard

• Log on to the User Console and navigate to the Browse Files perspective.

• In the Folders pane, click on the Public folder and then, in theFolder Actions pane, click New Folder. Create a solutions folder called demoDashboard.

• Expand the Public folder and click on the newly created demoDashboard folder. In the Folder Actions pane, click New Folder and create a subfolder titled files which will contain the JavaScript and Cascading Style Sheets (CSS) files used in this dashboard.

• Open CDE and create a new dashboard titled demoDashboard, and save it in the public > demoDashboard folder you just created.

• From the CDE menu bar, click Settings, and then select the RequireJS Support check box to convert the dashboard to a RequireJS dashboard.

  
• Click Ok.

  A message box appears warning you about possible issues with your custom JavaScript code in your dashboard. Click Ok to proceed. The dashboard is now saved as a RequireJS dashboard.

Step 2: Add layout

• From the Layout Structure menu bar, click the Add Bootstrap Panel button.

  
• Configure your bootstrap panel to match the settings in the image below. Be sure to add and rename all displayed rows and columns.

  
• In the Properties pane, all columns by default set the Extra Small Devices property to 12 spans. Change the Value for the following columns:

  • Set tableObj and chartObj to 6 spans. See CDE dashboard overview for more information on Bootstrap in CDE.

  
• Center the title and subtitle in the Properties pane.

  For both titleColumnObj and subTitleColumnObj, locate the Text Align property and click in the Value column. On the keyboard, press the down arrow to display a drop-down menu and select Center.

  

Step 3: Add external resources

• In the CDE Layout perspective, on the Layout Structure toolbar, click the Add Resource icon.

  
• In the Add Resource dialog box, enter the following data:

  • For Resource Type, select Javascript.

  • For Resource Source, select External File. Click Ok.

• In the Properties pane, click in the Value column to the right of the Name property and enter addins. Press Tab or Enter.

  
• Click the caret ('^') button to the right of the Resource file property and navigate to public > demoDashboard > files. Click Ok.

• In the Create File dialog box, enter addins and click Ok.

  You have now created the addins.js file, which will contain the JavaScript code to execute within the dashboard components. Note that the name you give to the JS file is how the file itself will be referenced within the dashboard.

• To enter content in the addins.js file, select the addins resource in the Layout Structure pane. Locate the Resource file property and click the ellipse ('...') button to open the Edit window. Enter the following content for this file:

  Copy

  define([
    "cdf/AddIn",
    "cdf/Dashboard.Clean",
    "cdf/Logger",
    "cdf/lib/jquery"
  ], function(AddIn, Dashboard, Logger, $) {
    Dashboard.registerGlobalAddIn("Table", "colType", new AddIn({
      name: "customArrow",
      label: "customArrow",
      defaults: {},
      implementation: function(tgt, st, opt) {
        if(typeof st.value !== "number") {
          Logger.warn("customArrow add-in invalid value: " + st.value);
          return;
        }
        var trend = st.value > 0 ? "up" : "down";
        $(tgt).empty()
              .append($('<ul><span class="glyphicon glyphicon-arrow-'
                + trend +'"></span>&nbsp<span>'+ st.value +'%'+'</span></ul>'));
      }
    }));
  });

  • Lines 2 to 5 specify the dependencies needed for the add-in, which are then registered for use in the function.

  • Line 7 registers the add-in, which is then available to the table component.

• Press the Save button and then press the Close button.

• Following steps 2 through 5, add a second JavaScript external resource named title and save a new file named title.js in the public > demoDashboard > files folder. The dashboard will have a title and a subtitle which are provided by the text components created in Step Five. These components will fetch the displayed value from an object returned by the AMD module defined in the title.js file.

• To enter content in the title.js file, in the Layout Structure pane select the title resource and then select the Resource file property. Click the ellipse ('...') button to open the Edit window. Enter the following content for this file:

  Copy

  define(function() {
    return {
      option1: 'CDE Dashboard',
      option2: 'Using a Table with a custom add-in and a CCC Bar Chart',
    };
  });

  In this file, an AMD module is defined which returns an object with two properties. This object will be accessible to the text components, using the same name as the one used for the Name property of the JavaScript external resource, and its properties will be used as the title and subtitle.

• Press the Save button and then press the Close button.

Step 4: Add data sources

In this example, you will use scripted queries as the data source.

1. In the Data Source perspective, from the Data Source list, click SCRIPTING Queries, and then click scriptable over scripting twice.

2. In the Datasources panel, in the Name column, enter chartQuery for the first data source, and tableQuery for the second.

   
3. Add the following script to the Query property for the chartQuery data source:

   Copy

   import org.pentaho.reporting.engine.classic.core.util.TypedTableModel;
   String[] columnNames = new String[]{
     "Country", "Population growth per City [%]"
   };
   Class[] columnTypes = new Class[]{
     String.class, Float.class
   };
   TypedTableModel model = new TypedTableModel(columnNames, columnTypes);
   model.addRow(new Object[]{
     new String("Tokyo"), new Float("60")
   });
   model.addRow(new Object[]{
     new String("Nice"), new Float("20")
   });
   model.addRow(new Object[]{
     new String("London"), new Float("-10")
   });
   model.addRow(new Object[]{
     new String("Munich"), new Float("30")
   });
   model.addRow(new Object[]{
     new String("Porto"), new Float("10")
   });
   model.addRow(new Object[]{
     new String("Brasilia"), new Float("10")
   });
   
   return model;

4. Add the following script to the Query property for the tableQuery data source:

   Copy

   import org.pentaho.reporting.engine.classic.core.util.TypedTableModel;
   String[] columnNames = new String[]{
     "Country", "City", "Population growth per City"
   };
   Class[] columnTypes = new Class[]{
     String.class, String.class, Float.class
   };
   TypedTableModel model = new TypedTableModel(columnNames, columnTypes);
   model.addRow(new Object[]{
     new String("Japan"), new String("Tokyo"), new Float("60")
   });
   model.addRow(new Object[]{
     new String("France"), new String("Nice"), new Float("20")
   });
   model.addRow(new Object[]{
     new String("UK"), new String("London"), new Float("-10")
   });
   model.addRow(new Object[]{
     new String("Germany"), new String("Munich"), new Float("30")
   });
   model.addRow(new Object[]{
     new String("Portugal"), new String("Porto"), new Float("10")
   });
   model.addRow(new Object[]{
     new String("Brazil"), new String("Brasilia"), new Float("10")
   });
   
   return model;

Step 5: Add components

• Switch to the Components perspective.

• From the Components list, expand the appropriate Group section, and then add the following components to the dashboard with the specified Name and HtmlObject properties in the table below. (See Customize the Components Perspective for more detailed instruction.)

  Group

  Component

  Name

  HtmlObject

  Others

  Text Component

  subTitleComponent

  subTitleColumnObj

  Others

  Text Component

  titleComponent

  titleColumnObj

  Others

  table Component

  tableComponent

  tableObj

  Charts

  CCC Bar Chart

  chartComponent

  chartObj

  
• Set the width and height for the chartComponent bar chart.

  • Click in the Value column for the Height property and type 450. Press Tab or Enter.

  • Click in the Value column for the Width property and type 400. Press Tab or Enter.

• Set the titleComponent text component by adding the following code to the Expression property:

  Copy

  function f() {
    return "<strong>" + title.option1 + "</strong>";
  }

  This piece of code is returning the content of option1 defined in the title.js file in Step Three.

• Set the subTitleComponent text component by adding the following code to the Expression property. Note that this code is similar to the previous step, substituting option2 for option1:

  Copy

  function f() {
    return title.option2;
  }

• In the tableComponent component, set the Column Types property as follows:

  

  Notice that the third line in the table is using the non-standard customArrow add-in. It is now available because it was registered earlier using the addins.js JavaScript external resource file.

• Set the Datasource property for the tableComponent to use the tableQuery data source created earlier in Step Four.

• Set the Datasource property for the chartComponent to use the chartQuery data source created earlier in Step Four.

Step 6: Preview the dashboard

• Save your dashboard and click the Preview your Dashboard icon in the top-right corner.

  The Preview window displays.

• Inspect your dashboard.

  Your finished dashboard should look similar to the image below.

  
• When finished, close the Preview window.