Patterns - Pattern Specification
A pattern is actually composed by of a set of files. The purpose of this document is to describe this files so anyone can define their own pattern. Thes files are:
- Pattern.Definition
- <PatternName>.Config
- Config.Definition
- Generation templates (*.dkt files)
- Special Classes and Interfaces (if needed)
These files must be stored in a folder named with the pattern name in the folder "Patterns" under the folder where the tool were installed.
Pattern.Definition
This file describes the structure of the pattern's
instance file . It's an XML file in which the root node contains general information (such as the name of the pattern, the associated template, etc) and there is one
ElementType node for each different type of element in the pattern instance file.
It can be created/edited with the tool itself using the options: Tools/New Pattern Definition or Tools/Edit Pattern Definition respectively.
Root Node
The first node in the pattern definition specifies general information about the pattern.
- Name: The pattern name. It must be unique for each pattern.
- Version: Pattern version. This version number is used to determine whether the instances were generated with the current version of the pattern or a previous one (for converting, if necessary).
- RootElement: The name used for the root element of each instance file.
- RootType: The type of the root element, which must correspond to an entry of the ElementTypes collection.
- HelperAssembly: For some tasks that cannot be resolved in the pattern definition, such as the implementation of the actions, the pattern can use an assembly (a .Net DLL) that provides this functionality. This assembly must contain .Net classes that conform to certain interfaces, described later.
- DefaultGenerator: The fully qualified name of the class used to generate a default instance of the pattern (when the "New" or "New from Transaction" menu options are run. It must belong to the Helper Assembly and implement the IPatternDefaultGenerator. If no generator is specified, the instances will be created blank and the user will have to fill them manually.
- VersionAdapter: (Optionally) a class that implements the "IPatternVersionAdapter" interface. used to convert instances of a pattern between versions. See PatternsVersionAdapter.
- MetadataManager: (Optionally) a class that implements the "IPatternMetadataManager" interface, used to maintain metadata associated to instances.
BuildInformation Node
- MinGXVersion: Minimum GeneXus version required to use this pattern. Can be set to "8.0", "9.0" etc.
- GeneratorType: Whether the template is available as a DKT file, or precompiled (see below).
- GeneratorFilename: If the "GeneratorType" is "Template", the name of the main template (DKT file) that will be used to generate the GeneXus objects (This file must conform to the PatternTemplateSyntax). If the type is Precompiled, the name of the DLL that contains the precompiled template.
ElementType Nodes
These describe a type of element that can be present in the instance. Each element corresponds to an XML element node in the instance files, and to a node in the treeview when editing them
- Name: The name of the element type, must be unique.
- Caption and CaptionParameters control how the node will be shown in the editor. The Caption actually corresponds to the "caption format" and can reference the parameters by index, while the parameters will be attributes of the element separated by semicolons. For example, if the element has Attribute: {0} - {1} as Caption and Name;Type as CaptionParameters, the node corresponding to the Birthdate attribute would be shown as Attribute: Birthdate - Date.
- KeyAttribute: An attribute can be selected which indicates the "primary key" of nodes of this type. This is used in the Instance Comparer to match corresponding nodes between two instances. This value is optional.
- Validator: This class will be used to validate the contents of nodes of this type. It must be present in the Helper Assembly, and implement the IPatternElementValidator interface.
- Icon: Icon file used for elements of this type in the instance editor.
Each ElementType node also includes:
- A list of Attribute nodes, which describe the attributes of these elements.
- A list of ChildElement nodes, corresponding to elements subordinated to the current one.
- A list of Action nodes, describing custom actions applicable to elements of this type in the tree editor.
Attribute Node
These nodes describe an attribute of a particular Element Type.
- Name: Name of the attribute.
- Type: Datatype of the attribute. Possible values are string, "text", int, bool, and enum{value1;value2;.} in which value1, value2, . are the possible values that the user will be allowed to select. If an asterisk (*) is included as an option, then the user will be able to input an arbitrary value. This can be useful to propose a list of default values, for example by using "enum{5,10,20,*}" as the Type of an hypothetical RowsPerPage attribute. "Text" is similar to "string", however the user will be able to open an editor to enter multiline or long text.
- Category, Description, PrettyName, Visible (all optional): Determine how the attribute is shown in the property grid. If PrettyName is not specified, the attribute name will be displayed.
- DefaultValue: Default value. When the element containing the attribute is created blank, the attribute will have this value. It must match the defined datatype, or an exception will be thrown.
- SerializationType_: Determines how the attribute value if stored in the XML file (by default, as an XML attribute). The possible values are: default, attribute, element, innertext, CDATA.
- ValidValues: The name of the class used to display a combobox to allow the selection of the value. It must belong to the Helper Assembly and implement the IPatternAttributeValidValues interface.
- GXLink, GXLinkClass: This is used to indicate that the attribute will store a reference to a GeneXus object, attribute or domain by its internal id instead of its name. That way, if an object or attribute is renamed inside GeneXus , the link will be maintained.
- NotNull: Indicates that a value for the attribute is required (validated when saving an instance).
ChildElement Node
Indicates which elements belong as a child of the current one.
- Name: Name of the child element in the XML file.
- ElementType: Element Type, must correspond to an ElementType defined in the pattern.
- Multiple: There can be multiple elements of this type, i.e. corresponds to an item in a collection. "Add/Delete" context menu actions will automatically be generated in the tree editor.
- Optional: The element is optional (if true, it won't be created by default, and it can be deleted). Note: Elements marked as Multiple are always optional.
Action Node
Defines a custom action (in the context menu) that can be executed on elements of the current type.
- Name: The name of the action, shown in the context menu.
- Class: The class to execute the action, which must be present in the Helper Assembly and implement the IPatternEditorCustomAction interface.
<PatternName>.Config
Defines many options that apply to all instance files (and which therefore would be unwieldly to set up on each one, like common literals, page size, styles used, etc.) or to the operation of the pattern itself (like settings about how the default instances are generated).
This file is located in the Patterns<PatternName> directory, under the directory where Patterns is installed, corresponding to the default settings for the pattern. Optionally, a copy can exist in the KB's Templates directory; in case it exits, its settings override those of the default configuration. To edit this file from Patterns, use the Tools/Change Pattern Configuration (or Tools/Change Default Pattern Configuration) option from the Menu.
In the Work With Pattern, the WorkWith.Config determines some general aspects applied to all objects. Ex. the styles to be used in the Web Panels, the Web Components to be used as header and footer, etc. See
Work With Pattern for more information.
Config.Definition
The
Config.Definition file describes the structure of the pattern's configuration files (<PatternName>.Config), in the same way as the
Pattern.Definition describes the
instance files When customizing a pattern, changing or adding entries to this file changes the way the configuration file is stored and edited.
Generation templates (*.dkt files)
This are the set of files that control the
pattern instantiation process See
PatternTemplateSyntax .
Special Classes and Interfaces
GXKnowledgeBase and PatternCommon
These assemblies contains classes to read the contens of a Genexus Knowledge Base (by using GXPublic), and process pattern instances. A documentation file describing their classes, interfaces and methods is provided with the Patterns package (ToolsDocumentation.chm).
Containers
The
PatternInstance,
ElementContainer,
AttributesContainer and
ChildrenElementsContainer classes, belonging to the
PatternCommon.Containers namespace correspond to pattern instances and their composing parts. They are public and will be used by actions, validators, etc.
Standard Helpers
There is a special DLL called TemplateHelpers which contains classes that can be useful for most patterns:
- TemplateGeneral: Contains methods for reading an XML file and for output of very basic XPZ entries, such as variable declarations, attribute declarations, etc.
- HtmlToKmw: Used to generate webpanel components (tables, grids, textblocks).
- WinToKmw: Used to generate winform components.
These classes also have XML documentation.