Learning Pentaho CTools (2016)

Chapter 4. Leverage the Process with CDE

In the previous chapter, you saw how to create custom dashboards at the code level, and now you will see how to build them in an easier and faster way. Creating a custom dashboard should not be difficult and time-consuming, and CDE is a Pentaho server plugin that allows you to create, edit, and render a dashboard easily. CDE can build all the code for you, and you just need to use the graphical interface that CDE will make available to you to create or edit your dashboards.

The topics covered in this chapter are based on how to create a dashboard using a graphical user interface (GUI). You will gain knowledge on how to build a responsive layout for the dashboard, add components, add some custom code, and add resources (both JavaScript and CSS) to the dashboard to create and use data sources without the need to create the CDA file by hand. What you learn here will help you to leverage the process and decrease the development time of the dashboards.

In the previous chapter, we already covered a major part of the core concepts that you need to build a dashboard using CDF/CDE. When you are building a CDE dashboard, you are creating CDF content, even if you are using CDE only components, as at the end they are also using and working on top of CDF. You are not required to build a dashboard by writing code using CDF, so you can skip writing CDF code, but it is important to know how it works and have a good understanding of it. Only this way will you be able to make the most out of CDE when building your dashboards. Make sure you really understand the lifecycle of the dashboard and components, as this is very important, even if you don't want to create your dashboards by writing your own code using CDF.

During this chapter, we will cover the following topics:

· Including resources in the dashboard

· Creating responsive dashboards

· Creating and customizing the layout of the dashboard

· Defining and using data sources

· Making use of parameters and listeners

· Making use of components

· Changing the order of execution of the components

· Previewing the dashboard

A brief introduction to CDE

CDE is a graphical interface tool where you can create your dashboard. Using CDE, you are able to decrease the development time, because CDE will generate the CDF code for you. But how does this work? The dashboard file is created on the client side and saved to the server side. When we later request that dashboard, we are making the request to the server which will deliver to the client side as an HTML page. This HTML page will not only include all the libraries needed for the execution of the dashboard, but will also provide the code for the dashboard. As soon as the browser, on the client side, has the HTML page, it will make the request to get all the libraries or JavaScript and CSS files that are needed or included by the developer in the dashboard. The server will return the files to the browser, and the web page that in turn is the dashboard, can begin executing.

When rendering the components, the dashboard, or to be more precise, the components, will make the requests for the queries to get the data to be displayed on the page. After getting the results and executing the remaining code, the dashboard is finally ready, and the user now has the ability to start interacting with the dashboard.

As we saw in previous chapters, the interaction of the user will generate changes on the parameters that in turn will trigger the update of the components, which will trigger new queries to get new data to the dashboard.

You should not expect CDE to have direct properties or options that you can directly set for everything you can do on the web or in a business analytics solution, but CDE will definitely provide a way to do these things; you just need to have an open mind and a good understanding of how CDE works. CDE works on top of CDF and CDA, and uses CCC. This way, you will find a solution for all your goals and build amazing, stunning dashboards that can go much further and build prescriptive solutions.

Working with the editor

One of the first things you need to learn to do is save and edit a particular dashboard. Usually, when using the term open the dashboard, we are referring to the operation of calling the dashboard using the generatedContent endpoint, which will execute the dashboard in the browser. This way, you will execute the dashboard and be able to interact with the dashboard. This is the operation that the final user will perform when requesting a dashboard.

There is another term that is frequently used, open the dashboard using the edit mode, which refers to the process of editing the dashboard in a way that you can make changes to the dashboard or just look at its layout, components, and data sources. This operation can be done using both wcdf.edit and the edit endpoints.

From now on, just let's use open and edit, the first when referring to the call to the dashboard to render the dashboard, and the second to make changes to the layout, components, or data sources.

Tip

The ability to create a new dashboard in a Pentaho standard installation

By default from version 5.3 and above, CTools comes with the Pentaho standard installation, but with a disabled flag that would not provide an option to create a new dashboard. You can overcome this by installing the last stable version of CTools (CDE, CDF, CDA, and CGG), by following the procedures in the second chapter.

To create a new dashboard, go to Pentaho User Console (PUC) and select from the menu: File | New | CDE Dashboard, and you will get a new tab with CDE Editor. What Pentaho is doing here is calling an endpoint that you can also call directly in your browser using the following URL: http://<server>:<port>/pentaho/api/repos/wcdf/new.

To open or edit a dashboard, you should select the dashboard from the repository using the PUC browser and click the open or edit button on the rightmost panel. Depending on the operation you are doing, you will get a new tab in the PUC, which uses one of the following URLs:

· To edit: http://<server>:<port>/pentaho/api/repos/<path>/wcdf.edit

· To open: http://<server>:<port>/pentaho/api/repos/<path>/generatedContent

Here, path would the path and filename of the dashboard and something similar to :public:Steel Wheels:CTools_dashboard.wcdf, which would redirect you to the Steel Wheels sample CDE dashboard. This will lead you to a good example that you later should edit and take a look at to recap what you have learned by reading this book. This is also a way to learn a few more tricks.

When creating a new dashboard or editing an existing one, you will get something like the following image, that we can divide into six sections:

The sections shown in the previous image are explained as follows:

1. Main toolbar: Here you will find some functional buttons such as New, Save, Save as..., Reload, and Settings. This is where you select where to save a file, the name, and description of the dashboard, and also the style and the dashboard type or the framework to use when creating the layout.

2. Title of the dashboard: This is the title given to the dashboard when saving it. When creating a new dashboard, you will see the name as New Dashboard. This means that you haven't saved your dashboard or you just gave it the title of New Dashboard, and let me tell you, that's not the most creative title or name to give to a dashboard.

3. Perspectives toolbar: You can select which panel you want to display in the perspective panel area.

4. Perspective panel area: Depending on the selection you make in the Perspective toolbar, you will get the layout, components, or data sources panels.

5. Properties panel area: For each one of the selections in the elements of the perspectives panels, you will have at least 2 panels, one for the existing elements and another with the Properties available for the existing elements.

6. Help and documentation toolbar: Here you have two options: the first one will display a brief description of the tool, with information about the installed version. Selecting the second option will give you the same dialog, but it contains documentation and some buttons where you can find some basic documentation and links to the CDE tutorial and sample demos you can buy from Webdetails/Pentaho.

Let's now start to look each of the sections. There are two sections that are really simple to explain and understand, so let's start with those two.

Operational toolbar

The main toolbar will show you the options in the following image:

New

This allows you to create a new dashboard. It will do the same operation as the New option in PUC.

Save and Save as

The behavior of Save and Save as… is the same as you get in all other applications. When clicking on Save for the first time, you will get a dialog where you need to specify the folder where you want to save the dashboard, and also specify the following:

· Name: The name of the files in the dashboard. This is the name to use when saving the file in the repository.

· Title: The name that identifies the dashboard. This is the name that will be displayed when browsing the Pentaho repository and the name that will be displayed in the browser when editing or rendering the dashboard.

· Description: This is just some more information that will be added to the metadata of the dashboard.

· Dashboard/Widget: You can select between a dashboard or a widget, but let's just focus on saving the files as dashboards. Nowadays, we will see better alternatives to widgets, but anyhow, we will cover widgets later on in this book.

After selecting the folder in which you want to save the file, and adding the file name, you are able to click on the OK button, and save the file successfully.

When clicking Save for a dashboard that has already been saved, this will overwrite the existing files. Save as... will have the same behavior as saving a new dashboard for the first time. The following image shows the dialog you will get:

When saving a CDE dashboard, three files are written to the repository, all of them with the same name but with different extensions:

· WCDF: This is saved as an XML file, containing the main information about the dashboard such as the title, description, author, style, layout type, and a flag for RequireJS.

· CDFDE: This is saved using the JSON syntax and will have all the information, keys, and values for all the properties and elements that have been used or are just needed for the rendering. Layout, components, custom code, and query definitions are part of the file.

· CDA: This is also saved as XML with the structure explained in the second chapter. It will have data sources that are defined using the editor. You will see later that we can make the components use the queries that are in another CDA file, which is useful when we are creating multiple dashboards where we have some common queries, or just have a centralized file with all the queries. We can use the editor to create CDA files and define data sources in an easy way, just using the editor to create a new dashboard, but not defining layouts or components. This file is only saved when data sources are defined, otherwise, only the first two files are saved.

Reload

Reload will load the dashboard files again, and all the changes made since the last saved change will be discarded.

Settings

Using the Settings operational button, you will be prompted with a dialog box where you are able to set/change the following options, as shown in the following image:

The options shown in the previous image are as follows:

· Title: This is the title of the dashboard, as defined when saving it.

· Author: This is the name of the author of the dashboard. The only way to change the author is by changing it here in the settings dialog, or changing the WCDF extension file by hand.

· Description: This is the description of the dashboard, as defined when saving it.

· Style: As explained in the CDF chapter, the style is where we can choose from an existing HTML page that will provide similar content for multiple dashboards. When in CDE, there is a dropdown where we can choose from the styles that are available. The one selected by default is the Clean template, but you have three more templates that can be applied, and they are used in the web details documentation and for the Pentaho App Builder dashboard/plugin.

There is also the chance to create new styles, by creating your own templates with similar content that dashboards can have, which is very simple to do. We just need to create an HTML page with content to be presented in all the dashboards using the style. This should be similar to the following example:

