Best Practices -

Pentaho CTools
This page intentionally left blank.
Contents
Overview .............................................................................................................................................................. 1
Setting Up CTools Best Practices ................................................................................................................... 1
Use Version Control ....................................................................................................................................... 1
Use CTools That ships with a Pentaho GA release .................................................................................... 1
Use Controlled Desktop Developing ........................................................................................................... 2
Development Processes Best Practices........................................................................................................ 2
Use a Full-Range Implementation Approach.............................................................................................. 2
Create Functional Breakdowns from Mockups.......................................................................................... 3
Avoid Extra Requests ..................................................................................................................................... 3
Use Necessary Components ......................................................................................................................... 3
Avoid Complex Logic in Components.......................................................................................................... 3
Get CTools Development Assessment ........................................................................................................ 4
Use CDE Templates for Multi-Dashboard Development .......................................................................... 4
Avoid CDE Inline Images................................................................................................................................ 4
Add Text with Text Component.................................................................................................................... 4
Use Default Bootstrap Framework .............................................................................................................. 4
Avoid Defining Styling Properties with CDE ................................................................................................ 5
Use a Consistent File Naming Convention.................................................................................................. 5
Avoid Complex Layout Structure ................................................................................................................. 5
Avoid Freeform for Layout and Components ............................................................................................ 5
Use Default Dimensions on Layout Columns ............................................................................................ 5
Encapsulate Your Layout Grid ...................................................................................................................... 6
Tips on CSS/JS Files ........................................................................................................................................ 6
Tips for the Datasources Perspective .......................................................................................................... 6
Options for Dropdown Selectors ................................................................................................................. 6
CCC Documentation and Customizing Charts ........................................................................................... 6
Consider Original Goal of Table Add-ins ..................................................................................................... 7
ETL, Data Modeling, and Queries - Best Practices ......................................................................................... 7
Use the Functional Breakdown to assess Query Necessities................................................................... 7
Optimize the Cache Layers ........................................................................................................................... 7
Use the Same Names for CDE and CDA Variables ..................................................................................... 7
Contents, cont'd
Embedding - Best Practices .............................................................................................................................. 8
Iframe Integration for CTools and Pentaho plugins .................................................................................. 8
RequireJS for Native HTML integration ....................................................................................................... 8
Look for Hidden/Different Visual Content .................................................................................................. 8
Overview
We are providing this collection of best practices and tips to help you implement CTools
Dashboards, so you can achieve solutions with little or no customization, and get to production with
minimal maintenance.

These topics are not presented in any specific order, and provide little detail about how to build a
dashboard. Your training materials and tutorials will have this information.

Software Version
Pentaho 5.4, 6.x, 7.0

Setting Up CTools Best Practices

Use Version Control
Use CTools That Ships with a Pentaho GA Release
Use Controlled Desktop Developing

Use Version Control

Definition: Any text-based files should be placed under VCS, such as GIT or SVN.

Rationale: Although CDE rewrites text-based CTools files whenever they are saved, they are
best managed when we can access the edit history in a multi-developer environment. These
dashboard files need to be synchronized from the VCS file system into the Pentaho BA
Jackrabbit solution repository.

<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="http_access." suffix=".log"
pattern="%t|%a|%m|%p|%U|%q|%s|%S|%u|%D|%T|%B|%{User-
agent}i|%{Referer}i|%A|%{Content-Type}o" resolveHosts="false"/>

Use CTools That Ships with a Pentaho GA Release

Definition: Pentaho ships with a fully supported read-only version of CTools, with
instructions to enable all capabilities. The Stable version of CTools, available in the Pentaho
Marketplace, is also supported but is not considered an official CTools release. Switch to
this Stable branch only when the changelog solves your problem.

Rationale: Different versions for different CTools may clash with the API calls among other
resources. Stable releases may include bug fixes at a faster pace than Pentaho BA servers
updates are released. The Trunk version of CTools is not supported nor encouraged for
production environments.

CTools Best Practices

Pentaho 1
Use Controlled Desktop Developing
Definition: Avoid working in remote servers, and make sure you can replicate the
production set-up as much as possible.

Rationale: Being capable of working locally from a virtual machine will speed up the
development gaps. This also makes sure that non-tracked changes performed by third
parties on the customer server are not carried over to your environment.

Development Processes Best Practices

Use a Full-Range Implementation Approach
Create Functional Breakdowns from Mockups
Avoid Extra Requests
Use Necessary Components
Avoid Complex Logic in Components
Get CTools Development Assessment
Use CDE Templates for Multi-Dashboard Development
Avoid CDE Inline Images
Add Text with Text Component
Use Default Bootstrap Framework
Avoid Defining Styling Properties with CDE
Use a Consistent File Naming Convention
Avoid Complex Layout Structure
Avoid Freeform for Layout and Components
Use Default Dimensions on Layout Columns
Encapsulate Your Layout Grid
Tips on CSS/JS Files
Tips for the Datasources Perspective
Options for Dropdown Selectors
CCC Documentation and Customizing Charts
Consider Original Goal of Table Add-ins

