After a report exists, there are a number of ways to customize various aspects of the report:

For reports using custom input pages, additional customizations are supported:

Customizing macros uses the standard Windchill application services delegation mechanism. This customization example creates a new macro to automatically compute a cutoff time.

For reports that use macros in criteria or default values, Query Builder evaluates the macro at runtime and displays the resulting value in the Criteria pane of the report generation window. It is also possible to use a macro as input in a Criteria pane input field. The macro name should start and end with the $$ characters to denote the value as a macro. For example, to use the out-of-the-box CURRENT_USER_NAME macro in an input field, enter the value as $$CURRENT_USER_NAME$$.

Query Builder uses object model information to present the list of all possible types to build queries against. It does this by searching for all types that implement the wt.fc.NetFactor interface. However, there may be classes that do not implement the wt.fc.Net.Factor interface, yet have subclasses that implement the Persistable interface and therefore can be used in queries. An example is wt.index.Indexable. To allow queries to be built using these types, these types can be listed as resources in a service properties file. The out-of-the-box entry in dbservice.properties handles the Indexable interface as follows:

To customize the list of Query Builder types, new entries can be added. For example, for the class myPackage.myClass, the entry would be as follows:

This is necessary only if the class does not implement the NetFactor interface, but does have subclasses that implement the Persistable interface.

Several report output formats are provided out-of-the-box. All of these formats are intended to be general purpose. That is, they should produce reasonable output from any query. If none of these formats are appropriate, you can modify them or create completely new formats.

All of the HTML report formats provided, except those derived from Microsoft Word, use a CSS1 stylesheet to specify font, color, size, and spacing details. Use of CSS1 allows these details to be separated from other aspects of page layout and placed into one or more re-usable stylesheets. Therefore, the easiest way to customize these aspects of the HTML reports is to edit the CSS files that they use. For further information about CSS1, refer to the W3C CSS1 specification, currently available at the following URL: http://www.w3.org/TR/REC-CSS1

Two CSS files are involved: htmlFormat4Print.css and htmlFormat4Screen.css. Both are located in <Windchill codebase>/templates/reports. The htmlFormat4Print.css file is intended to specify the appearance of HTML when printed and the htmlFormat4Screen.css file when viewed on screen. Actually, browsers do not support this aspect of CSS and, therefore, the printed output is controlled by htmlFormat4Screen.css as well. However, you may prefer htmlFormat4Print.css to htmlFormat4Screen.css, which is designed primarily for consistency with other Windchill HTML pages.

To change the CSS stylesheet used by a report or to make larger changes to the output format than possible through CSS1, you must customize XSLT stylesheets as described in the next section.

As mentioned earlier, reports are produced by applying XSLT stylesheet transformations to XML query results. This includes all the out-of-the-box formats. XSLT stylesheets are capable of producing not only any HTML layout but also any other XML or text format.

XSLT stylesheets are based on the concepts of templates and rules. Most XSLT stylesheets are largely composed of XML or HTML tags and text that are static; that is, included verbatim in the output. The remainder of the stylesheet is then composed of rules for computing the dynamic portion of the output from the input XML. Depending on the mix of templates and rules, the nature of XSLT customization can vary from simple HTML authoring to pure programming. For the definitive specification on XSLT, refer to the W3C XSLT specification, currently available at the following URL: http://www.w3.org/TR/xslt

For additional information about XSLT, refer to the “What is XSLT?” link and the “Resources” area currently available at the following URL: http://www.xml.com

One technique for customizing the output format is to modify one of the XSLT stylesheets that are provided in <Windchill>/codebase/templates/reports/. These stylesheets are described in detail in the following table.

Due to the template-based nature of XSLT, some modifications can be made to the provided stylesheets based almost solely on a knowledge of the intended output format (such as HTML). For example, the provided formats that use CSS1 stylesheets generate the references to these files using the following lines in the XSLT stylesheets:

The only part of these lines that is not strictly HTML is the portion within the { } braces which, though similar to JavaScript expression usage, is actually an XSLT XPath expression. In this case, the expression is referencing the variable windchill, which was previously assigned the URL of the Windchill codebase.

One aspect of the provided XSLT stylesheets is that they use XML resource bundles for localization of text. Rather than producing different versions of each XSLT stylesheet for each locale, the locale-dependent text has been extracted into separate XML files. These are loosely referred to as XML resource bundles, and are retrieved and searched through XSLT based on the locale.

This approach was taken for the following reasons:

The XML resource bundles used by the provided XSLT stylesheets are located at <Windchill codebase>/templates/reports/defReportRB_*.xml.

If you decide to use this technique in your own XSLT stylesheets, see the XML resource bundles provided and the XSLT files provided for usage examples. Keep in mind the following issues:

 

Besides modifying existing XSLT, you can also author entirely new XSLT stylesheets. You can author new stylesheets using the following steps:

The number and complexity of transformations to be done in step 3 can vary greatly from one format to another and largely determine the effort involved in creating a new format. XSLT provides extensive capabilities for sorting, filtering, summing, and combining XML data. Additionally, you can provide XSLT extension functions and elements that call other languages, including Java and JavaScript. See the Saxon documentation for further details.

Understanding the query result XML format is extremely important to successfully retrieving the desired data from it using XSLT (or any other technique). An outline of this format is shown below. The portions in bold represent dynamic data and ellipses (...) represent omitted items.

If an entire Windchill top-level object (a Persistable) is selected, additional attributes are generated on the column tag element, including the object ID, branch ID (if the object is versioned), and classname of the object. WTUser objects also include email attributes. These attributes are generated primarily to facilitate generation of hyperlinks. Out-of-the-box XSLT stylesheets for HTML and PDF formats use these attributes whenever they are present to produce hyperlinks to the objects.

