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 dataor
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 thesolution:/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 pathRule 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 ofinclude
andexclude
elements, in order of importance (from least to most important). theincludePattern_n
/excludePattern_n
patterns may contain backreferences to capture groups in thecdaPattern
. - 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 oneinclude
rule, unless it matches a subsequentexclude
rule (unless it matches a furtherinclude
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:Note that most of the patterns are wrapped in
<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>
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.