Management Center definitions

The Management Center framework uses configuration information within XML files to control the display and behavior of objects that are available and used in Management Center. These XML files are referred to as definition files.

All definition files are included in the workspace_dir\WebContent\WEB-INF\src\xml directory and subdirectories. When you create your own custom definition files include the files under this directory within a custom subdirectory. Do not include custom files under the commerce subdirectory.

Definition files can include one or more definitions. There are three types of definitions that are used in Management Center definition files: class definitions, class instance definitions, and singleton definitions.

Class definition: Class definitions define the classes that are used by the Management Center application. The element name of a class definition is the unqualified name of the superclass. If the superclass is not found within the "cmc/foundation" package, the package name, such as "cmc/catalog" must be included in the value for the package attribute to fully identify the superclass definition name. All class definitions must also include the classDefinition attribute with the value set to "true".
Class instance definition: Class instance definitions define instances of classes. In a class instance definition, a defined class instance is differentiated from all other instances of the same class by different values for the class variable names. The name of the class instance definition element is the name of the class for which the definition is an instance. If the package name of the class is not "cmc/foundation", then the class instance definition must include the package attribute to identify the package name. A definition declaration is assumed to be a class instance declaration when both the classDefinition and the singletonDefinition attribute are not specified. You cannot add JavaScript logic by defining methods or handlers for class instance definitions.
Singleton definitions: A singleton definition defines a singleton class, which restricts the instantiation of a class to a single instance. This single instance is created when the corresponding Asynchronous Module Definition (AMD) module loads. The name of the singleton definition element is the name of the singleton superclass. If the superclass is not found within the "cmc/foundation" package, then the singleton definition must include the package attribute. All singleton definitions must include the singletonDefinition attribute with the value set to "true".

Depending on the objects and behavior that is defined within a definition file, the file is grouped into one of two categories of files: restricted or customizable.

Restricted files: Restricted files include class definitions for the basic functionality that is common to all tools within Management Center. Since these restricted files can be replaced when you install maintenance fixes or upgrade HCL Commerce, do not change these files. All files within a restricted directory are restricted files.
Customizable files: Customizable files describe the objects that are managed within a Management Center tool and defines how to display the objects. When you install maintenance fixes or upgrade HCL Commerce, your customization files are maintained. You can use, extend, or change the classes within customizable files when you are customizing Management Center.

File and definition structure and definition dependencies

Each definition file is named after the main definition within the file. For example, the file BundlePrimaryObjectDefiniton.xml includes the definition "cmc/catalog/BaseBundlePrimaryObjectDefinition", which defines the base, or primary, object from which all catalog entry bundles and inherited bundles are derived.

Within every definition file is the root element <Definitions>. Within this root element, every child element must be either a definition or an image declaration. Any other type of element is ignored or is flagged as an error. Definitions can include configuration information to define tools, business objects, and views. Definitions must be defined as an direct child of the root <Definitions> element. To define these definitions and image declarations, different elements and attributes are used. For more information about these definition components, see Definition file components.

Each definition within a definition file is named, in camel case, by using the package name, the object that is being defined, and the class name suffix. For example, the definition name for the find all categories search definition is "cmc/catalog/FindCategories".

A definition can use or depend on other definitions within the same definition file or on definitions that are defined within other files to help define an object. For example, a definition can include a method declaration that references, or depends on, a class or a singleton definition to use the object or view that is defined within that definition. A dependency on another definition is declared by defining a <dependency> element as an direct child element of a definition element.

A <dependency> element must include the moduleName and localName attributes. The moduleName attribute identifies the definition name of the AMD module that generates from the definition that is being referenced. The localName attribute identifies the variable name that is being used within local JavaScript code.

If you are creating or customizing a definition to depend on a class definition, you must remove the reference the module variable with .Class to access the class definition. If your definition depends on a singleton definition, you must remove the reference the module variable with .Singleton to access the singleton definition.

A definition can also be extended without directly changing the original definition or the file that includes the original definition. You can extend a definition by creating another definition that identifies the definition that is being extended as the base definition. Use the baseDefinition attribute to set the name of the definition that is being extended.

For example, the following code snippet identifies the primary object definition for products that extends the "cmc/catalog/BaseCatalogEntryPrimaryObjectDefinition" definition and has a dependency on the "cmc/catalog/CatalogResources" definition.


<Definitions>
  <PrimaryObjectDefinition baseDefinition="cmc/catalog/BaseCatalogEntryPrimaryObjectDefinition" 
    definitionName="cmc/catalog/BaseProductPrimaryObjectDefinition" detailsViewHeaderText="${catalogResources.UtilityPaneHeaderText}" 
    displayName="${catalogResources.product_DisplayName}" displayNameProperty="partnumber" helpLink="tasks/tpnaddpr.htm" 
    idProperty="catentryId" isBaseDefinition="true" newDisplayName="${catalogResources.product_NewDisplayName}" 
    newObjectMenuItemText="${catalogResources.contextMenuNewProduct}" objectGroups="CatalogEntry,Products,CatalogEntriesNotASKU" 
    propertiesDefinition="cmc/catalog/ProductProperties" searchType="FindAllCatalogEntries">
  <dependency localName="catalogResources" moduleName="cmc/catalog/CatalogResources"/>
  ...	 
  </PrimaryObjectDefinition>
</Definitions>

Creating and customizing definition files

You can customize existing definition files or create definition files to define the display and behavior of your own custom objects. If you do plan to create and customize definition files, ensure that you follow the guidelines and best practices for customizing Management Center. For more information, see Management Center customization best practices and modeling guidelines.

When you add or change definition files in the workspace_dir\LOBTools\WebContent\WEB-INF\src\xml directory and subdirectories, you do not need to restart your HCL Commerce server. The new and changed definitions are automatically detected by the module servlet by the timestamp of the definition files. You do need to restart Management Center by closing the Management Center browser window and clearing the browser cache.

Differences in definition files from HCL Commerce version 7

In HCL Commerce version 7, definition files referred to XML structured files with the .def file extension. These files were typically business object or property definition files. In version 8, these files are converted to the XML structure for class definition files and include the .xml file extension. All OpenLaszlo (lzx) files from version 7 are also converted to definition (.xml) files in version 8. With this change, the workspace_dir\WebContent\WEB-INF\src\lzx\commerce directories and workspace_dir\WebContent\config\commerce directories from version 7 are merged to become the workspace_dir\WebContent\WEB-INF\src\xml\commerce directory. All definition (.xml) files are in this directory or its subdirectories.