Use a Full-Range Implementation Approach

Definition: Consider your business requirements before starting your technical discussion.
Make sure to include your UX team from start to finish.

Rationale: By using a UX consultant with an implementation consultant, you can focus on

the business requirements first. Then, shape any technical requirements after a UX mockup
has been developed and approved. UX consultants can also assist with the development of
the layout pieces and part of the QA process for final deliverables.

CTools Best Practices

Pentaho 2
Create Functional Breakdowns from Mockups
Definition: Create definition lists for each component that will feed all dashboard sections.
These components should have information regarding input parameters, listeners, and
external dependencies.

Rationale: Functional analysis is needed to assess which pieces of each solution mockup
may require custom development or present other challenges. It is also a crucial piece to
ensure an AGILE development and review of your total effort.

Avoid Extra Requests

Definition: Browsers ideally support 8-10 queries, which can all run asynchronously.

Rationale: Complex dashboards can have many requests with many drilldowns. Focus on
loading the paramount pieces and use compound queries. They are leveraged from the
backend side, to group some KPI or detail boxes that could be fed from one single query.

<category name="org.springframework.security.event.authentication">
<priority value="WARN"/>
</category>

Use Necessary Components

Definition: Optimize your existing components, as they can take time to load, using memory
and CPU.

Rationale: Components often depend on requests, and may slow down your memory.

<rollingPolicy
class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
<param name="FileNamePattern"
value="/home/pentaho/pentaho/server/biserver-ee/pentaho.log_%d{yyyy-
MM}.gz"/>
</rollingPolicy>

Avoid Complex Logic in Components

Definition: Avoid using endpoints from components to control other components.

Rationale: If you follow the natural life cycle of CDF, by using listeners and firechanges to
broadcast parameter changes, you will avoid spaghetti-code, which makes it more difficult
to diagnose unforeseen or wrong states in your dashboard.

CTools Best Practices

Pentaho 3
Get CTools Development Assessment
Definition: Always check with the CTools experts to see if there is a way to create a specific
solution using a supported approach.
Rationale: The Services Development team can provide valuable feedback with their
broader knowledge of the product road-map and actual implementations. Creating a
custom component address for every dashboard requirement can set you on a non-
supported path, with higher maintenance and knowledge transfer costs.

Use CDE Templates for Multi-Dashboard Development

Definition: CDE templates are available from the Layout perspective and allow you to store
the layout with the links for external CSS/JS files, and components of your data sources
definitions.
Rationale: Try to avoid repetitive tasks during development. Remain aware of keeping
things in a state where you dont have to edit many things to do a single change.

Avoid CDE Inline Images

Definition: Use CSS to refer to any images that you may need in the dashboard.
Rationale: CSS files with external images are easier to manage by non-technical users with
some web experience, and are also easier to manage in a multi-dashboard ecosystem.

Add Text with Text Component

Definition: Use this component when possible, especially if the dashboard will have a
localization enabled.
Rationale: As with other components, the content in the Text component is easier to
manage with Javascript, which can be centralized in one file.

Use Default Bootstrap Framework

Definition: Bootstrap is enabled by default, and is easiest to follow.
Rationale: Bootstrap will not make a dashboard automatically responsive. It will create the
structure to make it possible without having to refactor the whole layout.

CTools Best Practices

Pentaho 4
Avoid Defining Styling Properties with CDE
Definition: Use CSS to control the styling of a JS namespace with options set in the
preExecution functions for each component.
Rationale: Styling is easier to maintain if it is centralized in one place with CSS, especially
with many dashboards. The preExecution step redefines the component before it runs the
queries, ignoring whatever changes that could have been done through the editor on a
specific property to be manipulated in the preExecution step. You can add a test to check
whether the property has been modified, via JavaScript.

Use a Consistent File Naming Convention

Definition: Use suffixes to understand how everything ties together layout, element,
component, query, parameters.
Rationale: This is useful during knowledge transfers to others and for troubleshooting; for
example, salesObj is the container for the sales component, which is a table using the
salesQuery with the salesParam or other.

Avoid Complex Layout Structure

Definition: Use only the essential rows and columns to create your layout.
Rationale: A layout with many elements will complicate finding all the dependencies when
styling them.

Avoid Freeform for Layout and Components

Definition: The Freeform components in the layout section bypass the grid structure, and
should be used as a last resort.
Rationale: The Freeform component is almost a wrapper for a custom component, which
needs to be evaluated if the out-of-the-box components cant be configured for that specific
solution.

