Basic Customization > User Interface Customization > Adding Actions and Hooking Them Up in the UI > Action Framework for Windchill Client Architecture > Defining a New Action
  
Defining a New Action
Actions in the system are uniquely identified by the name of the action and the object type. They should be defined in an XML file that follows the structure based on codebase/config/actions/actions.dtd.
Here is an example of an action definition for the New Document window.
<objecttype name="document" class="wt.doc.WTDocument"
resourceBundle="com.ptc.windchill.enterprise.doc.documentResource">
<action name="create" uicomponent="CREATE_DOC" dtiUpload="true">
<command
class="com.ptc.windchill.enterprise.doc.forms.CreateDocFormProcessor"
method="execute" windowType="popup" onClick="validateCreateLocation(event)"/>
<includeFilter name="projectM4D" />
<nonSupportedTypes value="wt.part.WTPart"/>
<supportedTypes value="wt.doc.WTDocument"/>
</action>
</objecttype>
objecttype Tag
The objecttype is a way to create a name space as well as packaging for actions related to a specific object or functional area. In the above example, the name “document” creates a unique name space for actions that apply to wt.doc.WTDocuments.
Naming conventions for the name of an objecttype can be any combination of alpha-numeric characters. Most objecttypes are an alias for the persistable object to which the actions relate. Actions that apply to any object type, such as copy, can be put within the objecttype of “object”.
* 
PTC recommends that all custom objecttypes have a prefix specific to the company to prevent collisions with object types delivered with the product.
The table below describes the valid parameters for objecttype. Details about these parameters can also be found in codebase/config/actions/actions.dtd.
Parameter
Default Value
Possible Values
Req?
Description
name
any combination of alpha-numeric characters
Yes
The name used to reference this object type.
class
A valid Java class
Yes
Object class for the enclosed actions
resourceBundle
Any valid resource bundle class name
No
Class name for the default resource bundle to use for the properties of the actions that are to be localized
action Tag
The action name is a unique identifier for an action within the context of the object type. The object type in conjunction with the action name make the action unique within the system.
By default, the action name corresponds to the name of a JSP within the package named for the object type. The packaging is relative to codebase/netmarkets/jsp. For example, the action name in the XML example above is “create.” Within the document object type, this corresponds to codebase/netmarkets/jsp/document/create.jsp.
Naming conventions for the name of an action can be any combination of alpha-numeric characters.
* 
PTC recommends that all your custom actions have a prefix specific to your company to prevent collisions with names of actions delivered with the product.
The table below describes the valid parameters for action. Details about these parameters can also be found in codebase/config/actions/actions.dtd:
Parameter
Default Value
Possible Values
Req?
Description
name
Yes
This is the name by which the action is referenced
cad
false
true
No
Indicates if this action is only valid within the Creo embedded browser
installType
WINDCHILL
PDM
PDM
PJL
PDM
No
Applicable actions based on the installed components. This is for legacy purposes only.
multiselect
false
false / true
No
Used to indicate that multi-selection of row data can be used for this action. This is true only if the selectRequired attribute is also set to true for such an action.
selectRequired
false
false / true
No
Determines if the user interface should allow the action to proceed if nothing has been selected. Otherwise, an error message appears.
* 
If an onClick action handler is defined, the onClick function must check if items are selected. To do this, call the JavaScript function table.getSelectionModel().hasSelection()
afterJS
No
JavaScript function name to invoke on the client side validation for an action window step after the step is completed.
beforeJS
No
JavaScript function name to invoke on the client side validation for an action window step after the step is loaded
afterVK
No
Server validator name to invoke client side validation for an action window step after it is finished.
beforeVK
No
Server validator name to invoke client side validation for an action window step when the step is loaded.
id
objecttype .action
No
Overrides the ID of the action window step.
preloadWizard Page
true
false
true
No
Specifies that the action window step is to be downloaded when the action window is launched
hidden
false
false
true
No
An action window step to be hidden first, or that an action is rendered as non-clickable
required
false
false
true
No
Used for an action that represents a complete step in the action window. Specifies that the step is required.
resourceBundle
No
Class name for the resource bundle to use for the properties of the actions that are to be localized
renderType
PDM
No
Default
http://<host> /<webapp>
General:
http://<host> /<webapp> <command.method>
General with context:
http://<host> /<webapp> <command.method> ?oid=...
PDM: URL generated by URLactionDelegate; used for template processing
uicomponent
No
References an entry in roleaccessprefs.xml (uic.name) to specify role-based access.
preloadJS
No
The JavaScript function executed before an action window step is loaded or displayed.
postloadJS
No
The JavaScript function is executed after an action window step is loaded into memory, but before it is displayed to the user.
Command and Component Attributes
If necessary, place a <command> or <component> tag in the body of the <action> tag to define the processing aspects of the action.
<command
class="com.ptc.windchill.enterprise.doc.forms.CreateDocFormProcessor"
method="execute" windowType="popup" onClick="validateCreateLocation(event)"/>
Or:
<component name="my.component.id" windowType="page" />
• The class attribute defines what class to use for processing.
• The method attribute defines what method to execute in the class.
• The windowType attribute determines what window action to take.
In the example above, the command is for the New Document action, which is an action window (a wizard). Therefore, the windowType is “popup.” The framework adds JavaScript that launches this action in a new window. The specified class and method are executed upon submission.
Command Parameters
Parameter
Default Value
Possible Values
Req?
Description
class
No
The class to use for processing.
method
No
The method in the class to execute.
url
No
Used to override the generated URL
This attribute can be used to specify the location of the JSP associated with the action. The value should be the path of the JSP relative to <Windchill>/codebase.
onClick
No
Specifies an additional onClick function to call. This is useful for confirming with the user whether to execute a special action.
For certain places where actions are used (such as a menu bar or the toolbar on a table), onClick needs to be a valid expression for an “if” statement. Therefore, onClick should just be a call to a function.
The following are in scope variables that the onClick function can pass as arguments:
• event — The browser event
• target — The object representing the user interface component that was ‘clicked’
• table — The table that contains the action. This is null if the action is not contained within a table.
onClick should not contain semi-colons or return statements. For example:
• Correct:
onClick="doFoo()"
onClick="doFoo(event)"
• Incorrect:
onClick="doFoo();doBar();"
onclick="doFoo();Event.stop(event);"
* 
The use of the HTML-encoded character "'" to use a single quote is not necessary; just use a regular single quote instead.
When the actions are parsed, the action framework tries to repair troublesome definitions. If they cannot be repaired, then the onClick function is replaced with an alert. Warnings are logged if the action was repaired; otherwise errors are logged.
If the selectRequired attribute is set on the action, then the onClick handler is called before any other handlers. Thus, the onClick handler must check if there are items selected in the table.
windowType
page
new
no_content
normal
popup
wizard_step
No
new—Looks similar to other windows, but is launched differently. All of the form data is submitted to the popup window, making more information available. However, the extra form data might overlap with form data already in the popup. It might be easier to override the action URL to add additional information.
no_content—The browser ignores the response from the server from this request. This value is not recommended, rather create and Ajax request manually through a JavaScript function.
normal—Submits the form.
page —Display a new page.
popup—Create a non-modal popup action window.
wizard_step—Displays the action as a step in an action window.
Component attributes are very similar to the command attributes. But instead of providing a direct URL, the URL is generated given the MVC component ID. The MVC component can determine the correct URL in the MVC delegate. See MVC Components for more information.
Component Parameters
Parameter
Default Value
Possible Values
Req?
Description
name
Yes
The MVC component id that should be used to display when this action is clicked.
componentType
INFO
PICKER
SEARCH
TABLE
WIZARD
WIZARD_TABLE
WIZARD_ATTRIBUTES_TABLE
INFO_ATTRIBUTES_TABLE
SIMPLE
MINI_INFO
PRIMARY_ATTRIBUTES
No
The componentType affects whether objects rendered on the resulting page are editable, read-only, or validated out. Values are from com.ptc.core.ui.resources.ComponentType
The component type can change the URL to typeBased under certain conditions such as INFO. Some actions are only available under certain component types.
urlParams
URL parameters that are added to the generated MVC URL each time the action is rendered
typeBased
false
true
Determines if the MVC delegate lookup should include the type of object being acted upon. The MVC URL that is generated is /tcomp/ instead of /comp/ for type-based components.
onClick
No
Specifies an additional onClick function to call. This is useful for confirming with the user whether to execute a special action.
For certain places where actions are used (such as a menu bar or the toolbar on a table), onClick needs to be a valid expression for an “if” statement. Therefore, onClick should just be a call to a function.
The following are in scope variables that the onClick function can pass as arguments:
• event — The browser event
• target — The object representing the user interface component that was ‘clicked’
• table — The table that contains the action. This is null if the action is not contained within a table.
onClick should not contain semi-colons or return statements. For example:
• Correct:
onClick="doFoo()"
onClick="doFoo(event)"
• Incorrect:
onClick="doFoo();doBar();"
onclick="doFoo();Event.stop(event);"
* 
The use of the HTML-encoded character "'" to use a single quote is not necessary; just use a regular single quote instead.
When the actions are parsed, the action framework tries to repair troublesome definitions. If they cannot be repaired, then the onClick function is replaced with an alert. Warnings are logged if the action was repaired; otherwise errors are logged.
If the selectRequired attribute is set on the action, then the onClick handler is called before any other handlers. Thus, the onClick handler must check if there are items selected in the table.
windowType
page
new
no_content
normal
popup
wizard_step
No
new—Looks similar to other windows, but is launched differently. All of the form data is submitted to the popup window, making more information available. However, the extra form data might overlap with form data already in the popup. It might be easier to override the action URL to add additional information.
no_content—The browser ignores the response from the server from this request. This value is not recommended, rather create and Ajax request manually through a JavaScript function.
normal—Submits the form.
page —Display a new page.
popup—Create a non-modal popup action window.
wizard_step—Displays the action as a step in an action window.