Let´s see how to work with the Patterns Tool.
Use the sample xpz to test the following Steps and generate a Web Application in minutes !
A typical scenario of use involves the following steps:
Create or choose a GeneXus 9.0 KB with some TRNs and create a New Web Model (.NET or Java is recommended).
Execute Patterns Tool: Design Model / Tools / Patterns.
Patterns Tool is a stand alone application too, that can be run independent of Genexus. It's initial screen is:
A dialog box with the title "workspace configuration" will open. This dialog allows to set up:
- Some options related to the KB
- Other options related to the pattern
- Other options related to GX actions (impact the model, specify, generate, etc.) that could be executed using the Patterns Tool
This dialog can be closed at this point, and you can enter it again later selecting Build /Configure GX Integration (see step 7 below).
After that, the Patterns Tool displays some KB information using GXPublic Since many patterns use TRNs, a list of the available TRNs is shown in the KB Explorer tab:
Note: To be able to use a KB from the Patterns Tool, it must be closed from GX and vice versa (that is, to use a KB from GX it must be closed from the Patterns Tool).
Select which pattern apply from a list of available patterns. Use the combo box in the toolbar to select the pattern you want to use. A set of built-in patterns will appear by default, and you can also add your own patterns. See How to write your own Pattern
At this point we need to obtain an Instance File for each case to which the instantiation process will be applied. To do that, instance files could be created from scratch, but it is not very practical, so patterns usually provide a functionality to create default instance files that can be edited later.
In the case of the Work With Pattern it is possible to obtain a default instance file from any TRN. To do this, being positioned in the KB Explorer tab, you must select a TRN, press the right button of the mouse and select the Generate Instance File option. You can do a multiple selection of TRNs (pressing Shift or Ctrl and selecting the desired TRNs) to generate more than one instance file at the same time.
Also an instance file can be generated by double clicking on a TRN.
After that, the instance files can be edited in the right pane. There are two ways to do it: using the Tree View or using the XML View. The XML View allows to edit the instance file directly in its XML format. Since this format isn't very user friendly it is recommended only for advanced users. The Tree View is the most commonly used editor. It's far more user-friendly and provides a greater functionality to help in the editing process (e.g. a combo box for attribute selection, default nodes, etc.).
Below you can see the edition of the instance file created from the Doctors TRN using the Tree View:
Below you can see the edition of the instance file created from the Doctors TRN using the XML View:
The instance files must be saved. For this, you have the following items under the Instance option:
Save - It saves the file that has been selected in the right window of the Patterns Tool (TreeView).
The files that were not saved yet, are visualized with the name: <TRN Name.Pattern>*. And once saved, they are visualized with the name: TRN Name.Pattern.
In the example that we have been analyzing concerning the instance file associated to the Doctors TRN, since we are applying the "Work With" pattern, the name of the file saved will be: Doctors.WorkWith.
And where will the stored instance files be saved physically? In the Templates subdirectory under the KB directory.
Selecting the Folder Explorer tab you will be able to visualize these files:
Save All - It saves all previously generated instance files. If a file already exists, it asks you if you want to replace it, and if the file does not exist it saves it.
It is important to take into account that if you generate the default instance files again from the transactions, they will be overwritten.
Once the instance files were created and edited, at this point the tool will generate the GeneXus objects that implement the pattern for these instances.
The Build / Apply Pattern option allows you to generate a <TRNName>.xpz.xml file for each created/edited instance file, under the KBPathTemplatesImport directory. These files will have to be consolidated it in the GeneXus KB.
Alternatively, if you select the Build / Apply and Consolidate option, a <TRNName>.xpz.xml file will be generated for each created/edited instance file, under the KBPathTemplatesImport directory and they will be consolidated automatically in the GeneXus KB.
By right clicking you can also execute both of these actions: being positioned in the Folder Explorer tab, you can select a created/edited instance file or a group of created/edited instance files (.workwith files), and then execute the Apply Pattern action or the Apply and Consolidate action.
Note: It is also possible to select a TRN or a group of TRNs being positioned in the KB Explorer tab, and execute the Generate, Apply and Consolidate option. But it is important to understand that selecting this option, the default instance files for the selected TRNs will be generated again, and after that, the corresponding <TRNName>.xpz.xml files will be generated and consolidated in the GeneXus KB. If you are sure that the default instance files don't need to be edited, you can select this option directly.
If the Apply and Consolidate option is selected, the following actions are also done:
- Fantastic theme is automatically set as the default theme of the application
- Images directory is automatically copied under KBPathTemplates directory
- "Base image path" design model property is configured with the previous value
The messages are shown in the Output Window. If an error occurs, it is also shown in this window:
To make all the process easier, from the Patterns Tool you can execute the same actions that you execute with GeneXus (e.g.: Impact the model, Specify, Generate, Compile and Execute).
You can configure these actions in a dialog window that is displayed at the moment of opening the GeneXus KB from the Patterns Tool, or you can enter to the same dialog at any time by selecting the Build / Configure GX Integration option.
Below you can see the dialog we are refering to:
KB Path: (disabled, only to be shown)
Pattern: (disabled, only to be shown)
Model Combobox: it offers the models defined in the KB in order to select one of them. The models had to be created and generated before with GeneXus . It is not possible to create them from the Patterns Tool.
"Apply Pattern" frame
Apply and Consolidate Combobox: when the Apply and Consolidate option is selected, there are more actions that can be executed in adition to the the generation of the objects and the consolidation of the resulting xpz files in the KB. This combo offers the following posibilities so that you select one of them:
Note: In case of having configured in this option one of the values that include impacting the model, when the impact is executed, the Images directory will be automatically copied to the DATAXXXweb directory (or to the directory indicated in the "Static content" model property when using the Java generator).
- Consolidate Only (Apply and Consolidate)
- Impact Model (Apply and Consolidate Impact Model)
- Impact, Specify (Apply and Consolidate Impact Model Specify)
- Impact, Specify, Compile (Apply and Consolidate Impact Model Specify Compile)
- Impact, Specify, Compile, Run (Apply and Consolidate Impact Model Specify Compile Run)
GeneXus Version Combobox: The Knowledge Base GeneXus version is automatically detected. The model will be specified / generated using this version.
"Settings for the model" frame
Build Action Combobox: allows you to select which objects must be specified and generated when selecting Specify and Generate. The available options are:
- Build All
- Build Pending (updated since last specification)
- Specify Consolidated Objects
Specification Combobox: allows you to select the type of specification/generation to be executed when selecting Specify and Generate. The available options are:
- Full Specification
- Check Specification
- Force Generation
Run Command: in this option you must indicate the URL to be executed if you select the Impact, Specify, Compile, Run option.
By default Patterns Tools generates a homepage web panel and a procedure to list all WW objects used by homepage. To run a homepage, you must configure Run Command = http://localhost/services/hhome.aspx for .NET applications or http://localhost:8080/servlet/hhome for Java applications.