Definition file components

The definitions that Management Center uses to determine how to display objects, such as tools, business objects, views, and more, are defined within definition XML files. Each definition within these files are composed of a set of common elements and attributes.

Within every Management Center definition XML file is the root element <Definitions>. Within this root element, every direct child element is either a definition element or an image declaration. All other types of elements are ignored or are flagged as an error.

The definition elements within the root element can include different subelements and attributes to define the information for displaying tools, business objects, views, and more. Each definition must be defined as an direct child element of the root <Definitions> element. Each definition element must include the definitionName attribute to identify the definition. The definition element name is the unqualified name of the superclass definition.

The value of the definitionName attribute is the same name as the AMD module that generates from the definition. The definitionName value and AMD module name must include the relative path for the package and the simple name for the definition. For example, the definitionName value for a check box property, is "cmc/foundation/BaseCheckBox". "cmc/foundation" identifies the component package, and "BaseCheckbox" identifies the simple name for the definition.

Along with the definitionName attribute, the following elements and attributes can be used to create definitions within a definition file.

Variables

Variables are defined within a definition by including the <variable> element. All variables in definitions are instance variables. If you are creating your own definition or customizing a definition, you can define variables for class and singleton definitions. You cannot define <variable> elements for class instance definitions. When you define a class instance definition, you can, however, specify values for variables by defining attributes as part of the class instance definition element. The name of the attribute in the class instance definition element must be the same as the name of the variable.

When you define a class definition or singleton definition, you can specify values for inherited variables also by defining attributes as part of the definition element. The name of the attribute in the definition element must be the same as the name of the variable. If you precede the attribute value with ${ and terminate the value with }, then the value is interpreted as an expression. If the expression value changes, then the variable updates automatically. You cannot use expression syntax when you are specifying variable values for class instance definitions.

When a variable is referenced in JavaScript, the variable is accessed as a property of an instance of a class or of a singleton definition. If you need to modify the value of a variable in JavaScript, use the setVariable method. By using this method, you ensure that events trigger correctly.

<variable> elements can have no child elements and no body. <variable> elements can include the following attributes:
Attribute name Description
name The name of the variable.
type The type of variable. Variables can be defined with the following types:
  • string
  • boolean
  • number
  • expression
value The value of the variable. The value that is set for a variable depends on the variable type.
initialValue The initial value of the variable. This value is set only when the variable is initialized. It is not updated when the expression changes.

Methods

Methods are defined within definitions by including the <method> element. These elements can be declared as a child element of class definitions or singleton definitions. You cannot include <method> elements within a class instance definition.

You can override a method within a subclass by declaring a method that has the same name as the method that you want to override. Use the following syntax to call the overridden method from within the override method. The arguments that are passed to the overridden method are the same as those passed to the override method.
this.inherited(arguments)
The body of a <method> element is the JavaScript body of the method. <method> elements can have no child elements, but can include the following attributes:
Attribute name Description
name The name of the method.
args A comma-separated list of argument names.

Handlers

Handlers are defined within definitions by using the <handler> element. <handler> elements can be declared as a child element of class definitions or singleton definitions. You cannot include <handler> elements within a class instance definition.

The body of a <handler> element is the JavaScript body of the handler. <handler> elements can have no child elements, but can include the following attributes:
Attribute name Description
name The name of the event for the variable. All variables have an associated event name. The event name is "onVariableName" where VariableName is the name of the variable.
eventSource An expression that identifies the event source. Do not include this attribute if the event source is the current object.

Resource Bundles

Resource bundles are declared as a class instance definition. The base class definition for resource bundles is the cmc/foundation/ResourceBundle class definition.

The following code snippet shows how to declare a resource bundle within a definition file:
<ResourceBundle baseName="com.ibm.commerce.foundation.client.lobtools.properties.FoundationLOB" 
definitionName="cmc/foundation/FoundationResources" singletonDefinition="true"/>
When you reference a resource bundle string within a definition, you must include the resource bundle in a dependency element. The following code shows how to define a resource bundle in a dependency element: 
<dependency localName="pageLayoutResources" moduleName="cmc/pagelayout/PageLayoutResources"/>
If you are defining class or singleton definitions, refer to resource bundle strings by first identifying the resource bundle singleton. Then, specify the resource bundle key instance and the string property. The following code shows how to refer to resource bundle strings for class and singleton definitions:
pageLayoutResources.Singleton.layoutSlotTooltip.string
When you are defining a class instance definition, you can set the value of an inherited variable that is defined in a resource bundle by using the following simplified syntax: variableName="${<resourceBundleModuleLocalname>.<resourceBundleKeyName>}" The following code shows how to set a variable with this syntax: 
promptText="${pageLayoutResources.pageLayoutAssignmentList}"
Note: You do not need to define instances of ResourceBundleKey for all keys. The module serving servlet for the Management Center framework checks the specified resource bundle for the keys and automatically includes the ResourceBundleKey instances within the generated AMD module.

