JSP and Tags
Several tags and taglibs are delivered as part of the framework. These taglibs contain a set of handlers for including components and other common functionality into your pages. The basic steps to produce many components (table, tree, property panel, wizard, etc.) are:
• Describe the component (JSP)
• Acquire the necessary data (Data Acquisition Tags)
• Render the component (Component Renderer Tags)
The configuration of these phases is done by calling the tag handlers in the JSP Page. To use the tags, you need to include the components library. The following code snippet includes the library:
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
Controller — JSP
• Basic Elements of the JSP
You will need to be aware of a few important jsp fragment files. The first and most important is the begin.jspf. This files exists in codebase/netmarkets/jsp/util/. The purpose of this jspf is to:
◦ Include a tag for rendering the shell that surrounds all pages.
◦ Take care of housekeeping like:
▪ Instantiates the beans (context, clipboard, etc)
▪ Executes a command (for actions only)
▪ Includes some JS functions
▪ Creates ONE form for the page data (called mainform)
▪ Provides support for closing pop ups and refreshing the main page
Another jspf that is included is the end.jspf also located in codebase/netmarkets/jsp/util/. The purpose of this file is:
◦ mark the begin and end of the content area for DHTML content switching
◦ catch exceptions and handles them if they occur within the page
When constructing a wizard, there is a special beginWizard.jspf file, located in netmarkets\jsp\components, that should be used instead of the begin.jspf that will do essentially the same things as the begin.jspf.
• Component Description Tags
Component description tags are the first tag included in the jsp. These generally take the form of describe*Tag. (E.g. DescribeTableTag)
Component Description Tags define the columns/properties that the component will display. This happens first in a JSP since the way the data is retrieved may depend on the properties that are requested. During the component description phase the developer uses a “describe” tag handler that tells the infrastructure about the component they would like to display. One example describe handler is the describeTable, which might look like the following:
<jca:describeTable var="tableDescriptor" id="my.table.id" configurable="true"
type="com.myco.MyType" label="${myLabel}">
<jca:setComponentProperty key="actionModel" value="my action model"/>
<jca:describeColumn id="name"/>
<jca:describeColumn id="nmActions" />
<jca:describeColumn id="status">
<jca:setComponentProperty key="percent" value="true"/>
</jca:describeColumn>
</jca:describeTable>
Structure of the example
The tag contains a set of nested tags which give it some structure. There are two kinds of nested tags:
◦ setComponentProperty
This tag configures the properties of its parent tag that aren’t exposed as attributes of the parent tag itself. This gives the infrastructure and the developer some flexibility about the metadata they’d like to be available down the road, without always requiring a tag library definition (tld) update to do so.
◦ describeColumn
This tag describes a particular column that the developer wants to display. Like the parent describeTable tag, this tag accepts child setComponentProperty tags. There is also a describeProperty tag that has the same semantics when used in property panels.
Underneath the covers, the describeTable tag is simply configuring a java bean that implements the ComponentDescriptor interface. The attributes that are available via the tag handler typically correspond to properties of the ComponentDescriptor. The ComponentDescriptor object is important to keep in mind as it comes into play later on during the data acquisition phase.
The ComponentDescriptor object that the describe tag handlers build is communicated to the rest of the world via the required "var" attribute. The handler creates a scoped variable for the ComponentDescriptor object named whatever the var attribute value is. In the example above, the var attribute was mapped to "tableDescriptor", but it can be mapped to any legal JSP variable identifier. Note that this semantic for the var attribute is reused from the JSTL tag handlers. Since the ComponentDescriptor object is a scoped attribute, it can be referenced later in the page using the JSP EL as well as Java code. Subsequent tags can now refer to the descriptor using the ${varName} syntax, for example.
Model — Data Acquisition Tags
The necessary model data is acquired through data acquisition tags. These generally take the form of get*Tag. (E.g. getModelTag)
The Data Acquisition Tag will be the second phase and will come second in your jsp. This is because the Data Acquisition Tag gets the model data based on the description from Component Description Tag. In the data acquisition phase, the developer combines a component description with some additional information on how to actually go and get the data that will back the component. One example of getting a model for a table might look like the following:
<jca:getModel var="tableModel" descriptor="${tableDescriptor}"
serviceName="com.myco.MyService"
methodName="getMyObjects">
<jca:addServiceArgument value="${myArgument}" type="java.lang.Long"/>
</jca:getModel>
Structure of the example
• descriptor and var
The tag gets a component description by using the EL to look up the scoped "tableDescriptor" variable. The tableDescriptor variable would typically be put in the page by a previous describe tag that had a var value of "tableDescriptor".
Like the describe tags, the get tags produce a java bean that is added to the page as a scoped variable named with the var attribute value. In the case of the get tags, the resulting bean is an instance of ComponentModel.
• What is it doing?
Developers typically don't interact with the ComponentModel object produced by the get tags. Instead, the developer provides information on some lower-level API that the client infrastructure invokes and then transforms into a ComponentModel. The sample code above, for example, will invoke the com.myco.MyService.getMyObjects(myArgument) method, take the results, and turn these into a ComponentModel object.
View — Component Renderer Tags
The view is rendered by the Component Renderer Tag. These generally take the form of render*Tag (E.g. RenderTableTag)
This produces HTML and JavaScript based on the model data. Rendering using Component Renderer Tags is usually simple for the developer to set up. The Windchill Client Architecture provides a few render tags that take the ComponentModel produced by a “get” tag and turns it into HTML and JavaScript. Like the get tags, these tags uses the EL to accept scoped variable data from the page:
<jca:renderTable model="${tableModel}"/>
Structure of the example
In this case, the table renderer is taking an input ComponentModel assigned to the scoped variable "tableModel", and rendering it as a table.
Supported Components
• Wizard (Create/Edit)
• Table
• Tree
• Property Panel
• Attribute Table
Additional Resources
• Tag Library Documentation
The Windchill Tag Library Documentation is delivered with the product and can be accessed through the UI. To locate the documentation, first enable the customization examples and tools, then browse to the customization navigation and select the tools option.
Under the API documentation section of the page you will find a link to the Windchill Tag Library Documentation
• Related Customization Documentation