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
•
Rationale: Although
text-based files should be placed under VCS, such as GIT or SVN.
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.
Use CTools That Ships with a Pentaho GA Release •
Definition: Pentaho
•
Rationale: Different
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. 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
•
Rationale: Being
working in remote servers, and make sure you can replicate the production set-up as much as possible. 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
•
Rationale: By
your business requirements before starting your technical discussion. Make sure to include your UX team from start to finish. 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
•
Rationale: Functional
definition lists for each component that will feed all dashboard sections. These components should have information regarding input parameters, listeners, and external dependencies. 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
•
Rationale: Complex
ideally support 8-10 queries, which can all run asynchronously.
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. cat egor y>
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.
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 nonsupported 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 don’t 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 pr eExecut i on functions for each component. Rationale: Styling is easier to maintain if it is centralized in one place with CSS, especially with many dashboards. The pr eExecut i on 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 pr eExecut i on 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, sal esObj is the container for the sales component, which is a table using the sal es Quer y with the sal esPar amor 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 can’t 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 dashboard’s production by maintaining control of your column’s 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 post Fet ch and pr eExecut i on. 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 post Fet ch step. Rationale: Post Fet ch operations are done on the client, which affect performance in a more unpredictable manner.
Options for Dropdown Selectors • •
Definition: These
components can use j Quer y- 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 j Quer y- UI add-ins. In the existing plugins, the Sel ect 2 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 f or mat Text 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 i f r ame integration is done in the same way for all of them. Rationale: Even though i f r ame integration may not be ideal for some CTools cases, it makes sense to move away from it, since we must deal with actual i f r ame limitations.
RequireJS for Native HTML Integration •
•
Definition: The
latest stable release of CTools support the AMD framework with r equi r eJ S, which allows for a robust embedding with the OEM’s parent applications. Rationale: While both Native HTML: get Header s| get Cont ent and r equi r eJ S approaches are possible at this point with CTools, it is very likely that only the r equi r eJ S 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