Child definition elements

Definitions are hierarchical. You can define child definitions for a definition that are implicitly created when the parent, or base, definition instance is created. Definition child elements are similar to definition elements. The name of the element must be the name of a class. If the class is not found in the default package, "cmc/foundation", the package attribute must be specified to identify the package. Other attributes can be used to provide values for inherited variable values. The child elements within a child definition element must not include <dependency> elements. All dependencies must be specified as direct child element of the base definition element.

Do not specify the classDefinition or singletonDefinition attribute for child definition elements. Variable attributes for class and singleton definition child elements follow the same rules as class and singleton definition elements.

You can use the ${ } syntax to specify expression values for variables. Variable attributes for class instance definition child elements follow the same rules as class instance definition elements. You cannot use the general expression syntax to set variables, but you can use the simplified resource bundle key syntax.

Definition child elements can be assigned names by using the name attribute. This variable is a variable of the base definition instance, which you can use to refer to child definition instances by name. The parent of a definition instance is found in a property that is named parent.

For example, if you want to restrict the width of a definition instance to be the same width of the parent definition instance less four pixels, declare width="${this.parent.width – 4}". If you want to constrain the width of a definition instance to the width of another child definition instance that is named "a", declare width="${this.parent.a.width}".

Image declarations

Image declarations are used in definition files to associate simple names with image files or sets of image files that can used to represent different states of an image. For example, an image can have different states based on how a business user is interacting with the image, such as normal, hover, and selected. Image declarations can be for images with a file extension of .png, .gif, or .jpg.

If an image consists of a single image, the <Image> element can be declared as a direct child of the root <Definitions> element in a definition file. <Image> elements include the following attributes:
Attribute name Description
src The URL to the image file.
name The name of the image. This name must uniquely identify the image.
If an image can have different states, which requires multiple images, the <ImageSet> can be used to include all of the images. This element must include a name attribute that uniquely defines the image set. Each image within the set, must be defined in separate <Image> child elements of the <ImageSet> element. Management Center uses the currentImage variable to select the appropriate image to use within an image set. The first <Image> element that is listed within an image set is considered image "1". You do not need to include a name attribute for the individual images within an image set.

Predefined AMD Modules

A number of predefined AMD modules area available for use in definition files. These modules are coded directly in JavaScript and are not defined in any definition XML file. You can use these modules to help you create your own definitions within definition files.

The cmc/foundation/Node module defines the base class for all definitions. You can use the following variables with the Node class:
Variable Name Type Description
UID number The unique identifier of the module. This property is a read-only.
module object The module object. This property is a read-only.
moduleName string The module name. This property is a read-only.
id string A global identifier for creating a unique instance of this node. Set this variable for only definitions that can result in a single instance. The object can be accessed by name by referencing the named property in the cmc/foundation/SingletonRegistry module.
classroot Node When a class definition is instantiated, the root object can be accessed by any of the declared descendants through the classroot property. This property is a read-only.
name string When a child definition is instantiated, the child object can be accessed as a property of the parent object through the specified name.
defaultplacement string The name of a child definition view to which new children are to be attached. That is, the immediateParent of the new child instance.
initstage string A hint to the framework that indicates how this node should be initialized. The following values are recognized by the framework:
  • normal (default) – initialize this node with its parent
  • defer – do not initialize this node until the completeInstantiation method is explicitly invoked.
placement string The placement for this node.
inited boolean This variable indicates whether the node is initialized. This property is a read-only.
isinited boolean Like the inited variable, this variable indicates whether the node is initialized. This property is a read-only.
parent Node The parent node of this instance.
immediateParent Node The direct parent node of this instance.
childNodes Array of Node An array of child node instances.
You can also use the following methods with the Node class:
Method name Arguments Description
completeInstantiation None Use this method to complete the initialization of a node that is created with initStage="defer".
init None Override this method to provide initialization logic for the node. Ensure that your override method includes a call to this.inherited(arguments)
destroy None Override this method to release resources that are used by the node. Ensure that your override method includes a call to this.inherited(arguments)
setVariable variableName – the name of the variable. value – the new value for the variable. Use this method to set variable values explicitly in JavaScript. By using this method, you can ensure that event handlers are called correctly.