Additional flexibility for generating hyperlinks is provided by use of the characters $$ in column names. If a column name containing $$ is specified through the Query Builder, an individual cell is not created for it; instead, the name is parsed as follows. If the part of the column name preceding $$ matches another column name that does not contain $$, its data is added to the other column as an attribute, which is determined by the part following $$.

For example, assume the following columns are specified through Query Builder:

Each XML row would then contain a Part element like the following:

Rows would not contain individual Part$$branchID or Part$$type columns. This functionality allows you to select the right data to obtain hyperlinks (as described earlier in this section) without having to select entire Persistable objects.

If the column type is java.util.Date, column data is formatted based on the HTTP request's Locale. In addition, the column element has a "value" attribute containing the raw Java string value. If other date-formatting customization is needed, this value could be used.

The table below summarizes the data conveyed by the various top-level elements in the query result XML.

 

To use an XSLT stylesheet as a report format, you must specify it either in the report template user interface or, for report templates that specify their format as “Ask Upon Generate”, upon generation using the HTML report generation form. In either case, two means of specifying formats are allowed: custom and standard.

Specification of custom formats is done using up to two relative or absolute URLs. When the URLs are not absolute, they are relative to the Windchill codebase. When two XSLT URLs are specified, they are applied to the report results in series. The custom specification mechanism allows use of XSLT stylesheets that are not located on the Windchill server and facilitates testing of new stylesheets. It also allows the application of two XSLT stylesheets in a series, which is not possible through the standard format mechanism.

Specification of standard formats is done by selecting one from a list. Most of the provided XSLT stylesheets are part of this list. Additional formats can be added to this list by editing dbservice.properties. These property entries begin with wt.services/rsc/default/wt.query.report.DefaultXSL.

If an existing format is being replaced with a customization, then there may be an additional property entry for the format type that overrides the XSL. This property begins with wt.services/svc/default/com.ptc.core.query.report.client.generation.ReportSAXTransform and should be removed.

The format of these entries is that of the Windchill application services delegation mechanism. If localization of the additional entries is required, edit the Java resource bundle wt.query.template.TemplateResource.

The report generation client consists of an HTML form that can prompt the user for additional report generation input and an HTTP processor that executes the report and applies the XSL transformations. Both of these clients can be customized in the same manner as typical HTML client customizations. For further information, see Customizing HTML Clients Using the Windchill JSP Framework .

In addition, report generation-specific code is available as static methods in a separate class so it can be reused. The ReportTemplateHelper class provides many methods for processing reports (See the wt.query.template.ReportTemplateHelper class entry in your installed Windchill Javadoc for more information).

Both of the clients mentioned above rely on a wrapper API developed for XSLT processors. The API can be found in the wt.xml.xslt package entry in your installed Windchill Javadoc for more information.

This API provides the following functionality:

For additional capabilities beyond those provided through this API, you can use the standard JAXP (Java API for XML Processing) APIs, or access Saxon directly. For further information, see the Saxon Web page, currently available at the following URL:

Note, however, that the XSLT library bundled with Windchill may change in the future and that users of the Windchill XSLT and JAXP APIs will be affected less by any such change.

The report generation form is used to gather additional report input parameters prior to execution. It consists of two main sections: report parameters and output format.

The report parameters section is built from data specified in the query. Given a report query as an XML source, the ReportTemplateHelper buildParameterTemplates( ) method returns an array of ParameterTemplate instances that represent the parameters of the query. The current client accesses this parameter template data to build the form to prompt the user for input. Note that the processing bypasses any parameter templates if the specified name is included in the HTTP parameters (see the section Customizing the Report Generation URL that follows). This is an indirect way to customize the form. For example, fully specifying all parameter values in the report generation URL would cause no parameter input fields to be generated. Also, the current form processing completely bypasses the form and goes directly to the report execution processing if the XSL specification has been set in the report template and all required parameters (if any) have had values specified in the HTTP parameters.

The output format section is generated based on the XSL specification of the report template object. If one exists, the output format section is bypassed. Otherwise, the input fields for specifying the format are generated. The ReportTemplateHelper getAvailableXSLFormats( ) method is used to build the drop-down choice for the standard XSL.

The report generation output relies on the XSLT API. The basic steps are as follows:

The preceding sections describe the current report generation client and some simple customization points. Using the XSLT API, ReportTemplateHelper methods, and report commands as a basis, there are many ways that an entirely new client could be created. However, detailed discussions on this topic are beyond the scope of this document.

The following are possible example customizations:

Understanding the report generation URL is important for customizing applications to seamlessly integrate report generation functionality. The URLs that invoke reports can be created dynamically or set up statically (for example, bookmarked) with known URL parameters. There are two types of report generation URLs: Generate Form and Execute Report. The Generate Form URL requests additional input from the user (only if necessary) and generates a form action button that leads to the Execute Report page. The Execute Report page executes the query and returns output to the HTTP request output stream.

Both of these URLs can be edited directly to add URL parameters. Either the original or the edited URL can be bookmarked or used in a hyperlink for future reuse. The URLs can also be generated programatically. The ReportTempateHelper class provides APIs for each type of URL. Several versions, each taking different parameters, are also available. See the getGenerateFormURL( ) and getExecuteReportURL( ) classes entry in your installed Windchill Javadoc for more information.

The Generate Form URL can have parameter values specified directly. For any parameter names that are specified on the URL, the input field is bypassed. In addition, all URL parameters are passed to the Execute Report URL through the form’s action button. The Execute Report URL also derives all report parameter values from the URL parameters (through ReportTemplateHelper methods). If a URL parameter does not exist for a report parameter, then the report parameter’s default value is used. In addition, several other URL parameters, described in the following table, can be used.