Auto Include support in CDF

2 blog posts in one day - I'm on a spree!


This is a great feature in the Ctools (specially cdf / cda combo) package. The ability to automatically include the result of certain queries.

Imagine the following scenarios:

I want to have my date selector to default to the last day my etl ran to avoid spikes in the data

or

I want to have specific defaults per user on my selectors

The traditional way to do  this is to manually add queryComponents to CDF and then play with the postExecution / postFetch parameters. It works, but not practical at all to tweak the life cycle around this methodology.

This is what Auto-Includes are for!  Just drop a .cda file in a specific directory under solution:/cdf/include/mypath and it will be available for all dashboards under a mypath directory.

Here are the full details of this feature, available already in the stable Ctools packages (and obviously in the development packages too)

Query Auto-Including

CDF supports adding the results of CDA queries to the context. The default configuration file will take any CDA file within the solution:/cdf/include/ folder hierarchy and include all queries therein, with their default parameters, in any dashboard whose path, relative to the solution root, is within the same path as the CDA file, relative to solution:/cdf/include/.As an example, if you have a CDA file in solution:/cdf/include/aFolder/myQueries.cda, then the dashboard solution:/aFolder/myDashboard.wcdf would include all queries from myQueries.cda, as would a dashboard located at solution:/aFolder/anotherFolder/myOtherDashboard.wcdf. A dashboard located at solution:/someOtherFolder/myThirdDashboard.wcdf, however, wouldn't include those queries. Partial matches will also work, without the full solution path

Rule format

The auto-include rules follow the following template, where all the Patterns are understood as regular expressions:

<autoinclude>
<cda>cdaPattern</cda>
<ids>idPattern</ids>
<dashboards>
<include>includePattern</include>
<include>includePattern_2</include>
<exclude>excludePattern</include>
  ...
<include>includePattern_n</include>
</dashboards>
</autoinclude>  

Such a block should be interpreted as follows:

• This auto-include rule pertains to any and all CDA files whose path matches cdaPattern.
• The dashboards element may have any number of include and exclude elements, in order of importance (from least to most important). the includePattern_n/excludePattern_n patterns may contain backreferences to capture groups in the cdaPattern.
• The path for the dashboard being executed will be tested against the include/exclude patterns, in order of importance. The dashboard will auto-include a CDA's queries if it matches at least one include rule, unless it matches a subsequent exclude rule (unless it matches a further include rule, etc).
• If the dashboard qualifies for auto-insertion, all queries from the matched CDA whose dataAccessIds also match idPattern will be executed and included in the dashboard's context object.

 

The Default Rule

The default rule for auto-inclusion serves as a good example of what can be achieved with the rule format:

<autoinclude>
<cda><![CDATA[cdf/includes/(.*)/(.*?)\.cda]]></cda>
<ids>.*</ids>
<dashboards>
<include><![CDATA[/$1/.*\.wcdf]]></include>
<include><![CDATA[/$1/.*\.xcdf]]></include>
<include><![CDATA[/$1/.*\.cdfde]]></include>
</dashboards>
</autoinclude> 

Note that most of the patterns are wrapped in blocks, obviating the need for escaping any reserved XML characters within the regexps.
As you can see, the cda element defines that this rule will match any CDA file whose path looks like /solution/cdf/includes/(.*)/(.*?)\.cda— this will match all files within /solution/cdf/includes/ that have at least one more folder in the path, and end with the .cda extension. The two capture groups will capture the file path, and the (extension-less) filename.

The include patterns all specifiy paths starting with /$1/ (the path capture group), meaning, the path begins the same as the previously matched CDA file's, and ending with .*\.wcdf (or cdfde/xcdf), so matching all paths that start the same as the CDA file, but possibly having more folders in the path . The three rules differ only in the file extension they allow (covering CDF and CDE dashboards). The ids pattern specifies a loose pattern — any id matches, so once a match has been made between a dashboard and a CDA file, all queries in that CDA will be inserted into the dashboard's context.