Customization Details
After a report exists, there are a number of ways to customize various aspects of the report:
• Customizing Macros
• Customizing Query Builder Types
For reports using custom input pages, additional customizations are supported:
• Customizing the Report Output Format
• Customizing the Report Generation Client
• Customizing the Report Generation URL
Customizing Macros
Customizing macros uses the standard Windchill application services delegation mechanism. This customization example creates a new macro to automatically compute a cutoff time.
1. Create a class that implements the MacroExpressionProcessor interface by performing the following steps:
a. Create a new package or use an existing one. Name the package, for example, myPackage.
b. Create a new class and inherit from the MacroExpressionProcessor interface in the wt.query.report package. Name the class, for example, TimeCutoffMacroProcessor.
c. Compile the class.
d. Fill in the implementation of the buildExpression( ) method. This implementation reads the current system time in milliseconds, computes the new time, and creates a new Date. The Date value is returned as a wt.query.DateExpression. This is necessary because of special handling of dates in SQL expressions to take into account Java representation of dates and timezone settings.
public class TimeCutOffMacroProcessor implements MacroExpressionProcessor {
@Override
public ColumnExpression buildExpression( Element a_element, Map a_parameterMap ) throws QMLException
{
final int DAYS=3;
long currentSeconds= (System.currentTimeMillis()/1000);
long timeSeconds= currentSeconds - (60*60*24*DAYS);
java.util.Date time= new java.util.Date(timeSeconds * 1000);
return (ColumnExpression) DateExpression.newExpression(time, Timestamp.class.getName());
}
@Override
public Object getValue()throws WTException{
final int DAYS=3;
long currentSeconds= (System.currentTimeMillis()/1000);
long timeSeconds= currentSeconds - (60*60*24*DAYS);
java.util.Date time= new java.util.Date(timeSeconds * 1000);
return time;
}
}
e. Fill in the implementation of the getValue( ) method. This value is the actual Date value as computed in the preceding step. This method is called to populate Report Builder input fields when a macro is specified as a default value.
2. Create a logical name for the macro and map it to the implementation class. For example, for logical name "TIME_CUTOFF" and class "myPackage.TimeCutoffMacroExpressionProcessor", the entry would be as follows:
wt.services/svc/default/wt.query.report.MacroExpressionProcessor/
TIME_CUTOFF/java.lang.Object/0=myPackage.TimeCutoffMacroProcessor/singleton
The OOTB entries that exist in dbservice.properties.xconf are:
<Service context="default" name="wt.query.report.MacroExpressionProcessor">
<Option cardinality="singleton" requestor="java.lang.Object"
selector="CURRENT_TIME" serviceClass= "wt.query.report.CurrentTimeMacroProcessor"/>
<Option cardinality="singleton" requestor="java.lang.Object"
selector="CURRENT_USER_NAME" serviceClass= "wt.query.report.UserNameMacroProcessor"/>
<Option cardinality="singleton" requestor="java.lang.Object"
selector="TIME_CUT_OFF" serviceClass="ext.mypkg.TimeCutOffMacroProcessor"/>
</Service>
3. Create a new report query that uses the new macro by performing the following steps:
a. Open the existing Foldered query and save it as a new query, for example, FolderedModified.
b. Remove the criteria based on cabinet name.
c. Add criteria. On the Criteria tab, set the following values as shown in the following table:
|
Field
|
Value
|
|
Class
|
Foldered
|
|
Attribute
|
thePersistInfo.modifyStamp
|
|
Operator
|
>
|
|
Value
|
TIME CUTOFF
|
The TIME_CUTOFF macro is now available for use in reports from the Criteria tab of the Query Builder.
d. Save the query.
4. Execute the report.
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$$.
Customizing Query Builder Types
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:
wt.services/rsc/default/wt.query.report.ClassName/
wt.index.Indexable/java.lang.Object/0=wt.index.Indexable
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:
wt.services/rsc/default/wt.query.report.ClassName/
myPackage.myClass/java.lang.Object/0= myPackage.myClass
This is necessary only if the class does not implement the NetFactor interface, but does have subclasses that implement the Persistable interface.
Customizing the Report Output Format
|
|
This customization is supported for reports using custom input pages.
|
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.
Customizing the Report Generation Client
|
|
This customization is supported for reports using custom input pages.
|
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).
|
|
In previous releases, reports that used subtypes (that is, types created using the Type and Attribute Management utility) needed to be processed using the report commands (See the com.ptc.core.query.report.command.common package entry in your installed Windchill Javadoc for more information). The ReportTemplateHelper APIs now directly support subtypes and customer-created attributes. While report commands are still supported, they are no longer required.
|
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:
• Independence from individual XSLT implementations (for example, Saxon, the XSLT processor library currently in use)
• A high-level abstraction for XML source that hides the details of a particular implementation (for example, String, Java IO stream, DOM, or SAX)
• A clean API for XSLT operations in Windchill
• Easy-to-use, high-level facilities for complex chaining of XSLT transformations
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.
Customizing the Report Generation URL
|
|
This customization is supported for reports using custom input pages.
|
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.
|
URL Parameter Name
|
Description
|
|
jrb
|
Name of a Java resource bundle for localization of result column headers. The provided XSLT stylesheets are all capable of localizing the result column headers if the name of a Java resource bundle is provided to them. This is intended to allow for re-use of a single query to support multiple locales because the report template user interface provides no means of entering strings per locale.
|
|
format
|
Specifies the format type: formatDelegate or formatCustom. This parameter is used only if the report template object has no XSL specification.
|
|
delegateName
|
Specifies the delegate name to obtain an XSL stylesheet from Windchill codebase. The delegate name must match a value specified in the dbservice.properties file. This parameter is used only if the report template object has no XSL specification and the format URL parameter has a value of "formatDelegate".
|
|
xsl1
|
Specifies a URL for a custom XSL stylesheet. This stylesheet is applied immediately to the query result and can generate direct output to the user, or output suitable for input to another XSL stylesheet. This parameter is used only if the report template object has no XSL specification and the cformat URL parameter has a value of "formatCustom".
|
|
xsl2
|
Specifies a URL for a custom XSL stylesheet. This stylesheet is applied to the output of the first XSL stylesheet (specified by xsl1) and should generate output to the user. This parameter is used only if the report template object has no XSL specification, the format URL parameter has a value of "formatCustom", and the xsl1 URL parameter has been specified.
|