Use Default Dimensions on Layout Columns

Definition: Always provide default dimensions to columns.
Rationale: It will be easier to debug the styling of the dashboards production by
maintaining control of your columns width. This allows you to follow the box model
upstream from the element having the issue.

CTools Best Practices

Pentaho 5
Encapsulate Your Layout Grid
Definition: Use a master row and column with maximum width, with a specific CSS class
applied.
Rationale: If you want to change global styling properties, this will give you a quick way of
accessing all the children for that layout. It also helps with troubleshooting, by quickly
identifying where the CTools dashboard starts.

Tips on CSS/JS Files

Definition: Use different CSS/JS files for global settings, local settings, and eventual
dependencies. Remove all commented code, namely on properties such as postFetch and
preExecution. Use version control instead of commenting old pieces of code.
Rationale: Keeping the files separate makes it possible to reuse them at a corporate,
project, or local level. Clean files load faster than unused code that leads to mistakes.

Tips for the Datasources Perspective

Definition: The output-options and calculated-columns properties in the Datasources
perspective should be used instead of moving this calculation to the postFetch step.
Rationale: PostFetch operations are done on the client, which affect performance in a
more unpredictable manner.

Options for Dropdown Selectors

Definition: These components can use jQuery-UI plugins to customize their look and feel.
Rationale: The Select and Multi-Select components are more mainstream, robust, and can
easily be upgraded by including more jQuery-UI add-ins. In the existing plugins, the
Select2 library is more recent than Chosen. Try to aim at the more recent libraries.

CCC Documentation and Customizing Charts

Definition: Use the sandboxes in Community Chart Components, and the links for each
chart documentation.
Rationale: The online documentation for CCC and other CTools increases with samples at
every release. This will keep you up-to-date on how to make the best of the CCC API.

CTools Best Practices

Pentaho 6
Consider Original Goal of Table Add-ins
Definition: If you need to perform a specific action which no existing add-in can perform,
create a new one or base it on an existing one.
Rationale: Using the formatText add-in to create charts creates confusion and could
cause future maintenance problems. Take the pieces of code that you need from the
original add-in and create a new one. Use the add-in documentation that is shipped with
the CTools under the Public/plugin-samples folder.

ETL, Data Modeling, and Queries - Best Practices

Use the Functional Breakdown to Assess Query Necessities
Optimize the Cache Layers
Use the Same Names for CDE and CDA Variables

Use the Functional Breakdown to Assess Query Necessities

Definition: Make sure that your data warehouse is ready for the filtering, aggregation, and
other operations needed for the dashboards.
Rationale: Canned reports and dashboards allow for optimized queries. For performance
reasons, sometimes you may need to use more complex queries in order to minimize the
number of requests done to the server. Your back-end should be ready for these
requirements.

Optimize the Cache Layers

Definition: Remember that queries can be cached at the CDA, Mondrian, and Database
level.
Rationale: All non-hidden parameters can be seen in the REST calls done from the client
side and this could become a security problem. Keep all sensitive information private and
as obfuscated as possible.

Use the Same Names for CDE and CDA Variables

Definition: CDE components need to map out the CDE parameters into the CDA query
parameters. Use the same name for both.
Rationale: By keeping the same names, it will be easier to follow the REST calls done to the
server and troubleshoot. The mapping between CDE and CDA variables is done in the
parameters property in the Component perspective.

CTools Best Practices

Pentaho 7
Embedding - Best Practices
IFrame Integration for CTools and Pentaho Plugins
RequireJS for Native HTML Integration
Look for Hidden/Different Visual Content

Iframe Integration for CTools and Pentaho plugins

Definition: All Pentaho plugins are URL-addressable, so iframe integration is done in the
same way for all of them.
Rationale: Even though iframe integration may not be ideal for some CTools cases, it
makes sense to move away from it, since we must deal with actual iframe limitations.

RequireJS for Native HTML Integration

Definition: The latest stable release of CTools support the AMD framework with
requireJS, which allows for a robust embedding with the OEMs parent applications.
Rationale: While both Native HTML: getHeaders|getContent and requireJS approaches
are possible at this point with CTools, it is very likely that only the requireJS approach will
continue in later Pentaho releases. You can get more information about this in
http://redmine.webdetails.org/projects/cdf/wiki/RequireJS.

Look for Hidden/Different Visual Content

Definition: Depending on the user, dashboards may appear different. Use the CTools/CDF
workflow to avoid data filtering.
Rationale: The dashboard context object can show some system variables that are defined
from the server side. These should not be used for any filtering, but can be useful when you
need to test values. Use a specific CDE parameter which is listened by hidden components
to trigger their rendering and make use of the execute-at-Start property.

CTools Best Practices

Pentaho 8