<!DOCTYPE HTML>

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<meta name="viewport" content="width=device-width, initial-scale=1">

@HEADER@

</head>

<body>

<div class="dashboardWrapper">Your dashboard will be wrapped by this element

@CONTENT@

</div>

@FOOTER@

</body>

</html>

Defining a new style is just creating an HTML page where we need to add the following strings, which will be replaced by the HTML and JavaScript code needed for the dashboard:

· @HEADER@: This will be replaced by the scripts to include the JavaScript and CSS needed for the execution of the dashboard.

· @CONTENT@: This will be replaced by the HMTL with the structure defined in the Layout panel and the JavaScript code generated by CDE to run the dashboard, using as a base the components and data sources defined and the components panels.

· @FOOTER@: This will be replaced by some supplementary code to render some content that may be needed for the dashboard.

The styles should be uploaded to the repository and should be placed inside the folder /public/cde/styles. The styles inside the dropdown will have the name of the file, but two files should exist. One when creating legacy dashboards, not using RequireJS, and another when using RequireJS. The file name containing the style to be applied when using RequireJS should be appended by the text Require. For instance, create an HTML page with the name customStyleRequire.html containing the previous code and upload it to the folder /public/cde/styles folder. By creating your own styles, you can add content that will be used in all the dashboards where the style is applied.

Tip

Refresh the CDE plugin

