CanQues 2.0 Templates

Last updated: July 12, 2006
Questions or comments to: canques@ims.nci.nih.gov

Overview

The template configuration file, where several report layout properties are specified, makes managing reports' properties easier. A default template for all CanQues projects, templates.cfg, exists at the root of the CanQues hosting site. A custom template configuration file, also named templates.cfg, can be placed in your project directory and can override the default template settings. Multiple report templates may be specified in the template configuration file and be used for the same report data in different occasions.

The following three properties are specified in a template of a template configuration file:

• element order,
• style sheet, and
• HTML title.

The default report properties are set in the default template for all CanQues projects ("global" default template), also named templates.cfg, but at the Canques site root.

Templates and The Template Cofiguration File templates.cfg

The template information exists in an INI-format templates file (templates.cfg). It contains one or more sections that represent individual templates within the same configuration file. The section name (enclosed within the square brackets [ ... ]) is the is the actual name of the template. The lines following the section name, are property-value pair, where a property name is followed by an equal sign =, and then a value string. (See a template configuration file.)

Project Templates vs. Global Templates

A template specified in the project template file (templates.cfg) will override the "global" template. The global (and default) template file (templates.cfg) is located at the root of the CanQues hosting site and is editable only by the CanQues site managers, whereas a project template file is located in the project directory and is optional.

Default vs. Custom Template Sections

The default global template file must contain a template named DEFAULT , which is used by all CanQues reports by default. A project template configuration file may (optionally) have a DEFAULT template, which will force all project reports to be generated with this new default (not the global default template).

Custom, i.e. non-default, templates may be specified in either the global or local template configuration files to provide the capability to generate reports with different properties (i.e. order, order, fonts, title, etc.). If a custom template exists, a report will be generated with this template, only if the template name is specified in the CGI parameters of the request report URL (see the CGI call protocol for more information). A template may also be specified in the CanQues applet, which assembles the request URL (see info on applet CGI parameters).

Precedence of Templates and Properties

If a template name is specified in the CGI parameters of the request URL, then the CGI program will use one of the following templates (if the conditions are satisfied):

• a custom project template: matching the template name specified; if the project template config file exists; else,
• a custom global template: matching the template name; else,
• the default project template: if the project template config file exists; else,
• finally (if all else fails), the global defaul template.

Note: the global default template must exist, or otherwise an error will be generated and no report code produced.

When a template (default or custom) from the global/project templates.cfg file is used for a report, it may have only some or all properties (element order, style sheet, HTML title). If some properties are missing or contain blank values, the following alternatives are attempted (in this order until the value is obtained):

1. If the current template is a custom template, then the property value will be fetched from the respective default template.
2. If the current template is the default project template or there is no project templates.cfg, the property value(s) will be fetched from the default global template.
3. If the current template is the default global template, and the property missing/blank is the:
   
   • style sheet property, the value will come from the global configuration file cq_submit.cfg css_path and css_style properties (currently the defaults are /CSS/cq_submit.css),
   • HTML title property, the default value is "CanQues Results" (hard-coded in cq_request.cpp),
   • element positions property, an error will be generated.

Note: the Style Sheet property of a template can be overriden by the StyleSheet property in the project Canques.cfg configuration file (per database).

Template Properties Explanations

1. Element positions - determines the position of the report elements for each report type.

There are four report types (with their corresponding code names):

• Vertical Bar Graph (VBAR)
• Line Chart (LINE)
• Table Report (TAB)
• Data Delimited Report (DATA) - used to generate data that can be used as input for other programs.

Hence, there are four possible element position properties (for each report type), containing element identifiers in the order wanted:

• VBAR_Element_Positions=selections~report~notes~citation~variables~altformats
• LINE_Element_Positions=selections~report~notes~citation~variables~altformats
• TAB_Element_Positions=selections~report~comments~variables~notes~citation~altformats
• DATA_Element_Positions=selections~dict~report~variables~notes~citation~altformats

The possible (available) elements to use in the property are:

• report - the actual report data (image, or table, or other)
• notes - the notes associated
• citation - citations associated
• selections - the parameters with one value
• variables - the parameters with multiple values
• altformats - if the report can be view in different formats, the element will show links to display these formats.
• dict - dictionary

Elements must be separated from each other with a ~ (tilde). Consult your Canques.cfg file to check what report types your data supports.

2. Style Sheet - determines the style sheet to be used in the report (if any)

Three possible formats for a style sheet are possible:

• full well-formed URL - http://seer.cancer.gov/styles.css
• path relative to the site root (must start with a /) - /CSS/custom_sheet.css
• path relative to the current project directory (must NOT begin with a /) - custom_style4.css (it will implicitly be converted to /<ProjDir>/custom_style4.css )

Make sure you create the style sheet in a well known location and you also have the permissions to create it there.

!!! Note: a separate style sheet may be defined in each database section(s) of your project Canques.cfg; if the StyleSheet property of any database section contains a non-empty value, it will override any template style sheet information.

3. HTML Title - this is the title that appears in the "blue bar" of your browser.