that's going to have the name of the territory and the value. You should have noticed that we are using CSS classes, the bootstrap CSS classes that will make this content responsive to screen size changes. [ 226 ] Chapter 6 Model handler We already covered in earlier chapters and/or sections the fact that we can use Pentaho Data Integration (Kettle) transformations to return data to the dashboard. When using MDX, we may return some more complex value parsed in a string and, when this happens, you may also need to manipulate the model so that it will let you build a really advanced visualization. Let's suppose that you are returning the sales for each territory and country, and you want to display a card by territory where you will include all countries' sales, such as in the following image: What we need to do is to group the result by territory, because if we can have an object for each one of the territories then we can have all countries inside it. It's easy to build a template that can bring those results to the screen: function(data){ if (data.queryInfo.totalRows > 0) { var model = {}; var territories = _.groupBy(data.resultset, function(elem){ return elem[1]; }); model[this.rootElement] = territories; return model; } else { return null; } } [ 227 ] Tables, Templates, Exports, and Text Components On the previous code, first we are checking whether we get results from the query, otherwise we want to return null to notify the component that it will not have data to display. If we have data on the result, then we will use the groupBy function to group all rows based on the second column (index one) that contains the territory. What we are getting is an object where the key will be the territory and the value will be the array of countries/values that belong to that same territory. After getting the result object we also need to put it on a root key, which is represented by this. rootElement, so we are using the property that has been set on the component (default value is items) so that we can iterate on each territory inside of it. An example of the model that is returned to the component is: { items: { APAC: [["Australia", "APAC", 630623, "0,49637,0,…,0,37905"], …, ["New Zealand", "APAC", 535584,"0,0,36409,…,0,102523"]], EMEA: [[…],…,[…]], Japan: [[…],…,[…]], NA: [[…],…,[…]] } Based on the model, we can now build the template. We will need to iterate on each element of items, getting each one of the territories, where we will iterate on each one of the arrays inside it. When inside each country we can access the value by using the proper index such as 0 to get the country, 1 to get the territory, or 2 to get the value for sales: function() { var template = ''; return template; } [ 228 ] Chapter 6 You will see two loops that are coded using the _.each function. First, iterate for each one of the territories and then for each one of the countries. When on the territory, we are using the key to create an element that will have the category or territory. When on the country, we will build three elements to display the name of country, the sale of the year, and a sparkline that represents the value for each one of the months for that same year. You will notice two function formatters and add-ins, but don't worry; we are going to cover them now. Formatters Formatters are very useful because, most of the time, we can't get the value formatted from the query, as we want it to be displayed on the dashboard. Let's suppose you have a query that can be used to get data to more than one component, taking advantage of the already cached data. If that's the case and if you want to display the values on a different format, then you need to handle it on the clientside. It's also easier changing the format on the client-side than on the queries, which can also be used by another dashboard or application. The template component has the concept of formatters, which are functions that we can define on the component and later use them inside the template. The values here can be numeric, a date, or a string. This can be done using the following property of the component: • Formatters: Used to define the formats that we may need to apply to the values returned from the dashboard and that will be displayed on the dashboard. When you click on the property you will get a popup where you will have to define the identifier/name for the formatter and the function that receives an argument, the value, and returns the already formatted value. Let's suppose you wanted to display the numbers, not to eight decimal places but just one. For that we would create a formatter with the identifier/name floatFormatter and a function such as: function(value, id){ return Utils.numberFormat(value, '$0.0a') } Formatters are defined as a property. When you click on the property, you have the ability to add as many as you want. [ 229 ] Tables, Templates, Exports, and Text Components To make use of the formatter inside the template, we need to use a function that is a formatter and receives two arguments: the value to be formatted, and the identifier/name of the formatter to use. This is because you can define and use multiple formatters on a template. One example of a template that would make use of the formatter would be as follows: function() { var template = ''; return template; } You can see in the code that this way we are displaying all the sales by territory, but the values of sales are being formatted to have only one decimal place. The formatter function is being used and called from the template. Add-ins We already covered the use of add-ins in the table component. They are really useful and easy to create on the tables, and here on the template component this is also very easy. We can create new add-ins or make use of the ones that are already there by default. The way to apply add-ins that already exist is a bit different from tables. Here on the template component, since we are defining the layout for our visualization you also need to define it on the template. You can make use of it by using the addin function that receives three arguments, the data to be used by the add-in that will create the visualization, the name of the add-in to use, and the name of the column that comes from the query because the add-in may need to access the column. Another reason to specify the ID is because, when using the same add-in on the same template but for a different purpose, you may want to have a different format, as is possible on the table component. Let's suppose you want to display sparklines but using lines and bars for different purposes. By including the id, you may do so. Just don't forget that the id must match the column name that is returned from the query. [ 230 ] Chapter 6 Let's suppose you want to display sparklines like you can do on the table component. For that you should have the string with comma-separated values, and let's suppose that the third column of your query is returning it for you. You would need to apply a template as follows: function() { var template = ''; return template; } You can see the addin function being used, passing as arguments elem[2] where the string containing the values separated by commas is, and another argument with the name of the add-in to use. We may also want to change the default options for add-ins, and here it's the same as on the table component. We need to use the setAddInOptions function to override the default values. The function should be placed on the preExecution function of the component: function f(){ var opts = { type: 'bar', height: 20, barWidth: 6 }; this.setAddInOptions("templateType","sparkline", opts); } [ 231 ] Tables, Templates, Exports, and Text Components The result of the add-in would be something similar to that displayed in the following image: You need to be sure that the add-in that you are using is registered, otherwise it will not work. The add-ins that are available for the template component are not the same; some will be available and others will not. During the writing of this book I also created approximately ten add-ins, some of them almost a copy of add-ins used in the table component. The following image is an example of the add-ins that can already be used inside the template component: [ 232 ] Chapter 6 You can see on the image some numbers pointing to the add-ins; let's cover them and use the numbers so that you can easily identify them. The add-ins that we are covering for the template component are very similar to the ones on the table component so you already have most of the information. Don't forget that these options should be set inside the preExecution function of the component: 1. clippedText: The same as the table add-in plugin used when we have text larger than the space we have to display it. It will show the full text when we hover over it. The options available are: °° showTooltip: To show a tooltip when hovering over the text. The default value is true. °° useTipsy: Use the Tipsy JQuery plugin to show a fancy and customizable tooltip. The default value is true. °° applyFormat: This is a function that receives an argument that is the value to show on the tooltip and returns the formatted value. One example would be: var options = { showTooltip: true, useTipsy: true, applyFormat: function(value) { return value; } } this.setAddInOptions("templateType","clippedText", options); 2. trendArrow: This add-in is very similar to the trend arrow of the table component using the exact same behavior and properties. It will display an arrow up/down and red/green depending on whether it's up/below and whether it's a good/bad value. This is the same behavior as the trendArrow table add-in, so please refer to the documentation. The properties are the same: °° good: This property says that a good value is above the threshold °° thresholds: Defines the up and down thresholds. The default for up upper interval. The opposite applies if we set a value of false. The default value is true. and down thresholds is zero: {up: 0, down: 0}. [ 233 ] Tables, Templates, Exports, and Text Components °° includeValue: Used to specify that we will also see the value side by side with the arrow. The default value is false. Here the difference to the add-ins available on the table component is that I have used font icons to display the arrow. Color and sizes can be changed just by changing/overriding some CSS. By opening the trendArrow.css file when debugging your dashboard, you will find the CSS classes that you need to override and customize the size, icon, and color. The following image is an example of the template add-in showing the trendArrow pointing down or up depending on a negative or positive trend compared to the sibling period: 3. formatted: I consider this a multiuse add-in because you can use it to easily apply some formatting or even customize, and have complete control over, what you will display. You can use the add-in to send HTML to the dashboard, so it gives you great flexibility. By default, the add-in format will be applied using one of two functions. You can format numbers and/or dates. This is quite different from the one we have discussed for the table component; it's simpler to use but powerful as well. The three main properties are: °° formatFunction: Here you should specify a string with the name of the function that you want to use from Utils. Use numberFormat to format a number or dateFormat to format a date. The default value is numberFormat. °° formatMask: You should remember from the section where you covered the Utils number and date formatting functions that we also need to specify the format mask, so this property is used to specify it. You should set a string with the format to use on the function that you specified as formatFunction. The default value is #,#.#. To get more information, please refer to the date and number formatting of the CDF chapter, Chapter 3, Building the Dashboard Using CDF. [ 234 ] Chapter 6 °° applyFormat: By default, the functions used are the formatFunction and formatMask properties, so it will do the formatting based on what you have specified for those properties. But if you want to customize the content to display, you can overwrite this function. If so, you need to define your own function, which needs to receive the value as the argument and return the text/HTML to be presented on the dashboard: var options = { applyFormat: function(value) { return ''; } }; this.setAddInOptions("templateType","formatted", options); The previous code is an example of the code to be placed on the preExecution function of the component to extend the options, if we want to customize the content to return to the dashboard when applying the formatted add-in inside the template component. 4. sparkline: Allows you to use the JQuery Sparkline Plugin just like we covered on the table component. Options should be the ones available on the plugin; just make sure the value returned is a string, represented with comma-separated (,) numbers. This is the only property that you will need to define, but you can use more. You can go to the Try It Out section of the Sparkline Plugin to check that the properties will differ from chart type to chart type: °° type: It's a chart type and also a property that is passed from the add-in to the Sparkline Plugin. Here the default is bar. Per instance, if you need to display bars to represent the values chart and change some of the properties you would use code such as: var options = { type: 'bar', barWidth: 6}; this.setAddInOptions("templateType", "sparkline", options); [ 235 ] Tables, Templates, Exports, and Text Components Please refer to the sparkline add-in section of the table component. You will find all the information you need, which will also work on the template component. The following images are also examples of what you can achieve when using the add-in: The previous image uses the bullet chart options, while the following image uses the bar chart options to represent the values that should be represented: 5. hyperlink: hyperlink is an add-in that can provide links to any URI that is recognized by the HTML and the browser. You need to return a string with a valid URL from the query. The use is exactly the same as on the table component, so please refer to that section to get more information. The options are: °° openInNewTab: Used to open the URI on a new tab of the browser. By default, it is set to true. When set to false it will be opened on the same tab. [ 236 ] Chapter 6 °° prependHttpIfNeeded: Used to tell the add-in to prepend the string http:// to the URL provided when the URI does not include one. We should avoid it when providing an e-mail address as the URI. °° regexp: We can provide a regular expression to check whether °° pattern: This is the regular expression that will extract the strings to use as the label and as the URI. °° labelReference: Used to tell from which group index we get the label. By default, its value is set to 0. °° urlReference: Used to tell from which group index we get the the provided URL is valid. The regular expression is just to check whether it's valid or not. If it's valid then the add-in can create the link. By default, it's set to null, avoiding the validation. URI. By default, its value is set to 1. To use the add-in, the value returned can be something such as: [Pentaho Website][http:// www.pentaho.com], and if that's the case you will need to apply the following options to the add-in: var options = { pattern: /\[(.*?)\]/g }; this.setAddInOptions("templateType","hyperlink", options); 6. localized: This is similar to the localizedText add-in on the table component. Please refer to the documentation on the table component section. 7. bubble: This add-in will draw a bubble where the size of the bubble is the relation between the value and the minimum and maximum values for all the rows on that same column, where the biggest bubble will be the highest value of all. The available properties are: °° containerSize: Sets the size of the parent container where the bubble will be. The default value is 30. The size of the bubble should be returned as a percentage, which will be the relative size for the bubble inside the parent container. [ 237 ] Tables, Templates, Exports, and Text Components °° valuesArray: This is the function used to return the array of values where we should be searching for the max and min values, so that we can calculate the size of the bubble. By default, it will use the id passed when applying the add-in on the template, where the id should match the name of the column that we want to use to get the max and min values. Therefore, it's very important to have the id of the column passed when making the call of the add-in on the template. Based on the modelHandler function and the model you are returning to the component, the valuesArray function may need to be changed to get the proper array of values from the returned model. The function receives an argument that is the status but, as it's called from the radius and/or color functions that we also may override, you may include more arguments on it: function(st) { var colNames = _.map(st.data.metadata, function(elem){ return elem.colName; }); var colIdx = _.indexOf(colNames, st.id); var values = st.data.resultset.map(function(e){ return Number(e[colIdx]); }); return values; } °° radius: The default value is a function that will calculate the size based on the value for this same element. It accepts a function that receives the status as an argument. From the status, we can get the value that should be represented by the bubble, the data returned from the query, and the id for the add-in, which should identify the name of the column that should be used to find the min and max values that can be used to calculate the size of the bubble. If there are some add-ins that can work without the id being passed, this is not the case. By default, the following code is applied: function(st) { var values = this.valuesArray(st); var tblMax = _.max(values), tblMin = _.min(values); var value = Number(st.value), size = (value-tblMin)/(tblMax-tblMin); return size*100; }, [ 238 ] Chapter 6 °° color: The color to be used for the bubble. This option accepts a function that receives as an argument the status, where we can find the value, all the data returned from the query, and an id that identifies that unique add-in. The default function is: function(st) { return "rgba(200, 200, 200 , 0.6)"; } °° showTooltip: To show a tooltip when hovering over the bubble. The default value is true. °° useTipsy: Use the Tipsy JQuery plugin to show a fancy and customizable tooltip. The default value is true. °° applyFormat: This is a function that receives an argument that is the value to show on the tooltip, and returns the formatted value. The default value is: function(st, opt) { return "Value:" + Utils.numberFormat(st.value, '#,#.#'); } °° tipsyOptions: The options to be passed to the Tipsy JQuery plugin. This way Tipsy can be customized. The default value is: { gravity: 's', html: false } The following image is an example of the result of applying the Bubble add-in: [ 239 ] Tables, Templates, Exports, and Text Components 8. bulletChart: This is used to represent a bullet chart with the values that come from the query for that same cell. Here you need to return all the values to use on the bullet chart, separated by a comma. The options that you have available are all those available for CCC charts, which we are going to cover later. The options for the chart should be set inside the chartDefinition object. The following code is an example of how to set the properties: var options = { chartOpts: { compatVersion: 2, height: 60, orientation: "horizontal", } } this.setAddInOptions("templateType","bulletChart", options); When using the default properties, you get a bullet chart similar to the ones in the following image: 9. cccChart: This add-in allows you to display any CCC chart, but it's tricky. We will see later in this book, when we cover CCC charts, that CCC can receive from the query any result set and still display the chart. You may need to change some properties to have data displayed as expected. This is the tricky part here. What is the best way to represent the data so that we can have it represented correctly? Depending on the chart and on the properties that you set for the chart to represent it, you may need to adapt the result set. It would be easier to set the query, choose the chart to represent it, and then just adapt some of the options to adapt the chart to the data format that is returned. You may be a little bit confused with this, but do not worry, you will get the information to understand it. For now, let's focus on the properties that can be used to customize the behavior of the add-in: [ 240 ] Chapter 6 °° type: Used to set the kind of chart to represent data. Possible values are: BarChart, LineChart, PieChart, DotChart, StackedLineChart, StackedAreaChart, HeatGridChart, WaterfallChart, BoxplotChart, MetricLineChart, TreemapChart, SunburstChart, and BulletChart. You won't need the last one since you have an add-in capable of doing the same thing. The default value is set to PieChart. °° chartOptions: Used to set the options for the chart; you should take a look at the CCC documentation pages and check what properties are available. You can also directly change some of the properties of the chart and check the results. Those are the options/properties that you can set here. One example would be: chartOptions: { compatVersion: 2, height: 100, animate: false, crosstabMode: false, seriesInRows: false, timeSeries: false } The crosstabMode, seriesInRows, and timeSeries properties are the ones that will make the difference when CCC is interpreting the results. This will definitely change the data you are displaying. The compatVersion is used to inform CCC that the chart should be rendered using version 2, which has a lot of improvements and fixes. In this case there is a property that's really mandatory, the height for the chart. Without this one the chart will not be rendered. °° transformData: A function that receives the data as an argument and returns the complete result containing the metadata and resultset. Please refer to the Chapter 2, Acquiring Data with CDA to get more information if you can't remember the format expected. You won't need to include the queryInfo: function(data) { var result = { metadata: [], resultset: []}; try { data = JSON.parse(data); var colMetadata = []; _.each(data, function(row, index) { if (index == 0) { _.each(row, function(col, index) { result.metadata.push({ [ 241 ] Tables, Templates, Exports, and Text Components colIndex: index, colName: "Col"+index, colType: "String"}); }); } result.resultset.push(row); }); } catch(e) { return null; } return result; } The following code accepts as an argument an array of arrays. For each row we need to add it to the new result set, and in the case of the first row, we also need to add the metadata to it. The following image is one example of a pie chart being displayed inside the template component: Events It's also possible to handle clicks on the elements created by the template component. You can use events to expand a particular section, to make a fireChange creating interaction between components, or to get details for the clicked section. Since you are creating a function, you can do whatever you need inside. To create an event, you need to use the Events property of the component. For the right-most value you will need to define the event that you want to handle, followed by the selector of the element from where you want to handle the event separated by a comma (,). On the left you will need to define the function and write the code (it can only be a fireChange) so that other components can be notified and updated. [ 242 ] Chapter 6 Let's suppose that you wanted to get details for a particular territory, the one that is clicked; the template would be like: function() { var template = ''; return template; } You can see that for each of the items/territories, we are creating a parent container that includes data-territory attribute with the name of the territory and a CSS class where the value set is the clickable value. The data-territory attribute will be used to get the territory we are clicking on, and the CSS class will be used to get the HTML element where we will attach the event. To handle the event, we will need to add an event handler on the events property of the component. To do it you will need to use the left field click , .territory and the following function on the right field of the dialog that pops up: function(event) { var $elem = $(event.currentTarget); var selected = $elem.data('territory'); $elem.toggleClass('selected'); this.dashboard.fireChange('selectedParam', selected); } Inside the function this will refer to the add-in, so on the first line we are getting the element that we clicked on. After that, we are using the JQuery data function to get the data from the attribute data category from where we will know which value should be used to set the parameter value. But first, we also need to toggle the CSS class to know which territories are selected. At the end we add a fireChange so that the value is written to the parameter, and the components that are listening it can be notified about the change. Don't forget that, for this to work, you will need to create the parameter to store the selected territory name. In our example the name is selectedParam. Besides fireChange, you can expand the container you are clicking on and display some more information. This doesn't need to be an element outside, as in the samples provided with the book. [ 243 ] Tables, Templates, Exports, and Text Components Extendable options On the template component it's possible to customize the messages that you get in the event of an error, and for that we can use the following property: Extendable options: Accepts a function that returns the JSON object structure with all the messages to override it. The function to return the messages, which is used by default, is the following: function() { var opts = { messages: { error: { noData: "No data available.", invalidTemplate: "Invalid template.", invalidTemplateType: "Invalid template type.", generic: "Invalid options defined…." }, config: { style: { error: {icon: "remove-sign", type: "danger"} }, template: ""+ "" } }, }; return opts; } The function will return an object with customized error messages but also the Underscore template that is used to build the error message that will be displayed. If you look deeper into the template, you will find that I used a Bootstrap alert component and also made use of the icons to display on the alert. The alert type to use and the icons are defined inside messages.config.style. It will work as a template model where the template will act as the template and the style as the model. If needed, you can also overwrite the processMessage function that takes care of building the message. The function accepts two arguments, the message and the type, and returns a string with the HTML to be displayed as a message. [ 244 ] Chapter 6 If you have no row to display, by default, the following will be shown: As you can see, the template component needs to be improved, mainly by making it easier to use, but without losing the flexibility to adapt and create new and impacting visualizations. We are in an era where the request to have prescriptive solutions and real-time prescriptive solutions is already a reality. I will be working on a similar component that can have real-time results presented on a dashboard using your custom visualization, so I am expecting to be able to have a real-time template component in the near future. Export button component When presenting content on a dashboard, which uses a query to present the content, we can make the export of the data to a specific format. It can be done only for a component, so the results of only a query and not the full dashboard will be exported. When using this component, you can export data to one of two formats, csv or xls; no other format is available on this component. The properties that you need to set are: • Label: The label that will be displayed on the button. • Component name: The name of the component from where to export the data. This should be the name that you gave to the component. Since you need to export the data from a component, you should already have a component set and ready to be used. • Output type: The format to export data to. Available options are the ones already mentioned, csv or xls. Export Popup button component The Export Popup button component is more flexible and will let you have more options. When using this component, the final user will have a link available where he can click to do the exporting. When clicking on the link, the user will get a popup with the options to export to different formats, and one option should be selected to make the export. The formats available are the same that are available in CDA, so you are able to export data to csv, xls, json, and xml. Besides that, if you have a chart, the final user will also be able to export the chart to svg or png format. [ 245 ] Tables, Templates, Exports, and Text Components The options that you have available are: • Title: This is the text that will be displayed on the dashboard, where the final user can click. • Gravity parameter: This is used to set the position where the popup will jump. • Chart component to export: This is the name of the chart to export. Here you can click on the down arrow key to get the list of values and select the component name. • Chart export label: This is used to set the text that will be displayed and to make possible the export of the chart. • Chart export type: Here we need to specify the format to export the chart to. Available options are svg or png. • Data component to export: This is the name of the component from where data will be exported. Here you can click on the down arrow key to get the list of values and select the component name. • Data export label: This is used to set the text that will be displayed and to enable exporting the data. • Data export type: Here we need to specify the format to export the data to. Available options are csv, xls, json, or xml. • Name for data export attachment: This is name of the file that will be exported. The format will automatically be appended to the name of the file. • Content linking: This an advanced option to present the options and set the links that will enable the export. Per instance, when you want to be able to export to CSV and XLS. Using the previous properties you can only specify one format. The content linking property will allow you to specify the text to be displayed and a function that will be executed when the respective link is clicked. Inside this function you will be able to define the component from where to export, the format, and the filename to export to. When using this property, you will get a dialog where you will be able to add options. Each new line will be an option, and for each line you need to specify an argument and a value. On the text more to the left, you need to specify the text to display as the link. On the text more to the right, you will need to specify the function. Per instance, on the text to display you would set Export to CSV and the function would be as follows: function() { var comp = dashboard.getComponentByName('${c:myTable}'); [ 246 ] Chapter 6 var cd = comp.chartDefinition || comp.queryDefinition; var query = dashboard.getQuery(cd); query.exportData('csv', {}, {filename: "filename.csv"}); } The first line of code will get the instance of the component with the name myTable, whereas on the second line we get chartDefinitions or queryDefinitions. Depending on the component, it will return the correct option, because if one is not available we will use the other. The third line gets the information about the query, and by using this last one we can export the data. For that we need to make use of the exportData function that should be available for all the components that run a query. This function accepts three arguments; the first is the export type, the second is the overwrite options, and here you can return an empty object, and finally the third one is an object where we can specify the filename and extension for the file that will be exposed. The following image is an example of what can be produced, out-of-the-box: When doing the export, the CDA query will run again, using the same parameters that are selected on the dashboard, and at that time it's already cached. Anyway, you can play around a little with this. It's not unusual to have a request to have quite a different export than we are seeing on the dashboard, so you can imagine a scenario where you will have a component that is hidden and is not executed until an export is requested. [ 247 ] Tables, Templates, Exports, and Text Components Referring to component, parameters, and to the layout If you go to the developer tool of your browser and inspect a CDE dashboard code, you can see that, to the names of the components that we set when editing the dashboard, we always prepend with render_. So when you want to refer to the name of the component, you should refer to the complete name such as render_myComponentName. When you use code inside the dashboard, which is not valid for code on external files, you can refer to the component as ${c:myComponentName}. This will be translated when the code is sent to the browser, as it's already referring to the correct name of the component. This is also valid for parameters ${p:myParameterName} and for elements on the layout by using ${h:myPlaceholderName}. The syntax difference is the letter before the name and inside the {}. You can use c for components, p for parameters, and h for elements on the layout. Text component The text component is another component that is really simple to use. It allows you to display text on the dashboard. This component will not trigger a query, but is still executed as part of the lifecycle of the dashboard, so it's very useful. It can be used, per instance, to display the user that is logged in. Besides the properties that you already know and that are common to the remaining components, there can also be: • Expression: A function that should return the text/HTML to be displayed on the element of the layout associated to this component. One example would be: function() { return this.dashboard.context.user; } The previous code is returning the username of the user that is using the dashboard, but we could have returned HTML to display. [ 248 ] Chapter 6 Summary By reading this chapter, you should have learned how to use the table component, template component, export buttons, and text component. You should be able to use the table component to display details for each one of the rows, or just trigger some changes to other components when the user clicks on a row. You also should have learned to apply add-ins and customize tables, understand the capabilities provided by functionality on the server-side, or just customize what we see displayed (and the how of it). You have also learned how to use the template component to display data the way you need to. The template component provides many ways to display the results of a query, customize messages, or just apply some functions to customize formatting. Besides the fact of learning how to use the components, you should be able to make the most of them and be able to find the best way to present data to the user using these two components. Hopefully you also understand what you should use, or should avoid, so as to not decrease the performance of the dashboard, or even queries triggered. Performance is very important. At the end of the chapter, besides learning how to use the text component, you also learned how to export data and the way to do it. We have covered the way to export an image from a chart. There is a dedicated chapter for charts, as they are one of the best ways to represent data on the dashboard. The next chapter will cover some advanced concepts that you can use in both CDF and CDE dashboards. [ 249 ] Advanced Concepts Using CDF and CDE Today, when we are requested to build a dashboard, most of the time we find ourselves faced with customers who want you to make the dashboard available in multiple languages, and to be honest, this makes sense. Why would you have a dashboard available only in your language and not in other languages? In this chapter, we will teach you how you can do this. CDF and CDE provide you with some really cool components that are more flexibility then others, and allow you to build your own visualizations, so we will also cover these components. But for now let's suppose that you are working with a customer who has hired you to build a dashboard but also to train his team to build the remaining dashboards. If there is a visualization that you need to implement/develop, you will certainly be capable of creating a delivery that includes a custom component that they can use/reuse later. This is possible, and we are going to cover how to do it, as well as how to extend template and table components by creating new add-ins. In one of the sections of the book, we also provided some information about reusing templates and styles, and we already showed you how to create a new template, save it, and reuse it. But we also may want to create a style, and this is the chapter where we are going to do that. A very interesting possibility is building a dashboard and embedding it in another one. Do you realize how cool this could be? Just imagine creating a dashboard that can be used a section of another dashboard, and reusing it multiple times. You must be having some ideas already, so let's start with the chapter. [ 251 ] Advanced Concepts Using CDF and CDE The topics covered include: • Creating new add-ins for table and template components • Making use of the template add-in for table and template components • Creating and changing the style of the dashboards • Using the dashboard component to reuse dashboards • Creating new add-ins and new components • Making use of bookmarkable parameters References to components, parameters, and layout elements First, I want to start by covering one important concept in CDF, and don't forget that concepts in CDF also extend to CDE. If you open the developer tools in your browser and start inspecting some CDE dashboard code, you will see that the names of the components are always prepended with render_ with the name of the components that we set when editing the dashboard. This way, when you want to refer to a component using its name, you should use the complete name of the component such as: this.dashboard.getComponentByName('${c:myComponentName}'); This would be the same as: this.dashboard.getComponentByName('render_myComponentName'); When you use this code line inside a dashboard, where it is not valid for code in external files, you can refer to the component as ${c:myComponentName}. This is possible because, when using this syntax, it will be translated and replaced by the full name of the component, so you don't need to worry about the name that CDE may have given to it. This is also valid for the parameters or elements created in the layout perspective. When you use a dashboard embedded in a dashboard, like we are going to see later, and you take a look at the code, you will see that the name will not be exactly the same as the one you gave it. You should worry about this, because you can use the syntax previously referred to. [ 252 ] Chapter 7 Since this is also valid for components, parameters, and layout elements, we should have a way to distinguish them. This is done by changing the letter before :. You should use a p for parameters, a c for components, and an h (from HTML) for the layout elements, like the following: • Components, which has already been covered: this.dashboard.getComponentByName('${c:myComponentName}'); • Parameters: this.dashboard.getParameterValue('${p:myParameterName}'); • Layout elements: $('.${h:myLayoutLementName}').text('Hello World'); When you select the name of parameters, the elements of the layout, and the component's name using the drop-down, CDE will automatically create a reference to the proper object of the dashboard, using the correct syntax. It won't work, if you type the name yourself nor when writing your own code. For this reason, I always advise you to select the values using the drop-down, and select the value from the list, otherwise you might be creating issues. The query and freeform components The components we have covered will give you the freedom to do almost everything you need to do to build an amazing dashboard. However, sometimes we need to go further, and we might be able to do this just by using the available components. To build custom visualizations, you can also make use of the query and freeform components, but what's the difference between them? A very frequently asked question is where to use one or the other. So now let's answer this question and learn how to use these components. [ 253 ] Advanced Concepts Using CDF and CDE The query component will trigger a query, but you want to display some custom content inside your dashboard. Here you can't avoid setting a valid query, so the freeform component is useful here. The freeform component will not trigger any query so you can use it as you want/need. You may be thinking, If it does not do anything, why would I use it? Well, it's because sometimes you have the need to execute some code that respects the lifecycle (a good example can be internationalization/ localization, or just adding static HTML to the page/dashboard) of the dashboard; as with any other component, these two components have their own lifecycle. When using require, if you add HTML elements with text directly to the layout of the dashboard, you will see that text displayed in the first place, will give you a bad look and feel. You can use a text component to add the HTML, which will just be added to the page when the dashboard is being rendered. For both, query and freeform components, you will be able to specify the priority of execution and the preExecution and postExecution functions, as well as the component that should be executed at the start of the dashboard, by setting true or false in executeAtStart. For the query component, we are also able to specify the properties datasource, parameters, and the postFetch function, which will be executed as soon as the component gets the results, just after the preExecution function and before the postExecution function. So the difference between the query and the freeform components, is that, for the query component, a data source will be used and, for the freeform, it will not. Just use them when you need to present content that you are not able to present with any other component provided by CDF and CDE. The query component As already said, we can use the query component to present custom content to the dashboard. The properties that are available along with the common ones are: • Result var: This is the name of the dashboard parameter that is going to be used to store the result set from the query. This will not include the metadata, but just the resultset itself. It will store a multidimensional array with all the rows and columns returned. There is no default value—you should specify the name of a parameter. When you leave it blank, no parameter will be set. To access the parameter that could be named myResultset, you should use the same methods as for any other parameter in the dashboard, as in the following code: var data = this.dashboard.getParameterValue('${p:myResultset}'); [ 254 ] Chapter 7 • Asynchronous mode: This tells us that the component should work in an asynchronous way. The default value is true and, when set to false, only after the component's rendering is complete, the components with a low priority (higher values) will be executed. My advice is to always use the default value. Pretty much, the property is there to retain compatibility with older versions of dashboards/components, so keep this property set to true. You can also get more details on Pedro Alves' blog at the following links: • http://pedroalves-bi.blogspot.co.uk/2012/11/making-cdf-callsasynchronous.html • http://pedroalves-bi.blogspot.co.uk/2013/01/cdf-async-support. html Let's suppose that you wanted to display the product line to be displayed as an accordion, where for each product line item we display the products and sales for that same line. There is no component, out of the box, that would build what was described in last sentence. Anyhow, you can build a custom component if you want to use it multiple times in multiple dashboards; otherwise you can just use the query component. The reason for using the query component is because the results that are going to be displayed come from a query, and we still don't have them in the dashboard. [ 255 ] Advanced Concepts Using CDF and CDE We could use the query component in one of two ways. The first way is to use the variable to create and write the elements to the page on the postExecution function, only after postFetch. The following code is an example of creating the accordion with the accordion from JQuery UI (more information is available at: https:// jqueryui.com/accordion/): function() { var data = this.dashboard.getParameterValue('${p:myResultset}'); var $placeholder = this.placeholder(), $accordion = $(''), productLines = _.groupBy(data, function(elem) { return elem[0]; }); _.each(productLines, function(products, line) { $accordion.append('

'+line +'

'); var $content = $(''); _.each(products, function(product) { var values = product[1] + ': ' + Utils.numberFormat(product[2], '$#,###.0'); $content.find('p').append(''); }); $accordion.append($content); }); $accordion.accordion({ heightStyle: "content" }); $placeholder.empty().append($accordion); } In the previous code, we are getting the result of the query and iterating on each product line, and for each line we are also iterating on the products. This way, we can write the elements to the page. At the end of the code, we are using the accordion plugin and rendering it in the dashboard. The other way is to use postFetch directly, making use of the argument that is passed. If that was the case, then you will not need to define the variable data, just specify it as argument of the function; where you have data, it will be data. resultset. Don't forget that, when in postFetch, we should return data to the component. [ 256 ] Chapter 7 The freeform component If you have a component that already has the result of a query that fits your need or you just want to render some content in the dashboard that does not depend on the result of a query, you can use the freeform component. The advantage is that the component has its own lifecycle and will be perfectly synced with the lifecycle of the dashboard. You can change the priority of execution, and add code for preor post execution. A property that is different from the other components is: • Custom script: This will accept a function with the code to be executed, just after preExecution and before postExecution. For this case, and supposing that you had a query component execution before this one, you could use the same code here in the custom script. This would grab the result from the parameters and the same code would be used to build the content for the dashboard. Even simpler would be a case where you needed to have the freeform component performing fireChange to a parameter based on some actions that can be controlled by the lifecycle of the dashboard. As the component will not make use of a query, you should already have figured out that it will not make a call to postFetch. Creating add-ins We have seen that both the table and template component can make use of add-ins. We can also extend CDF and create new add-ins that can be added to the dashboard. You should always be aware that when using it on a table component the add-in will be used for the cell of the table, so be cautious about what you are showing for each cell, so that the table does not become hard to read due to excessive information. Just because dashboard users get information from a dashboard does not mean you should present excessive information. To add a new add-in you just need to write a few lines of code and some properties, create a new instance of an add-in, and register it to the dashboard. The definition of the add-ins will be set using a JSON structure with the following elements: • name: This is the name/identifier given to the add-in, which will be used to reference it. This field is mandatory and accepts a string. • label: This will be the description of the add-in. It accepts a string. [ 257 ] Advanced Concepts Using CDF and CDE • defaults: Here we need to set another JSON structure with the default properties of the add-in. These properties are the ones that may be overwritten later when setting the properties of the add-in. For example, for the sparkline add-in, it may have the type set as line but later we may want to use a bar. • init: This is used to execute some code once the add-in is requested. Some preparation code can be executed here. When defining an add-in that will be applied to a table, we also need to specify the sort functions, and the right place to do it. It accepts a function and accepts no arguments. • implementation: This is a function where the code of the implementation will be added. The function receives three arguments: • target or tgt: As you will see in the following example, it's a reference to the HTML element where we will be rendering the content to be displayed. • status or st: As you will see in the following example, it's an object where we can find the value to be used. The information that will be available inside this argument will depend on the component that is using the add-in. For instance, when used in a table, we may have access to the index of the column (colIdx) and the index of the row index (rowIdx) being processed. Since in some cases we may be using a hierarchical structure, we will have access to the add-in identifier (id) that is being passed when the add-in is used in the template. For both cases, independently of the component, we will have access to the complete dataset or model (data when in the table component and model when in the template component). • options or opt: Like you will see in the following example, these are the options set by the developer to customize the appearance and/or behavior of the add-in. We should use them if we want to extend the default options. Let's see what the code would be for an add-in created to be used in a table and another for the template component. Let's suppose you want to create an add-in to format the values that are going to be displayed in the dashboard. For this, you need to use the numberFormat function under the CDF utilities, which was already referred to in this book as Utils. We should not forget to include the module. To create and include a new add-in in your dashboard, you will need to add a new resource, using the layout perspective, and give it a name. After setting the name, you should place the code inside it, something like: define(['../../../AddIn','../../../Dashboard', '../../../dashboard/Utils','../../../Logger', '../../../lib/jquery','amd!../../../lib/underscore', 'amd!../../../lib/datatables'], [ 258 ] Chapter 7 function(AddIn, Dashboard, Utils, Logger, $, _) { var formatted = { name: "numberFormat", label: " numberFormat", defaults: { formatMask: '#,#.#' }, init: function() { $.fn.dataTableExt.oSort[this.name+'-asc']= $.fn.dataTableExt.oSort['string-asc']; $.fn.dataTableExt.oSort[this.name+'-desc']= $.fn.dataTableExt.oSort['string-desc']; }, implementation: function(tgt, st, opt) { var opts = $.extend(true, this.defaults, opt), Value = Utils.numberFormat(st.value, opts.formatMask); $(tgt).empty().text(Value); } }; var addin = new AddIn(numberFormat); Dashboard.registerGlobalAddIn("Table", "colType", addin); return formatted; }); In the previous code, first we are using require to create the add-in, including all the modules (JavaScript and CSS). When all modules are there, we need to start creating the code for the add-in. We start by creating a JSON structure, the name, label, and defaults as well as the init and implementation functions. The name will be the identifier of the add-in, in this case the formatter. For the defaults, we are defining the format mask, which will be applied when no other format is passed to the add-in. The init function is being used to define the sort functions of the jQuery Datatables plugin. This will only be used by the add-ins that we create and apply for the tables. It will not break if applied to the template; it will just not be used. The implementation function has the code that will be executed every time it's called by the table or by the template components. On the first line of the implementation function, we are extending the default options with the options that may be passed to the add-in on the pre-execution of the component. On the second line, we are setting a variable with the format, which is defined in the options and applied to the value that we can grab from the status. Here, using jQuery, we are cleaning the actual content that might be there and writing the already formatted value. [ 259 ] Advanced Concepts Using CDF and CDE After this is complete, and now that we have the formatted JSON with the definition of the add-in, it's time to create a new instance of the add-in. And last, we are registering the add-in in the dashboard and as available as a column type of the table. When developing the add-in for the template component, there are two main differences between the add-in for the table component. One difference is that we would not need to define the sort function inside the init function, because that may not make sense when applying a template. That way, we would also not need the datatables module. The other difference is when registering the add-in for the dashboard. As you can see in the following code line, we are registering it to be used for the template component. Just look at the first two arguments of the function. We are using Template and not Table, as we are also using templateType and not colType: Dashboard.registerGlobalAddIn("Template", "templateType", addin); The template add-in There is one other add-in that was not covered, and it's available for the template component but also in the table component. The way it works is pretty much the same as the template component. There are three ways for the add-in to use the data being processed. The first one is by working on the query to return a string with the JSON structure that will be parsed by the default modelHandler function. There is another way: overwriting the modelHandler function by writing your own code and returning a custom and valid JSON structure as the model. If none of the earlier options return valid JSON, then the value will be treated as a string. Please refer to: http://www.json.org for more information. Just use the method that you are most comfortable with, prepare everything in the query/backend, or use the available function to return a valid model that can be applied to the template being defined. The way to apply options to the add-in is the same as already covered for the other add-ins, and the ones available are: • templateType: You must select the template engine to use. Those currently available are underscore and mustache. The last one is the default value. • template: This is the template to be used. • rootElement: This is the name/key that will wrap the model/value being processed. [ 260 ] Chapter 7 • formatters: This accepts a multidimensional array. Each formatter will be represented by an array that will have two elements. The first element will be a string with the name of the formatter and the second will be the function that accepts two arguments: the value to be formatted and the identifier of the add-in being executed. It should return the formatted value. • events: This is similar to the last option, and here it accepts a multidimensional array. Each event will be an array with two elements. The first element is a string that has the event being handled and the selector of the element, separated by a comma (,). The second element is a function with the code to execute when the event is triggered in the selected element. The function accepts one argument that is a reference to the event itself, just like writing a function such as a regular JavaScript event. • modelHandler: This is a function that accepts data being processed by the component. The function is used to return a valid model to be rendered in the template of the add-in. • postProcess: This is a function where you can write some code after the elements are rendered on the page. For any of these functions, please refer to the template component documentation to get more information: var templateOpts = { templateType: 'underscore', template: '<% _.each(items, function(value, idx) { %>' + '