When uploading files into the folder /public/cde/*, we should refresh the CDE, and to do this, you need to make a call to the following URL: http://<server>:<port>/pentaho/plugin/pentaho-cdf-dd/api/renderer/refresh. This call will refresh the CDE, and all the content added to that folder will now be included in the CDE editor and will be available when rendering the dashboards.

· Dashboard Type: This will specify which framework to use when creating the layout. There are three options available:

· Blueprint: This creates a dashboard using the Blueprint CSS framework. You can get some more knowledge on their website: http://www.blueprintcss.org.

· Mobile: This creates a dashboard using the JQuery Mobile framework. If you pretend to use it, you can get some more knowledge at their website by using the following URL: https://jquerymobile.com/.

· Bootstrap: This creates a dashboard using the Twitter Bootstrap framework. You could go through all the documentation, but you can just start by reading about the grid system, the concept that you really need to know to create the layout for the dashboards.

The following URLs are a good start: http://getbootstrap.com/css/#grid and http://getbootstrap.com/css/#responsive-utilities-classes

In this book, we only cover Bootstrap, which is selected by default. This is the right one to use when building responsive dashboards. Just by looking at the names, you could think that to build a mobile dashboard, you should use the Mobile option, but that's not really true. You can use Bootstrap to build a desktop and/or mobile dashboard, something that would not be fully true when using the mobile framework. If you build a dashboard with the mobile framework, it won't become a desktop dashboard.

· RequireJS Support: This checkbox will be used by CDE to know whether the code should make use of RequireJS when generating the CDF code of the dashboard. When the box is checked, CDE will generate the code using RequireJS. When rendering a dashboard with this option checked, by default, CDE will require a collection of the base modules. This way, the developer does not need to specifically require them when building custom JavaScript code. By default, the loaded modules are:

· Logger: This is represented as Logger

· JQuery: This is represented as $

· Underscore: This is represented as _

· Moment: This is represented as moment

· Cdo: This is represented as cdo

· Utils: This is represented as Utils

The perspectives toolbar

You should know that there are three perspectives and a preview button, as shown in the following image. The other three buttons or perspectives are as follows:

1. The layout perspective: This is used to switch to the layout perspective of the editor. You should use this perspective to define the layout of your dashboard. When clicking the layout button, you will get the available and used layout elements. The properties panels will change according to the element selected, displaying all the available properties.

2. The components perspective: This is used to switch to the components perspective of the editor. You should use this perspective to define the components to apply to the dashboard. When clicking the components button, the perspective and properties panels will change accordingly and will show you the available components you can use for your dashboard, and also the ones already added to the dashboard.

3. The data sources perspective: This is used to switch to the data sources perspective of the editor. You should use this perspective to define the data sources to be saved on the CDA file that will be directly related to the dashboard you are working on. When clicking the data source button, the perspective and properties panels will change accordingly and show the data sources available to be used, and the ones already defined.

4. Preview the dashboard: This is the rightmost button, and it allows you to preview the dashboard. When pressed, you will get a new dialog, with the dashboard you are working on inside of it. This way, you are able to test the behavior and see how the dashboard would look.

We will now cover each of the perspectives, except for the last one, as there is nothing else to cover there, so we will give you some more details on the first three.

The layout perspective

When clicking on the layout perspective button, you will switch to the layout perspective and get two panels, as you can see in the following image:

1. Layout toolbar: This toolbar is used to create the elements in the layout structure. (See panel 1 in the previous image.) When clicking on the buttons, you will be adding or removing the element, and these changes will be reflected in the layout structure panel.

2. Layout structure: In this panel (see panel 2 in the previous image) of the layout perspective, will have represented all the elements that are part of the layout of the dashboard. Whenever you click on an element, the Properties panel will be updated and will show you the properties available for the selected element.

3. Properties: This panel (see panel 3 in the previous image) shows you the available properties of the selected element in the layout structure, and depending on the type of element, the properties may vary. This is where you can see the value for each of the properties or just set their value.

The Layout toolbar

The toolbar that becomes available when you are in the layout perspective is like the following image. Depending on the elements you have selected in the layout structure, you may find some of the buttons enabled or disabled:

In the image given, we have labelled each button as per their corresponding elements. Now let's look at what each of the buttons is used for:

1. Save as Template: You can save the dashboard you are working on as a template. When clicking the button, you will be presented with a dialog like the following image, where you can set the name for the template and the title:

The name and title will be used as previously explained when saving a dashboard. File Name is the name of the file inside the repository and Title is the text that will be displayed when you are later choosing which template to use.

When saving a template, you should also specify whether you want your template to include components and/or data sources within the template. When these options are checked and when using the template, you are saving all the components and data sources included in the new dashboard. But when those options are unchecked, you will include only the layout of the template in your new dashboard, and nothing else. This will not add new elements to the layout structure.

Tip

Templates are saved inside the Pentaho repository

The templates you are saving will become available in the repository inside the /public/cde/templates folder.

2. Apply Template: Clicking this button will give you a dialog where you can choose from the available templates, as shown in the following image:

You can choose from the available templates already included in CDE, or you can select from ones you have created and saved. If you want to select one of your own, you should click the My Templates button, available at the bottom-right side of the dialog. When selecting this option, you will see the templates you have saved.

To select a template, you only need to click on the template you want to choose and click the Ok button.

3. Add Resource: You can add resources, JavaScript, and CSS files to your dashboard as a code snippet or as an external file.

To add a resource, when clicking a button, a dialog box will pop up, similar to the one in the following image. You must select from the dropdowns if you want to include CSS or JavaScript code and if the code will be added as an external resource or code snippet:

When adding resources as a code snippet, a line referring to the resource will be added in the layout structure. The properties that become available for this element are as follows:

· Name: This is the name you want to use to identify the resource in the layout structure.

· Resource Code: When clicking on the button available in the property, a dialog will be presented where you can write, delete, and edit your code. You just need to click Ok or Cancel to confirm whether you want to add it to the dashboard.

· Type: This is the type of the resource, which is automatically set when adding the resource. It will have the value selected in the type dropdown when adding a new resource.

When adding resources as a code snippet, a line referring to the resource will be added in the layout structure. The properties that become available for this element are:

· Name: This is the same as the previous.

· Resource File: In this property, you can set the URL of the resource, or use the buttons available. The first button will open a new dialog that will allow you to select the file to include, and the second one will allow you to edit the code that is inside the file. When editing the content of the file, you will have three available buttons: Save, which can be used to save the changes in the file, Close, which can be used to close the dialog without saving the changes, and Open Tab in new Tab/Window, which will open a new tab in the browser with the editor that allows you to change the content of the selected resource file.

· Type: This is the same as the previous.

When adding a code snippet, the code will be part of the dashboard when it is saved, and this is because it will be saved inside the CDFDE file. When using an external file, the reference to the file will be added to the dashboard.

When generating the code for the dashboard, CDE will also include it as a RequireJS module by using the require functions that incorporate its location on the server. Later during the execution of the dashboard, the file will be requested to the server, and the code will become available inside the require context of the dashboard.

When adding your code as a code snippet, it will be included inside the dashboard module and will become available inside the dashboard object.

When you are including a resource that uses an external file with your code, you need to define a RequireJS module, because the dashboard will require it. It will then become available in the dashboard module. You can define the code in your file as follows:

define(function() {

var myObj = {

name: "Joe",

sayHello: function() {

return "Hello " + this.name}

};

return myObj;

});

or

define({

name: "Joe",

sayHello: function() {

return "Hello " + this.name }

});

This way, you are able to access the code in the dashboard module. Here you can set the name of the resource using the same name as the file, and this will be used to define your module name. Let's suppose you named the resource myModule and the name of the file is myModule.js. You can later use this code inside your dashboard. For instance, you would set the following code in the Expression property for a text component:

function f() {

this.placeholder().text(myModule.sayHello());

}

You may also want to include a third-party resource to be used in your dashboard. If they are built as RequireJS modules, you just need to follow the previous instructions. Most of the JavaScript frameworks and libraries have this support, so you should look for it. If the resource is not exposed as an AMD module, you'll need to develop AMD support for it.

You may ask: What option should I use: code snippet or external file? Well, this depends on what you want or are doing, but I always prefer to have all the code in external files. One of the reasons for this is that when you are saving a dashboard, CDE can change the order of the elements inside the saved file, and this will cause problems with version control, especially when you are working as part of a team working on the same files. It will be painful to solve conflicts just because of a small change in the CSS.

Of course, it will be easier to deploy the code to another server if you have the JavaScript and CSS code as snippets, where you just need to worry about deploying the dashboard files, because the code will also be there.

4. Add Bootstrap panel: This is used to add a Bootstrap panel to our dashboard, like the examples available at: http://getbootstrap.com/components/#panels. If clicked, it will add a parent element containing three child elements. The parent element is a Bootstrap panel, where you can change the properties, and the child elements are panel header, panel body, and panel footer. You can change the properties available for these elements, but you can also add more elements as rows, columns, freeform, and HTML inside each one of these child elements.

For the parent element, identified by the type Bootstrap Panel, the properties that become available are:

· Name: This will be the unique identifier of the HTML element that is going to be created by CDE and used in the dashboard to render elements. This will correspond to the id property of the HTML element being created.

· Height: You can specify the height of the panel, but usually we let it be dynamic and let it be larger or smaller depending on its content.

· Corner: Let's consider this property deprecated. It was used in older versions of CDE, where it was not possible to use CSS to create a rounded corner. We will not refer to this property again in this book.

· CSS class: When creating the element on the page, CDE will add the values of this property as the values of the class property for the HTML element being created. This will allow you to use your own CSS classes and later use them when defining the CSS for the dashboard.

· Panel Style: You can select from multiple options available in Bootstrap and depending on the value used, you will have different styles applied to the panel being created. The possible values are: Default, Primary, Success, Info, Warning, and Danger.

Child elements identified by the type panel header, panel body, and panel footer will have the same properties, except for the panel type, which will not be available.

The Bootstrap panel will include the header and the footer, but if you want to exclude them, you can add some CSS to hide them when needed, or delete them by clicking the X button.

Depending on what you are trying to achieve, you may find Bootstrap very useful.

5. Add freeform element: Adding rows and columns will just add DIVs to the dashboard, but using the freeform element, you can specify which HTML will be added. When you click the button, the freeform element will be added to the layout structure, and the properties that become available are as follows:

· Name: This corresponds to the value of the id property for the HTML element being created. CDE will generate a random and unique ID when the value is not set.

· CSS Class: These values will be used as the values of the class property of the element being created. This is used to set your own CSS classes for the element. It can have multiple values separated by a space, like the normal CSS property of the HTML elements.

· Element Tag: Here you should set the HTML type to create. By default, it uses a value of div. This way, you would create a div element, so you should change the default value and write the name of the element to create.

· Other Attributes: Here you can set the name of the properties and the value to be used for these properties. When creating the element, CDE will also add the property/values that will become available in the dashboard. When clicked, the input field of this property will become available as a dialog, where you should set the property name in the option field and the value in the value field. To add more properties, you just need to click the Add button. At the right side of each row added, you will find a minus button, which, when clicked, will remove that row. Click Ok to confirm or Cancel to discard:

6. Let's suppose you added a freeform with properties the same as the previous image. The HMTL code generated by CDE will be as follows:

7. <input id="searchBox" class="inputBox" type="input">

8. You can see that the element is an input type just as specified in the Element Tag property, the id is the value set in the Name property, the class is inputBox as the value of the CSS Class property, and finally, the type property is input as the key value set on the other attributes.

9. Add row: Use this button when you want to create a Bootstrap row. A Bootstrap row is just a div element with a class value of row. This way, the dashboard will use the Bootstrap framework and apply the rules defined for the grid system. Following the best practices of Bootstrap, components should be rendered inside columns and not directly on rows. As referred to previously, you can find more information at http://getbootstrap.com/css/#grid. This means that you should always have at least a column inside the row, except for some special cases where you have the need to create a row. The properties that become available are:

· Name: This corresponds to the value of the ID property for the HTML element being created. CDE will generate a random and unique ID when the value is not set.

· Height: This is used to set the height of the HTML element. It should be left blank whenever possible.

· CSS Class: These values will be used as the value of the class property of the element being created. It is used to set your own CSS classes for the element. It can have multiple values separated by a space, like the normal CSS property of the HTML elements.

· Background Color, Corner, and Text Align should be set as the CSS.

10. Add column: You should click this button when you want to create a new column to be used by your dashboard. Columns should always be created inside a row element and, not always but usually, used to render the components. If it's a leaf, you always need to set the name, so that we can use the name on the components. When creating a new column, it will become available in the layout structure of the dashboard. The properties are:

· Name: This corresponds to the value of the ID property for the HTML element being created. CDE will generate a random and unique ID when the value is not set.

· Extra small devices, small devices, medium devices, and large devices: These are used to set the width to be used for the column. This is where you should already have some knowledge about the Bootstrap framework, particularly the grid system.

When creating a row using the CSS Bootstrap framework and the concepts of the grid system, each row can go up to 12 columns, scaling appropriately when the viewport or screen size increases. When creating a column, there is a need to include a class such as col-<device_size>-<num_columns_to_span>.

Bootstrap already includes predefined classes that can be used for all the columns spanning from 1 up to 12. So, depending on the device/screen size and the number of columns to span, the CSS rule to be applied can change.

CDE will take care of this for you, you just need to set the number of columns to span, for instance, if you are creating columns that should occupy six columns of the 12 available columns for each row, you just need to set the number 6 for the device size you want to apply to this value. This is why you have these four properties: extra small devices, small devices, medium devices, and large devices, corresponding to col-xs-*, col-sm-*, col-md-*, and col-lg-*, where * is the number of columns you wish to span for the specified device/screen size.

Let's analyze this example. We have created a row that contains two columns. The two columns are named col1 and col2 and use a value of 8 and 4 respectively for each of the columns of the extra small devices property of each column.

The HTML result would be as follows:

<div id="329e160a-625d5a5ds5" class="row clearfix ">

<div class="col-xs-8">

<div id="col1"> </div>

</div>

<div class="col-xs-4 last">

<div id="col2"> </div>

</div>

</div>

By analyzing the generated HTML, we can see that we have a row, the first element that has a uniquely random generated ID, because we haven't set the name for it. Inside of it, we have two child elements: the first column uses the col-xs-8 class and the second one uses col-xs-4, because we used a value of 8 and 4 in the extra small devices:

The layout generated would always span the first eight columns available for the row, and use it for col1 and the span the last four columns also available for the row.

We can also offset the columns by using an additional Bootstrap CSS class col-<device_size>-offset-<num_columns_to_span>. More information can be found on this at: http://getbootstrap.com/css/#grid-offsetting.

Let's suppose you only wanted to have col1 at the right side of the dashboard using only the last four columns. To achieve this result, you would create just one column with the name col1, a value of 4 in the extra small devices property, but also set the Bootstrap class, the next property to be explained, to have a value of col-xs-offset-8. This would give the following result:

Don't forget that by using CSS, you can extend the position, and the look and feel, by using additional media queries, for instance, to include a max width to limit the CSS for a narrower set of devices.

Similar to the use of offset is the use of the responsive utilities classes, available at http://getbootstrap.com/css/#responsive-utilities-classes.

· Bootstrap class: This is a CSS class that will be added to the Bootstrap element. You can refer to the last example of the last property. Here, it is possible to have multiple CSS classes; you just need to separate them with a space, just like when you are defining multiple CSS classes on a HTML element.

· Height: This is used to set the height of the HTML element. It should be left blank whenever possible.

· Background Color, Corners, and Text Align: This should be set in the CSS.

· CSS class: These values will be used as the value of the class property of the element being created. This is used to set your own CSS classes for the element. You can have multiple values separated by a space, like the normal CSS property of the HTML elements.

11. Add space: This is used to create a vertical space between elements of the dashboard. If clicked, it will add an element to the layout structure. The following elements become available:

· Height: This is used to set the height of the separator. This property is mandatory when using this type of element.

· Background color, corners, and text align: This should be set in the CSS.

· CSS class: These values will be used as the value of the class property of the element being created. This is used to set your own CSS classes for the element. You can have multiple values separated by a space, like the normal CSS property of the HTML elements.

You should be able to create the same effect when setting the CSS margin at the top or bottom for the elements you want to separate visually.

12. Add image: Click this button to add images to the dashboard. The properties that will be available for this element are:

· URL: This is the URL to the image ${solution:../../images/logo.png}. It will point to an image of two folders below the current directory of the dashboard, or refer to http://www.pentaho.com/sites/all/themes/pentaho_resp/_media/logo-pentaho-n.png, which will point an image on the Internet.

· CSS class: These values will be used as the value of class property of the element being created. Used to set your own CSS classes for the element. Can have multiple values separated by a space, like the normal CSS property of the HTML elements.

To be honest, I never use this element and always do it in CSS. To do so, I just add a column where I also set a CSS class that will later be used to load the image using just CSS rules. I do this because it is easier to change in CSS and keep a track of the version control system, but also because, using RequireJS, the HTML will be loaded in the first place and then all the components and CSS. If you set the image directly in the layout, the image will appear on the dashboard first rather than all the other components, so you may see the image being pushed from one side to the other.

Also, if you later apply some CSS rules to the image, you will see the image changing only sometime after, when the CSS code is loaded by RequireJS. When changing the CSS, I can do it in any text editor or using the referred Community Text Editor plugin.

13. Add HTML: This should be used to set HTML on your own. You may find the HTML element very useful when setting some static content, or when you can't do it with all the other elements available in CDE, but I find this very hard to believe. The properties that will become available for this element are:

· Name: This corresponds to the value of the ID property for the HTML element being created. CDE will generate a random and unique ID when the value is not set.

· HTML: This is where you can add HTML to include in the dashboard. When clicking the button available on the right side of the property, you will get a dialog you can use the editor to edit the HMTL code and confirm or cancel the changes you have made.

· CSS class: Values will be used as the value of class property of the element being created. It is used to set your own CSS classes for the element. Can have multiple values separated by a space, like the normal CSS property of the HTML elements.

· Font size and color: As we already saw for some other properties, these two should also be set using CSS.

14. Duplicate layout element: Another really useful ability is being able to copy elements, without needing to create all the elements by hand, when you want to replicate structures similar to already existing ones. Selecting one element and clicking the duplicate button on the layout toolbar will create a copy of the selected element and all its children.

15. Delete: Selecting one element and clicking the delete buttons will remove the element itself and all its children. Use this button carefully because CDE does not yet have an undo operation.

Nowadays, can also can change the position of the elements inside the layout structure, and to do this, you just need to grade the element to the position you need. You should take a look at the sample provided with the book and available once you upload them to the repository. You can find this under CTools Book Sample/Chapter 4. You should not expect a really a dashboard running queries, but it's good to understand the capabilities of the layout elements and how to use them.

Considerations when creating the layout of your dashboard

You should have noticed that I placed more importance on some properties than others. This is because some of the properties may be deprecated, and they are there just to ensure compatibility with older dashboards that were developed with earlier versions of CTools. Another reason may be because of my preference to have all the styles in CSS files.

Let's use the example of the align property, which allows us to specify the alignment for the content inside the element where element is defined. When defining the alignment in the property of the element, it may not work for all the content you have inside, and you would end up having some CSS to align some of the elements. If you set some properties using CDE and others in CSS, you are not being consistent. We should always avoid inconsistency, and I can point you to some other reasons beside consistency: complexity, maintainability, and also very importantly, reusability.

When developing dashboards, the layout can get a bit complex and you should find a way to build it to make it simple and use a name convention. One way is to find the most correct and simple hierarchical structure, and always set the proper names that can identify not only the element, but also the section and maybe the hierarchy level where it belongs. The name or ID must be unique and never be repeated again. You will see that following one name convention will help you later. A question that you could be asking is: Is the name or ID mandatory for all the elements defined in the layout structure? The answer is no, CDE will make sure you generate randomly unique IDs that will be used for the elements where you are not specifying a name, but never forget that you need to set the names for the leafs, because they probably will be used by a component.

Don't forget that you may be delivering dashboards to a customer or department that may need to make some changes later, so the dashboards should be simple, while always meeting the requirements.

You saw that when defining some of the components using the Bootstrap framework, there are two similar properties: the CSS Class and the Bootstrap Class, so another question you may ask is: What's the difference between the CSS Class and the Bootstrap Class and/or which one should I use? When we add a row/column in the layout panel, CDE will generate two HTML DIV elements. A parent where the value of the Bootstrap class will be applied and a child that will have the value of the CSS Class property. Depending on your goals, you can set both properties. In the Bootstrap Class, you should use the predefined classes available in the Bootstrap Framework, and in the CSS Class you should set your own classes, which you can use later in your CSS files.

When creating rows and columns, CDE always generates DIV elements for your page. The freeform and the HTML elements allow you to create different types of elements in your page. Let's suppose you want to create an input element—you don't have any button in the layout perspective to create these kinds of elements, so the only way to do so is to use freeform elements or create your own code for the HTML structure.

Regarding this matter, one question that I already asked myself was: When should I use freeform or HTML elements? I believe that the answer is use what you prefer, but note that when creating a structure using freeform, you can just keep expanding or collapsing the elements inside the layout panel. You cannot do this when using the HTML element, because you always need to click the edit button on the right side of the element to look at the code. However, it will be faster and more flexible if you define it by hand. To be honest, you will be fine using one or the other, you just need to see what you feel most comfortable using.

Tip

The freeform element (layout and component)

We will look at the usage of the freeform component during the next chapter, just to avoid getting confused later by establishing a relationship between the freeform component and the freeform element. They both have the same goal, which is giving more flexibility, but they have different applications. The freeform element is used to provide the flexibility to introduce a different element in the layout, and the freeform component is used to create content that can be rendered inside the other elements of the layout, which could be the freeform element or not.

When editing the content of a resource that was added as an external file, and when we're using the CDE button available in the Code File property, CDE will use ACE, a web-based code editor. It has the ability to do syntax highlighting and is a great help when reading or writing code. You also have a bunch of shortcuts that are very useful, and you can learn more about these at the following web page: https://github.com/ajaxorg/ace/wiki/Default-Keyboard-Shortcuts. Now you can see some of the shortcuts I often use:

Using Bootstrap to create a responsive dashboard

Creating a responsive dashboard is simple, but don't forget that the components must respond to the changes and not only the layout. It is very important when creating CSS rules that you always use relative widths values and never static values. By default, almost all the components can adapt to changes in screen size, and that's because the CSS which has been included, except for the charts that need some extra code to readapt their size when changes happens to the dashboard. CCC charts, the charts used by default in CDE, are not yet responsive. I will explain this and give you the source code later to make it possible, but for now let's focus on the layout. This can make your dashboard look good and be usable on all device sizes.

We already saw that the Bootstrap grid system appropriately scales up to 12 columns as the device or viewport size increases, and we can make predefined classes for easy layout options, as well as powerful mixins to generate more semantic layouts. But how does Bootstrap do this? Bootstrap uses media queries and some predefined classes we can use to leverage the process, but there are some Bootstrap rules that must be followed, which are as follows:

· Rows must be placed within .container (fixed-width) or .container-fluid (full-width) to get the correct alignment and padding, and by placing all the elements within a .container automatically will take care of alignment and padding.

· Content should be placed within columns, and only columns may be immediate children of rows. We must be careful to say where the components are rendered, so always do this in columns. CDE will take care of applying the correct row and colclasses, but the col classes will be set based on the device size and span value.

· For each CDE column element, we need to specify how many of the 12 columns available we will span. When more than 12 columns are placed within a single row, each group of extra columns will, as one unit, wrap on to a new line. We should play with this and the device size to make the layout of the dashboard responsive.

· Grid classes are applied to devices with screen widths greater than or equal to the ones where we had set values. Values set in classes for larger devices will override the values of smaller devices; therefore, applying a value on Medium Devices to an element will not only affect the style on medium devices but will also affect large devices, if and only if a value for the Large Devices property value is not set.

For instance, if you set two columns of a row to have the following properties/values:

Extra Small Devices: 12

Medium Devices: 6

What you will get is that it will display two columns on different lines for Extra Small and Small devices and will get the two columns side by side in the same line for Medium Devices and Large Devices. Setting the right values for these four properties is really an important task when building your responsive dashboard.

Another consideration when building a responsive dashboard would be using utility classes to hide some layout components. It should be used as previously covered in this chapter when talking about offsetting columns. To show or hide layout elements in the dashboard, we can set a class visible-<device_size>-<display_rule> and/or hidden-<device_size>, where <device_size> should be set as xs, sm, md, and lg (for extra small, small, medium, and large devices/screen sizes), and <display_rule> should be set asblock, inline, or inline-block, the last one set only for visible. The display rules will make the CSS apply similarly to the CSS display property.

Let's suppose, for instance, that we have created a row that contains three columns. The three columns are named col1, col2, and col3:

· Should be pulled to different lines, each with the full size of the screen, when on extra small and small devices

· Should be seen side by side on medium or larger devices

· The col2 column should only be seen when on medium or larger devices

· The height should be 15px and background colors should be red, green, and blue for col1, col2, and col3 respectively

To accomplish these requirements, you need to set a value of 12 in the Extra Small Devices property for all three columns (col1, col2, and col3), and a value of 3 in the Medium Devices property. In the property of the second column (col2), you should also set a value of hidden-xs hidden-sm to hide the element for those screen sizes. You also need to add the class emptyBox in the CSS class for all the columns and classes red, green, and blue in the CSS class for each one of the corresponding colors. Don't forget that the classes should be separated by a space.

The resulting HTML would be as follows:

<div id="responsive" class="row clearfix ">

<div class="col-xs-12 col-md-4">

<div id="col1" class="emptyBox red"></div>

</div>

<div class="col-xs-12 col-md-4 hidden-xs">

<div id="col2" class="emptyBox green"></div>

</div>

<div class="col-xs-12 col-md-4 last">

<div id="col3" class="emptyBox blue "></div>

</div>

</div>

If you build a dashboard with the layout set this way, you will get a responsive layout for your dashboard. Please take a look at the sample, which we provide with this book, and edit it. You can find the dashboard files in the responsiveDashboard folder within the chapter samples. After opening the dashboard, change the browser size and you will see the magic happening.

Considerations when building responsive dashboards using CDE

For me, it's very important to know the difference between the responsive and adaptive/responsive design concepts. Both concepts attempt to optimize the user experience across different devices, making the necessary adjustments for different viewport sizes, resolutions, and usage contexts, and I really like the Mozilla definition for these two concepts:

"Responsive design works on the principle of flexibility. The idea is that a single fluid design based upon media queries, flexible grids, and responsive images can be used to create a user experience that flexes and changes based on a multitude of factors. The primary benefit is that each user experiences a consistent design. One drawback is a slower load time."

"Adaptive design is more like the modern definition of progressive enhancement. Instead of one flexible design, adaptive design detects the device and other features, and then provides the appropriate feature and layout based on a predefined set of viewport sizes and other characteristics. This can result in a lack of consistency across platforms and devices, but the load time tends to be faster."

It is my opinion that you should not choose between using one or the other; you should use the advantages of both concepts and avoid the disadvantages of both concepts, and this is possible when putting together the Bootstrap framework's capabilities and the dashboards and components lifecycle. I believe this means having a layout that uses responsive concepts and components; the more adaptive concepts would make the perfect dashboard, where you can have only one dashboard for all devices and screen sizes, but just execute or change the behavior of the components depending on the device. This way, we can have the advantage of a unique dashboard for all devices and at the same time control what's being executed so that we can have better response times and avoid the possible lack of consistency across platforms and devices.

Desktops can have better processing capabilities and a lot more memory than mobile phones. When building a dashboard that will be used for various platforms, screen sizes, and even hardware capabilities, we need to be cautious. There are some points that we should consider:

· Mobile dashboards may face some hardware limitations. Processing and memory capabilities are not the same when comparing mobiles and desktops. When using a huge amount of points to represent, CCC Charts may be a bit heavy; anyhow when using a mobile phone the user would not get the best look and feel if you are trying to represent charts that become too tight on the screen. Here you have two options: using the same dashboard, you may use preExecution of the component to control if the chart is rendered on a mobile, or change the parameters and/or the query itself so that you can have an optimized visualization solution.

· You need to adapt the visualizations for the device/screen size. Similar to the last point, you can use the preExecution function of components to prepare the execution of the component. Depending on device/screen size or orientation, you can write some code to change the behavior of the component. For instance, if you have a bar chart, when on a mobile, you could change one property of the chart to have a horizontal bar chart instead of a vertical bar chart. Please refer to the following web page: http://dev.w3.org/csswg/cssom-view/#the-mediaquerylist-interface.

You place the following code in the preExecution of a CCC BarChart, and you will get a chart with vertical bars for screens greater than 840, a chart with horizontal bars if the screen size is between 600 and 839, and not get a chart at all if the screen size is less than or equal to 600:

function f() {

var mq = {};

mq['<=600'] = window.matchMedia("(max-width: 600px)");

mq['<=840'] = window.matchMedia("(max-width: 840px)");

if (mq['<=600'].matches) {

return false;

} else {

if (mq['<=840'].matches) {

this.chartDefinition.orientation = 'horizontal';

}

}

}

You should learn about and make use of media queries, using CSS or JavaScript, as they are important when using adaptive and responsive concepts. It may also be important to reduce the number of components being rendered.

· Mobile network communications are usually slower than wired networks, so avoid making lots of requests and requests that need a big portion of data when transferring from the client to the server side or the opposite. This is also the case when building the desktop version of a dashboard; we should be more careful when doing it for mobiles.

· Put your images on a diet, or even avoid using them. Just use icon fonts whenever you can. You have two options available to use in CDE/CDF:

· http://getbootstrap.com/components/#glyphicons

· http://fortawesome.github.io/Font-Awesome/

· Use relative sizes whenever possible. For instance, when you set a static width for an element, the element will not respond to the screen and orientation changes. The parent elements may change, but the element itself would always have the same size. Try to use relative sizes as percentages when setting the width of elements.

· Similar to the changes in the charts, we should adapt the column content to different device sizes. For instance, when applying an add-in to the columns of a table where we want to have a trend arrow (up or down depending on whether it's a good or bad value), we can change the options so we can also see the value. On a mobile, we would need to hide the arrow or the value. That can be achieved doing something similar to what we saw in the section for the charts, or we could do it using CSS Media Queries.

· Be careful with the number/size of the included libraries. When on a mobile (it is also the case for desktops, but needs more attention on a mobile), we already saw that the communications may be slower, so we need to be careful when loading libraries, and just load the libraries and the parts that are really indispensable.

The data sources perspective

When clicking on the datasources perspective button, you will be switched to the data sources view and get three panels and a toolbar, as you can see on the following image:

The four panels shown in the previous image are:

1. The data sources toolbar: This toolbar is used to change the position of the created data sources, up and down, and duplicate or delete them.

2. Available groups and types: This panel shows the available data sources. The data sources types are divided into groups that can be expanded when clicking on the group when selecting one.

3. Available data sources: This is where we can select from the data sources that have already been created, and it can be used by the dashboard and components. When selecting a particular data source, the properties will become available inside the properties panel.

4. Properties: This is where we can change or just get to know the values that will be or were set for the selected data source. Depending on the data source that is selected, the properties may vary, and the displayed properties may be different from data source to data source. We already saw in the second chapter of this book, the CDA chapter, that for different types, different properties are needed.

The data sources toolbar

The data sources toolbar becomes available when you are in the datasources perspective. You will see a toolbar like the following image:

Depending on the position of the selected datasource, you may find some of the buttons enabled or disabled:

1. Move up: This changes the position of the data source, moving it up.

2. Move down: This changes the position of a data source, moving it down.

3. Duplicate: This creates a copy of the data source and appends _new to the name.

4. Delete: This deletes a data source. It will remove the data source from the dashboard and from the available data sources panel.

Creating new data sources

To define a new data source, we just need to select the group of the data source to create and select the type. You will then see, on the right side of the screen, the palette of properties we need/can set to get the selected data source to work.

You already know which data sources types are available and what the properties are used for, as this was covered in Chapter 2, Acquiring Data with CDA. Let's suppose you wanted to create an MDX query. You should expand the MDX Queries by clicking on it, and then select mdx over mondrianJndi. This will create a new empty data source in the Dashboards data sources panel. The advantage of using CDE is that you don't need to know what the data sources types are or the names of the properties available for each one of the properties. Not that this is a disadvantage, but the difference is that CDE will generate a connection for each data source you set. When you are setting the data sources by hand, you can reuse one of the existing connections. If this is the case, CDE will generate a larger file, but at the end, you will notice the difference.

When you click on a created data source, on the right side, you will get a list of properties for the kind of data source you have created or selected. There are some mandatory properties and some other ones that are not. Some of them are common to all the data sources and other ones will just appear for a particular data source type, because they would not make sense for other types.

Tip

Automatically generated CDA files should not be edited and changed by hand

You should not edit and change any of the CDA files by hand that are generated when you save dashboards and have data sources defined. CDE will not read the CDA file, and instead will read the definitions that are inside the CDFDE file and always generate a new CDA file when we save the dashboard. This way, you will lose the changes that you make directly on the CDA file that you have changed by hand. Note that this is the case only for the CDA files that are automatically created with CDE, that is, the ones that have the same name as the dashboard. The CDA file is just read and used by CDA, never by CDE.

When you finish creating your data sources using the CDE editor, and after saving the dashboard, you will get a CDA file with the same name as the dashboard. Double-click on the CDA file and the CDA previewer will open. As we covered in the CDA chapter, you can use previewer to test the queries you just created using CDE.

Data sources properties

When creating data sources, you will see some common properties in all or in almost all the data sources you will create:

· Name: This is the name of the data source. This is the name to be used by the components or when selecting the Data Access ID when using CDA directly to run queries, or when using a previewer.

· Access level: This should be used for the query to be accessible from the outside or just for internal use. For instance, data sources that are just to be used on compound queries can be set as Private.

· Parameters: This is used to make queries dynamic. We can add parameters to be used inside the queries, and this parameters will be replaced during the execution. Parameters are very important, so don't forget to also set them in the query. It's also important to set the default values, because these are the values that will be used when previewing the results using the CDA previewer. You can change the parameters values in the previewer when using the CDA previewer or they will be overwritten by the parameters from the dashboard when we also establish the mapping on the components that will use the same data source.

· Calculated columns: This is used to set some simple formulas to create new columns based on calculations using other columns.

· Columns: Here you can change the header for your columns. You just need to add an element using the add button in the pop-up window and add the index of the column (starting from zero) and the name for the new column.

· Output options: This can be used to change the order to repeat a column after getting the results from the source and before sending the results back to the dashboard. You should specify the index of the columns starting from zero.

· Output mode: This should be used together with output options. The index of the columns specified will be included or excluded from the dashboard. The possible values are Include or Exclude.

· Cache keys: These are the keys that will be used to manage the cache segments where we are writing and getting the results from.

· Cache duration: This is the length of time that the cache will store the last results.

· Cache: This tells you whether the cache is enabled or disabled. True will enable it and false will disable the cache. Queries will be cached or not using this method.

Some other properties may be found just for some of the data sources types. For instance, the Query property is available for most of the queries, but not for all of them. When using a kettle data source you will not see a query property, but you will see the variables property. This is used to make the matching between the parameters and the variables in the kettle transformation. When the name of the parameters is the same, you don't have to set the matching, but when the name of the parameters is different from the variables defined in the kettle transformation, you need to set it.

JNDI is another example of a property that would appear in multiple data sources types, but not all of them, and allows distributed applications to look up services in an abstract, resource-independent way. At least will become available for SQL and MDX queries. For MDX queries, you will also get the Mondrian Schema to set the name of the schema to use. For both cases, you will see the property query.

Regarding the explanation here, you also can refer to the CDA chapter, the second one.

The components perspective

When you have the layout of the dashboards and the queries ready to get data using parameters, it's time to set the components.

To add components, you need to go to the components perspective. When you click on it, you will be switched to the components perspective and will see three panels, as shown here:

1. Layout toolbar: This toolbar is used to manipulate the elements you can see in the dashboard components panel.

2. Components groups and types: Here you can select the element type that you want to add to the dashboard. In a wide view, we can classify the components in three different categories:

· Visual Components: These are the components that are displayed in your dashboard, including tables, charts (such as lines, pies, bars, stacked, heatgrid, waterfall, and so on), selectors (such as dropdowns, radio buttons, date pickers, or buttons) and a lot more. There is a new component, called template component, where you can build your templates that will be rendered using the model, which is built automatically from the query results or that you can build on your own.

· Parameters: These represent values that can be shared by the components. The parameters are crucial for the interaction with the dashboards. They should be set in the input components, and set as listeners in the components that need to be updated when the values are changed.

· Scripts: These are pieces of JavaScript code that let you customize the look and feel or behavior of other components, and add code to be executed before or after the execution of the dashboard.

3. Dashboard components: This is where all the elements that are part of the dashboard will be represented. Whenever you select an element in the properties panel, some parameters will be updated, and will show the properties available for the selected element. When you add more components, parameter(s), or scripts, you will see them in this perspective panel.

4. Properties: This panel shows you the available properties of the selected component, and depending on the type of element, the properties may vary. This is where you can see the value for each of the properties or just set their values.

The components toolbar

This toolbar becomes available when you are in the components perspective and it is shown in the following image. Depending on the elements you have selected in the dashboard panel, you may find some of the buttons enabled or disabled:

1. Move up: This changes the position of a component, moving it up.

2. Move down: This changes the position of a component, moving it down.

3. Duplicate: This creates a copy of a component and appends _new to the name.

4. Delete: This deletes a component. It will remove the component from the dashboard and from the panel.

Dashboard parameters

You saw that we can create parameters using the components perspective. We already covered this, but it's never too much to refer it again. There are two different kinds of parameters, the kind that are set to be used by the queries and the kind that are set to be used by the components in the components. You just need to establish a matching between both the dashboard and query parameters and pass the values stored in the dashboard parameters to the query parameters. To do so, you should use the parameters property available in almost all of the components.

To create a parameter in the dashboard, you need to be in the components perspective and choose the right type from the generic, in the Components Groups and Types section. When expanding this group, you will get three different parameters to use. The difference between them is the way you set the default value, because at the end you are just setting a JavaScript variable, so the big difference is the value you are setting for the first time.

· Date parameter: You should name the parameter and set a property date value. The available options here are: Today, Yesterday, One week ago, One month ago, First day of month, First day of year, or Pick date.

· Custom parameter: Here you should set the name and JavaScript code, and this way you will have all the flexibility you need. You may set a number, a string, a Boolean, a date, a function, or whatever you need, just by setting the JavaScript code to do so.

· Simple parameter: For this, you should set the name and a default value that will always be set as a string. Each value you may set will always be interpreted like a string. It's really simple to use, but be careful when using it, because if you're setting it to true or false, it will be set as a string, so it will not be interpreted like a Boolean value. Comparing a Boolean and a string that has a Boolean string inside it is not the same when using JavaScript, so be cautious.

For me, it's always a good idea to set a custom parameter and just ignore the other two types.

You should have noticed that we haven't yet talked about the bookmarkable property that is in the parameters. This is a property where you can set a True or False value. If you want to open a dashboard on a particular state/selection, you can use bookmarkableparameters. When you call the dashboard using the URL, you can pass some values into the parameters and make those the values to be used for the parameters, which can make the dashboard work with a particular selection of values.

You will also notice, when using bookmarkable parameters, that your URL changes based on the new selections in the dashboard, so you can send the link to another person in the company and when that person opens the dashboard, they will see what you are seeing.

So, the bookmarkable parameters are used to accept values that come from the URL when requesting a dashboard. If you are expecting the values of a parameter to come from the URL, you should set the parameter as bookmarkable. You can later specify the values for the parameters of the URL, and those values will be automatically used to set the value of the parameter. For instance, if you just created a parameter called country and checked the box for bookmarkable, when calling the dashboard, you can just call a line, like in the following example. After the name of the dashboard or other options, you should add the following:

&bookmarkState=%7B"impl"%3A"client"%2C"params"%3A%7B"country"%3A"Portugal"%7D%7D

If it's decoded, you should add the following:

&bookmarkState={"impl":"client","params":{"country":"Portugal"}}

Appending this example code to the URL of the dashboard with a parameter named country will display a dashboard with values for the specified country, in this case, Portugal.

Scripts

You can also add some code to your dashboard using scripts. A script is just a JavaScript function or part of code you can add to the dashboard that will be executed at the beginning of the rendering of the dashboard, or called later as a regular function in JavaScript.

To add a script, you should expand the script group in the components groups and types panel that is available in the components perspective. You just need to click on the function component. This will make the script component available in the center panel, and the properties that need to be set are as follows:

· Name: This is the name you want to give to this element. The name is just an identifier for your own use.

· JavaScript code: This is where you will place the code that you need to include in your dashboard.

Visual components

The last type of components category is the visual components category. There are a lot of groups that belongs to this category—pretty much every group that is not script or generic is a visual component.

When looking at the groups and trying to find some logic, you will most likely be disappointed and you have a good reason to be. To be honest, I think anyone will be able to find the true logic behind the grouping as it is right now, but I also think and truly believe that Pentaho/Webdetails will take care of it and create some real logic there. Well, there is a group where the name is really informative, and that's the selectors group.

To add a visual component to the dashboard, you should act as for the last two categories, you need to expand the groups and types of available components and then click on the component you want to use.

Visual Components should only be set when you have the necessary layout elements and queries ready to be used, because to properly set a component we really need to specify values for some mandatory properties. There are some properties, likedatasource and htmlObject, which are common for most of the components. We already covered these common properties during the CDF chapter, so you should already be familiar with them. Anyhow, let's do a recap:

· Name: This is the unique identifier of the component inside the dashboard.

· Listeners: This will accept an array of string with the name of the parameters of the dashboard that triggers the component update. This array is crucial in the iteration between components. Here you should check the parameters that will trigger the update of the components when the values of those same parameters are changed by the fireChange function. If you remember, this is the function that can be called using your own code, or automatically called by a particular type of component. Suppose that you have a component that needs to be updated when selecting a value from a dropdown, and then you need to check the name checkbox in front of the parameter whose value will be changed by the dropdown, which is also another component. When clicking on the listener's property, you will get a list of names that will correspond to the dashboard's parameters created in the dashboard.

· Data source: This is the name of the data source you may have created in the data sources perspective. When typing the name, you will get an autocomplete list of values, that is, the names of the already created data sources. You can also click the bottom cursor arrow to get a complete list, before you start typing. When you type, you may be excluding some of the available values.

· Parameters: This accepts an array of arrays, where each array will have the name of the parameters of the query and the parameters of the dashboard with the value to be used. You already saw that we may have parameters defined in the query and in the dashboard. This is where we make the mapping between them in the component. You can have as many rows as you need for each component, and for each row you will specify the name of the parameter of the dashboard on the right side, and the name of the query parameter on the left side. What will happen is that the component will request the execution of the query defined in the data source, and send the values of the parameters that are in the dashboard to replace the parameters that are in the query. This way, the same query can get different results. Just don't forget that the parameters overwritten in the query are the ones where the matching is established, not for any other. Make sure the matching uses correct and created parameter names, otherwise you will not get the expected results, or you will get errors. To avoid this kind of error, you can use the same name for the parameters of the dashboard and for the query, but you will need to define the mapping between them anyhow.

· Parameter: For components where user input is required, this is where you set the name of the parameter where a value will be stored for later use. This is different from the last one, because this is where you are saying what the parameter name is where the values are stored, and not to be sent to the query. It is very important to know the difference between a parameter and parameters. You will find a parameter in the components that are under the group Selectors. The parameter should be set with the name of where it will be stored when the value is changed. In the same components, you will be able to get values to use from a query and you may need to pass some parameters to the query, so for that purpose you should use parameters. For this reason, you may need to set both, but definitely, where you have a parameter property, you should always set the name of the dashboard parameter you already created.

· htmlobject: This is the name of the layout element that you defined using the layout perspective. It's the ID of the HTML object, which will be the wrapper of the component's contents. The iQuery element can be reached by calling a method from inside the component using this.placeholder(). For instance, it can be used inside preExecution or postExecution.

· priority: This is the priority of the components' execution, defaulting to 5. The lowest priorities have the highest priority of execution. Components with the same priority will be executed simultaneously.

· executeAtStart: When set to false, the component will not execute at the start of the dashboard, but it can be updated as soon as one of its listeners has changed.

· preExecution: This accepts a function that will be executed, which can happen in three different ways: at the beginning of the dashboard, when there is a change in a parameter in the list of listeners of the component, or when directly calling the update function of the component.

· postFetch: This accepts a function with an argument that will have the object with the result of the query. As already described in last chapters, that object will be composed of three properties: metadata, where the column's name and type are described,resultset, where you will find a multidimensional array with the results, and queryInfo, with the number of rows in the result.

· postExecution: This accepts a function that is called after the rendering/drawing of the component. The function can be used for you to manipulate the DOM or perform some operations that you can only do after the rendering of the component.

In some cases, there are also two more functions on the components, the ones where user input is required. You can see it like the ones that can act as filters. For instance, when using a select component that would be rendered as a dropdown, when you change or select another option in the dropdown, it will automatically call a fireChange (which changes the value and notifies the components that are listening to the parameter that you set in the parameter property) between the executions of the following functions. Those properties, where you can add a function with the code to be executed before and after the parameter value changes, are as follows:

· preChange: This accepts a function that is called before doing the fireChange to the parameter. You can verify whether it's a valid option and return another value, one that is going to be set in the parameter. If not returning a value, the selected option is used.

· postChange: This accepts a function that is called after the fireChange to the parameter. You can use this function to execute after confirming the choice. Let's suppose you want to generate another value/parameter based on the choice the user made. Here you are able to do so by adding your own custom code.

For further information or reference, you can always review the CDF chapter.

The remaining properties are more specific to the type of component that you are using. For example, when using a chart, you will see properties that are not available for a table, or when using a table you will not get properties that you would get when using a template component. In the next chapter, I will start teaching you about how to use the most important components, so that's the right place to talk about these specific properties. This is also the reason why, in this chapter, we will not go into detail about using the components. From my experience of building a dashboard with CTools, the most important ones, and the ones that you should know really well are: select, multi select, date range, multi button, button, table, charts, duplicate, freeform, query, text, duplicate, export popup, map, and the new template component.

Tip

Not all components are everywhere

Note that some of the components may only be available in CDE and not in CDF. If they exist in CDE, this does not mean that they exist in CDF, and if they exist in CDF, they may not be seen in CDE.

As I just referred to, there are more important visual components than others, and to build an outstanding dashboard you really need to know a few of them, and these will be covered in the next chapter. Anyhow, we can provide an overview and a brief description of all the components here:

· Charts

· Others

· Selects

· Community and custom

Parameter, parameters, and listeners, again

When talking about building an interactive dashboard, you need to remember that parameters are crucial. To have a component using the same query but showing different results, we need to use parameters. When defining the data source, we need to say which parameters will be used and build the query with them inside. Also, we need to have the dashboard parameters where the values we want to use when executing the query are.

When setting the component, we need to specify the data source and the parameters properties, among others, but for now let's focus on these two. In the component, the parameters property is where you specify the mapping of the parameters that you have created in the dashboard, using the components perspective, and the name of the parameters in the data source. This way, the component can get different results, depending on the value of the parameters we have in our dashboard.

Listeners are also crucial. The dashboard parameters will store the value that we want to be used by the queries. When the values inside the parameters are changed, we may need to update some of the components in the dashboard, but for that, the components must be listening to those parameters so that they can be notified about the changes. To have this in place, we need to add the parameters that will trigger the update on the listeners of the component that will be updated on changes.

But how can the parameters be changed and store other values? You can directly call two functions, fireChange and setParameter, or just let it be done automatically by some components, which are available under the selectors group. The type of components inside this group have another property, called parameter, where we need to set the name of the dashboard parameter that will store the value.

When selecting or writing, depending on the component's type, the component will automatically call the fireChange function and set the new value to the dashboard parameter. This way, components listening to those dashboard parameters will be updated, and a query will be executed. Using the matching between dashboard and query parameters, set in the component, the component will know what values should be sent to the query so that the query can use them to get the pretended results.

Putting it all together

Now it's time to build your first dashboard with CTools. These are the steps you should follow:

Create/change the layout: Create the responsive layout for the dashboard using the Bootstrap concepts we covered earlier and add resources (JavaScript and CSS) if necessary:

1. Define the data sources: Create the data sources with the queries and if necessary, include these parameters:

· Add the parameters and components: Create the dashboard parameters, add the scripts (JavaScript code, if necessary), add the components to be displayed in the layout elements, and render the data coming from the queries. You will need to set the necessary properties:

Set the parameter on the components that are in the groups of Selectors

Set the data source and the parameters to use

Set the listeners so that the components can be notified about parameter value changes and be updated

Set all the other properties or, if necessary, some custom code

2. Overall improvements: This step is not mandatory, but it can increase the user experience just by adding some improvements to the components and layout, creating some custom behaviors, and adding some CSS to make the dashboard more attractive. These are just some examples of what you could do in this step.

3. Testing and Quality Assurance: This is where you, but always someone else that did not work on the backend or frontend, if existing should be done by the QA team, making sure the developments meet all the acceptance criteria, never forgetting the performance. Don't forget that performance is also important.

Once you finish step 3, if it's necessary for any reason, such as bugs, acceptance criteria not being met, or unsatisfactory performance, you will need to go through all the steps again and make the necessary changes to ensure the work delivered is really good. The cycle should be like the following diagram:

Creating your first CDE dashboard

Now let's create a dashboard using the concepts covered from Chapter 1, Getting Started with CTools till this chapter. Next you will find some images showing the dashboard design for the desktop and mobile versions:

The dashboard should be responsive, and the layout should adapt to the device/screen size. It will be created as a sample of the SteelWheels sample data. The dashboard has four components: a dropdown selector to select the year for the data to be displayed, and a multi button to select the product lines to display on the table. The table is the three columns with the name, total sales, and percentage. Last, we also have a simple pie chart using the same data used in the table. When changing the selectors, year, and product line, the table and the chart will be updated and fire new queries, so they should be listening to the correct parameters.

Creating the layout

Following are the steps to create the layout:

1. Create a new dashboard using the PUC menu: File | New | CDE Dashboard.

· Start by saving the dashboard in a folder chosen by you.

2. Go to the Settings of the dashboard, check RequireJS Support and press Save.

3. Using the Layout Perspective, add the following elements and properties (between curly brackets) respecting the hierarchy:

4. Row (Name="headerBackground", CSS Class="headerBackground")

5. Row (Name="header", CSS Class="header")

6. Column (Name="userInfo", Extra Small Devices="12", Medium Devices="4")

7. Row (No need to set aby property here)

8. Column (Name="userImage", Extra Small Devices="2", Medium Devices="1", CSS Class="fa fa-user userImage")

9. Column (Name="username", Extra Small Devices="10", Medium Devices="11", CSS Class="username")

10.Html (Html="Welcome: <b>CTools Book Reader</b>")

11.Column (Name="filters", Extra Small Devices="12", Medium Devices="6", CSS Class="filters")

12.Row ()

13.Column (Name="yearFilterTitle", Extra Small Devices="12", CSS Class="description")

14.Html (Html="Welcome: <b>CTools Book Reader</b>")

15.Column (Name="yearFilter", Extra Small Devices="12", CSS Class="yearFilter")

16.Row (Name="middlePanel")

17.Column (Name="dashMiddlePanel", Extra Small Devices="12", CSS Class="dashPanel")

18.Row (Name="overview", CSS Class="overview")

19.Column (Extra Small Devices="12", Medium Devices="3")

20.Row ()

21.Column (Name="productLineFilterTitle", Extra Small Devices="12", CSS Class="description")

22.Html (Html="Click on the product line to toggle")

23.Column (Name="productLineFilter", Extra Small Devices="12", CSS Class="productLineFilter")

24.Column (Name="overviewTable", Extra Small Devices="12", Medium Devices="6", CSS Class="overviewTable")

25.Column (Name="overviewPieChart", Extra Small Devices="12", Medium Devices="6", CSS Class="overviewPieChart")

Row (Name="footerBackground", CSS Class="footerBackground")

Define the data sources

Using Datasources Perspective, add the queries for the dashboard. The queries will all be mdx over mondrianJndi using a JNDI property with the value SampleData and the Mondrian Schema using SteelWheels. The data sources types and properties you need to create/define are as follows:

· As data source type: MDX Over JNDI:

· Name: productLineQuery,

· Query:

· WITH

· SET PRODUCTLINES AS { [Product].[Trains], [Product].[Trucks and Buses], [Product].[Motorcycles], [Product].[Vintage Cars], [Product].[Classic Cars] }

· MEMBER [Measures].[UniqueName] AS [Product].CURRENTMEMBER.UNIQUENAME

· MEMBER [Measures].[Total] AS AGGREGATE(PRODUCTLINES, [Measures].[Sales])

· MEMBER [Measures].[Percentage] AS [Measures].[Sales]/[Measures].[Total]

·

· SELECT

· {[Measures].[UniqueName], [Measures].[Sales], [Measures].[Percentage]} ON COLUMNS,

· ORDER(PRODUCTLINES, [Measures].[Percentage], DESC) ON ROWS

· FROM [SteelWheelsSales]

·

· Output Options: 1, 0, 2

Output Mode: include

· As data source type: MDX Over JNDI:

· Name: yearQuery,

· Query:

· WITH

· MEMBER [Measures].[Years UniqueName] AS [Time].currentmember.UniqueName

· SET YEAR AS UNION( [Time].[All Years] , [Time].[Years].Members )

· SELECT

· [Measures].[Years UniqueName] ON COLUMNS,

· YEAR ON ROWS

· FROM [SteelWheelsSales]

·

· Output Options: 1, 0, 2

Output Mode: include

· As data source type: MDX Over JNDI:

· Name: overviewTableQuery,

· Parameters:

· [productLineParam, [Product].[Trains], [Product].[Trucks and Buses], [Product].[Motorcycles], [Product].[Vintage Cars]

· [yearParam, [Product].[Classic Cars]], [productLineParam, [Time].[All Years]]

· Query:

· WITH

· SET PRODUCTLINES AS { ${productLineParam} }

· MEMBER [Measures].[UniqueName] AS [Product].CURRENTMEMBER.UNIQUENAME

· MEMBER [Measures].[Total] AS AGGREGATE(PRODUCTLINES, [Measures].[Sales])

· MEMBER [Measures].[Percentage] AS ([Measures].[Sales]/[Measures].[Total])*100

·

· SELECT

· {[Measures].[UniqueName], [Measures].[Sales], [Measures].[Percentage]} ON COLUMNS,

· ORDER(PRODUCTLINES, [Measures].[Percentage], DESC) ON ROWS

· FROM [SteelWheelsSales]

· WHERE {${yearParam}}

·

· Output Options: 0, 2, 3

Output Mode: include

· As data source type: MDX Over JNDI:

· Name: totalSalesQuery,

· Parameters:

· [productLineParam, [Product].[Trains], [Product].[Trucks and Buses], [Product].[Motorcycles], [Product].[Vintage Cars]

· [yearParam, [Product].[Classic Cars]], [productLineParam, [Time].[All Years]]

· Query:

· WITH

· MEMBER [Measures].[Year] AS [Time].CURRENTMEMBER.PARENT.Name

· SELECT

· NON EMPTY UNION(Crossjoin({[Product].[All Products]}, {[Measures].[Year]}), Crossjoin({${productLineParam}}, {[Measures].[Sales]})) ON COLUMNS,

· NON EMPTY {Except(Descendants(${yearParam}, [Time].[Quarters]), {[Time].[All Years]})} ON ROWS

FROM [SteelWheelsSales]

· As data source type: MDX Over JNDI:

· Name: quantitySoldQuery,

· Parameters:

· [productLineParam, [Product].[Trains], [Product].[Trucks and Buses], [Product].[Motorcycles], [Product].[Vintage Cars]

· [yearParam, [Product].[Classic Cars]], [productLineParam, [Time].[All Years]]

· Query:

· WITH

· MEMBER [Measures].[Year] AS [Time].CURRENTMEMBER.PARENT.Name

· SELECT

· NON EMPTY UNION(Crossjoin({[Product].[All Products]}, {[Measures].[Year]}), Crossjoin({${productLineParam}}, {[Measures].[Quantity]})) ON COLUMNS,

· NON EMPTY {Except(Descendants(${yearParam}, [Time].[Quarters]), {[Time].[All Years]})} ON ROWS

FROM [SteelWheelsSales]

· As data source type: MDX Over JNDI:

· Name: salesByTerritoryQuery,

· Parameters:

· productLineParam:[Product].[Classic Cars], [Product].[Trains], [Product].[Trucks and Buses], [Product].[Motorcycles], [Product].[Vintage Cars]

· yearParam: [Time].[All Years]

· Query:

· WITH

· MEMBER [Measures].[Sales in Time] AS ( [Measures].[Sales] , ${yearParam} )

· Select

· { [Markets].[APAC] , [Markets].[EMEA] , [Markets].[NA] } on COLUMNS,

· { ${productLineParam} } on ROWS

· FROM [SteelWheelsSales]

Where [Measures].[Sales in Time]

Do not forget to test the queries using the CDA Previewer. Correct any mistakes that you may have made.

Add the parameters and components

Now that we have the layout and the queries ready to be used, go to the Components Perspective and add the parameters, components, and scripts to the dashboard. The components and properties you need to create/define are as follows:

· Generic -> Custom Parameter

Name: productLineParam

JavaScript: ["[Product].[Trains]", "[Product].[Trucks and Buses]", "[Product].[Motorcycles]", "[Product].[Vintage Cars]", "[Product].[Classic Cars]"]

· Generic -> Custom Parameter

Name: yearParam

JavaScript: ["[Product].[Trains]", "[Product].[Trucks and Buses]", "[Product].[Motorcycles]", "[Product].[Vintage Cars]", "[Product].[Classic Cars]"]

· Selects -> Multiple button Component

Name: productLineFilter

Parameter: productLineParam

Multiple Selection: True

Value as ID: False

Datasource: productLineQuery

HTMLObject: productLineFilter

· Selects -> Select Component

Name: yearFilter

Parameter: yearParam

JQuery Plugin: Chosen

Value as ID: False

Datasource: yearQuery

HtmlObject: yearFilter

· Others -> Table Component

Name: overviewTable

Listeners: productLineParam, yearParam

Parameters:

· productLineParam

· yearParam

Column headers: Product Line, Sales Amount ($), %

Column types: string, numeric, numeric

Column formats: %s, $%.0f, $%.1f%

Column widths: 50%, 30%, 20%

Expand on click, Show filter, Info filter, Info filter, Length change, Paginate, Sort data: False

Datasource: overviewTableQuery

HTMLObject: overviewTable

· Charts -> CCC Pie Chart

Name: overviewPieChart

Listeners: productLineParam, yearParam

Parameters:

· productLineParam

· yearParam

Datasource: overviewTableQuery

HtmlObject: overviewPieChart

Height: 150

CrosstabMode: False

Legend: False

PreExecution:

function() {

// this code will reset the size of the chart

if (!_.isNull(this.chart) && !_.isUndefined(this.chart.options))

this.chart.options.width = this.placeholder().width();

// the code bellow will change some of the properties of the chart. will reset the size of the chart

var cd = this.chartDefinition;

cd.slice_innerRadiusEx = '60%';

cd.explodedSliceRadius = '0%';

cd.animate = false;

cd.colorMap = {"Classic Cars": "#005CA7", "Vintage Cars": "#3E83B7", "Motorcycles": "#5C9FBC", "Trucks and Buses": "#66C2A5", "Trains": "#22B573"};

}

Save the dashboard and execute it, so that you can check the result.

Overall improvements

If you follow the previous steps and render your dashboard, you can see that the elements and components are there and working, but they do not have the look and feel you expect or should be happy with.

Just by applying some CSS, you will definitely have an incredible change in the look of the dashboard. We are providing you with the files you can add to your dashboard. To add the CSS, you can go to the layout perspective and add a resource, CSS as an External File, and point it to the following file: /public/Ctools Book Samples/Chapter 4/SteelWheelsSample-1st/resources/css/steelWheels.css. Don't forget that to be able to use it, you should already have imported the book samples. This file contains CSS that uses the CSS Classes that we defined in the layout perspective, and it will make the dashboard much fancier.

You will not notice a problem when rendering on different devices where you are not resizing the window, but when resizing the window, the layout will adapt to the new size, but not the charts. We will cover this later on in a special chapter dedicated to CCC and will explain the following code; for now just follow the instructions to be able to update the charts when the window is resized. Using the Components Perspective, just add a JavaScript Function to the dashboard under the group Script. You can name itdashboard.postInit and write the following code for the JavaScript Code property:

dashboard.postInit = function() {

var chartsTypeToUpdate = ['CccPieChartComponent', 'CccBarChartComponent'];

var chartsToUpdate = _.filter(dashboard.components, function(elem, index) {

return (chartsTypeToUpdate.indexOf(elem.type) >= 0);

});

var resizeChart = function() {

_.each(chartsToUpdate, function(elem, index){

elem.chart.options.width = elem.placeholder().width();

elem.chart.render(true, true, false);

});

};

var throttle = _.throttle(resizeChart, 100, {leading: false});

$(document).ready(function() {

$(window).resize(throttle);

});

};

Now if you save the dashboard and refresh it, you will see that the charts are also updated when the window changes its size. You will find an example of the dashboard after uploading the book samples inside the folder /public/Ctools Book Samples/Chapter 4/SteelWheelsSample-1st. It will also be a good help if you have any trouble creating your own dashboard.

Note

Please check the samples provided for each one of the chapters. The samples for this chapter are under the Chapter 4 folder. There are two simple but complete dashboards, and also another small sample related to the content covered in this chapter. You are able to render them, but also edit them and check the layout, component, and data sources.

Summary

In earlier chapters, you may have got the idea that working with CTools, you would need to write a lot of code, but as you can see, CDE can save you a lot of work, and you can have a dashboard that works with no or almost no code.

In this chapter, you learned how to use CDE to create a dashboard, so at this time you should already know how to build a CDE dashboard. You are now able to create the layout of a responsive dashboard, define the data sources, and then make use of the parameters and components. At this time, you should already know the importance of parameters, the ones from the dashboard and the ones set on the queries, and how to establish the mapping between them. Also, you learned about how to set the listeners so that the components know when to be updated. We gave you a detailed explanation about the buttons, options, and sections, so that you know where to find them and what they are used for.

We haven't yet covered the visual components in detail, because that's what we will cover in the next chapter.

If I ask you what are the mandatory steps to build a CDE dashboard, what would be your answer? Certainly, it would be: create the layout, define the data sources, and create the dashboard parameters and the components, where we can then set the parameter, the parameters, and the listeners, because this is what creates the interactivity of the dashboard. Of course, we have a lot more to cover, so let's jump to the next chapter.