Tag: #extensions

After some weeks of hard work we are happy to announce that Skipper now supports also Gedmo extensions. New version with the support is so far available as beta, you can download it from a post about Gedmo extensions on our support forum.

Because Gedmo extensions support needed a lot of changes in the application, we are now looking for beta testers who will try it. So if you have a project with Gedmo extensions you are very welcomed to import them in your Skipper model and let us know, whether everything works as expected. We will be really glad for your help :-)

Gedmo extensions support is now available only for Doctrine 2 framework. But this is only temporary, as soon as the beta will be properly tested, also a support for MongoDB ODM will be added.

In this short article I want to show you how to execute another application from ORM Designer script. Since the version 1.4.2 ORM Designer has built-in a new script command called “execute-file” serving to launch the foreign applications from script. (1.4.2 is now obsolete, please download latest version from //http://www.skipper18.com/en/download)

By using parameter “working-dir“ we can specify a working directory for executed command. If no param is passed, the directory where executable file is located is used. Parameter “show“ serves to launch application in invisible mode and parameter “wait-for-exit” servers to wait until external application has finished its work and then continues with script.

Overloading export script

Now let me show you another new feature of ORM Designer 1.4.2. It can happen that you need to call your own executable when ORM Designer finishes export from model to ORM framework definition files. So we prepared new overloading points in export script, where you can write your own functions which will be called in this points.

Overloading basis

Method overloading in ORM Designer script is processed by method names and prefixes. The simplest way is by defining a function with specific name. ORM Designer runs this function when it is available.

Sometimes we need to distinguish functions for concrete type of ORM. In this case ORM Designer offers prefix overloading ability. ORM Designer tries to find several prefixes when searching for specific function.

These prefixes have fixed order and priority, so we can define a specific version of some ORMs and one common function for the rest of ORMs.

Order and prefixes are defined in following list. At first ORM Designer tries to find the function with “MVC.ORM.” prefix. As next ORM Designer tries “ORM.” prefix, then “default.” and then without prefix.

ORM Designer stops the function search after a function with correspond name has been found .

Now, if you need to create a custom function which is called anytime when ORM Designer exports model to ORM Definitions, follow next steps. As first, we create a file onfinish-export.uscript.xml (or any other name with “.uscript.xml” extension) in user configuration directory (more about user configuration files). As next, enter following script snippet to the created file:

Now, every time when ORM Designer exports a model it will execute one of these functions, based on the project ORM type.

Conclusion

Currently, a support for user-callbacks in scripts is limited only to export scripts. In future, we would like to add more callbacks places depending on users’ requirements. If you have any questions about this topic, feel free to contact us.

Part VII: How to write an export script

In this part of our serie I want to show you how to create an export script for your ORM framework. I’m going to show you basic script commands and how to communicate with ORM Designer project from the script. For an advanced usage of script language it is recommended to study the original ORM Designer scripts for Doctrine, Doctrine2, Propel and other frameworks located in Scripts folder in ORM Designer installation folder. Basic syntax of ORM Designer script is based on Phing XML language.

projectID: This variable will contain internal ID of project to export.

exportToOneFile: This variable will contain “c:\project.out.xml” in first command-line case, and is empty in second case.

First simple script

Now let’s add few commands to our export script. As first step we tell ORM Designer to export the selected project to a single temporary XML file and then copy this file to the output file determined by command line param:

By using “if” and “not-equal” we test if variable “exportToOneFile” isn’t empty. If it is true, we execute export statements which saves the whole project to one file.

“get-tmp-file-name” command assigns a unique temporary file name to variable tmpOneFileExport. Attribute “dir” serves to setup usage of subdirectory in temp directory. Result temporary file in our case will look like “….\temp\ormd-export\tmpXXXXXX.tmp”.

By using a next command “ormd-export-file” ORM Designer exports project with a certain ID into output XML file determined by output XML attribute.

The last command will copy file from the temporary location to a destination path determined by exportToOneFile variable.

This script isn’t much useful yet, but helps us to demonstrate how ORM Designer proceeds data export and allows you to examine how XML file exported from ORM Designer looks like. With this file we will do the next transformations and operations in next parts of this tutorial.

XSLT transformation

The next important step in import and export scripts are the XSLT transformations. Now I’m going to show you how to transform an exported ORM Designer XML file to another XML file required by your ORM framework. Let’s replace our previous script by following new one:

By using the command “xsl-transformation” we will perform XSLT transformation by using XSL template passed by “xsl” attribute (path is relative to script location). Other two attributes determine input and output XML file. Next new command which I use in this example is “delete-file”. After we procees all required steps, it’s a good practice to clean up all temporary files. So we delete both of them.

Hint:

If you want to store results from your script for debug purposes to some folder, you can use following statement:

This template creates XML with root element “import-export-document” which contains several “import-export-file” elements. These elements will contain copy of exported model from ORM Designer. We will use this prepared XML later in this tutorial to split file to several output XML files.

Advanced export script

In previous paragraphs I showed you few simple examples of export script. Now let’s look at more complicated export which exports data to several xml files. In this example I want to show you next new commands and scripting technique. First I’m going to show you a full script listing and then explain every single step.

Split transformed XML file by root children to separated files. These files will be stored in temp/ormd-export folder. List of the files will be stored in $splitFiles variable.

Now enumerate all splitted files one by one.

Copy splitted file to debug location.

Read value from splitted file by using xpath expression “/import-export-file/@import-path” to variable $destination_path.

If variable @import-path isn’t filled, skip next expressions and proceed next file.

Call next XSLT transformation on splitted file. File is again stored in temp with postfix “_2”.

Copy transformed file to our debug location.

Save exported and transformed result to destination file or append it to passed one-file path.

Delete temporary files from this cycle.

Delete another temporary files from this script.

Pretty simple, right? ;-). There is a lot of things that can be done by ORM Designer scripting language. But this sample should be sufficient to learn you how to create the export scripts for your framework. This script with both XSLT templates could be downloaded here: Final export script example.

Script execution

Now you can run this script in one-file export mode and also in full export mode. When you run this script by using “-output-orm-file c:\project.out.xml” param, file project.out.xml should content this:

As you can see, this is not valid XML file. This file is useful in unit-testing stage of your development process. You can simply compare result from export to some required pattern file. If you want to export data in the same format in which your users will see them, use second command line parameter “-output-export”. After that, two files “models\app.xml” and “models\plugin.xml” will be created.

In this example I showed you how to create the export script for ORM Designer. This topic might be a little complicated to understand, so if you find anything understandable, please leave us a comment bellow the post or contact me on [email protected] If you are seriously interested in creating of support for your ORM Framework, please let us know. We will prepare the support for you for free if you have large enough community which can be interested in. If you have your own company framework and want to prepare support for your internal ORM, please let us know too, we also offer creating of an ORM support for company customers.

Part VI: How to define an import/export from ORM Designer model to ORM

Now lets look on next important step for ORM framework support implementation into ORM Designer. It is a data import and export between ORM Designer and ORM framework. Both of these steps are implemented separately and don’t have to solved at all. In some framework for example it isn’t needed or possible to do import. That’s why only a support for data export from ORM Designer into ORM is created. In order to make import/export as flexible as possible, XML script language springing from Phing language syntax is used for script writing.

Firstly lets show how to set in our configuration which scripts should be used for import/export:

During ORM framework configuration is possible to enter 3 different scripts:

script-import: script used during model import into ORM Designer

script-export: script used during export from ORM Designer to ORM definitions

script-import-files-scanner: script serving to automatic finding of all definition files during automatic import

ORM Designer automatically loads all the scripts which are saved in files with mask *.uscript.xml. These files can be stored in anywhere in %ORM_Designer_Path%\Config or in %User_Application_Data%\OrmDesignerCore\config. Concrete location of these files can be found in ORM Designer configuration window at System Info tab:

Script files

Now we are going to show how the file with a simple script looks like. In directory %User_Application_Data%\OrmDesignerCore\Config\AtomixORM we create a file AtomixOrm.uscript.xml. Into this file we enter following XML fragment:

By this we have created the scripts which will be executed during the data import or export.

Initial values description

Each script has several initial values which we check by the command <check>. Here is their list.

Import script

lstFiles:a list of files to import

projectID: project ID to which the files should be imported

Export scirpt

projectID:project ID from which we will export

exportToOneFile: This variable determines an output file of project export when project have to be exported to one file.

Import scanner scirpt

directory: Determines a directory in which the files for import should be found

Conclusion

In this article we have shown how to configure and create basic scripts for ORM Designer. In next parts of serial we will step by step describe how to implement single scripts together with the explanations of some script language commands. If you have any question about this or following chapter, don’t hesitate and ask us directly here on the blog or you can contact us at [email protected]

Part V: how to specify inheritance support

In this part of the serial we are going to show how to configure inheritance types for ORM Designer. Regarding to fact that each framework may support different inheritance types, ORM Designer allows to define inheritance types by the XML configurations.

Again we start with an example from our configuration file AtomixOrm.cfg.xml:

Part IV: How to predefine values in ORM Designer

In this part of serial lets show how to pre-set some initial values for our framework.

In the case we use ORM in a combination with MVC framework, a directory structure for data saving is exactly specified. In this case it is possible to set default values in ORM Designer configuration files, which are used during creation of new objects in a model.

Now lets go through single params of attribute <supported-orm> together with an example of their usage:

default-new-module-file-name and default-new-module-path These attributes serve to set initial value during a creation of a new module. File-name determines a name of file, path determines a relative path to file with a project (*.ormdesigner). The result path is then composed from module-path and module-file-name as shown in following picture.

default-first-module-file-name, default-first-module-path and default-first-module-name These attributes serve to set attributes of initial module which is created together with a new project. Module-path and module-file-name determine relative path to project, module-name determine visual caption of newly created module.

default-export-module-data-format and default-export-module-path By these setting we can automatically define a format for data export into ORM framework. More about data export in chapter VI - import / export. Each newly created module (including the first module created with new project) has set this export format and export path.

script-import-files-scanner This param serves to set a script which is used during automatic data import of our framework. More about this param in chapter VI - import/export.

If you have any question about this or following chapter, don’t hesitate and ask us directly here on the blog or you can contact us at [email protected]

This article is a part of serial about implementation of a support for an own ORM into ORM Designer. Now we are going to show how to add definitions of single properties which are specific for our ORM framework. Each ORM framework has several specific properties which uses for its configuration. By these properties you can modify entity behaviours, a way of work with fields etc. Therefore ORM Designer has a complex system for definition of these properties.

Here is an article describing all options of ORM properties configuration. How to configure new ORM properties and data types. Then we recommend to check up other ORM frameworks configurations where you can find many of ORM properties definitions (available in application directory OrmDesignerCore\config). These definitions can serve you as examples of all options of usage.

Now lets show how we can set several attributes for entity and field in our AtomixORM framework.

<orm-configurationname="AtomixORM"><attributename="TABLE"><attributename="useTable"type="string"help="Custom database table name"/><attributename="cacheQueries"type="bool"help="Whether or not to cache queries for this entity."/></attribute><attributename="COLUMN"><attributename="readonly"type="bool"help="Checks if a field is modified."/></attribute></orm-configuration>

After saving of above mentioned definition into our configuration file (and restarting ORM Designer) we can see following properties in ORM Designer:

Element description <attribute>

In our example we define 2 attributes for the entity and 1 for the field. The attribute definition is proceeded by writing down the element <attribute> with attribute name including one of following enabled values:

Part II: define ORM data types

In this part of the serial about a support implementation for an own ORM into ORM Designer we are going to show you how to configure ORM framework data types. Each ORM uses its own types that reflect the framework orientation and usage. That’s why ORM Designer offers the possibility of all types setting.

If you have defined ORM data types as shown in our XML example, during an entity editing you should see following data types in field editor:

Element description <orm-data-type>

For the data type defining use an element orm-data-type. Here is a description of all its attributes:

name This is the only one attribute which is required. It includes a data type name.

unified-name By this attribute it is possible to enumerate the data types that are transformed into a specific ORM data type during an import from external applications or another sources. For example when is a model imported from a database. All the columns with datatype TEXT,LONGVARCHAR,VARCHAR and CHAR will be transformed to ORM data type string. All the datatypes in “unified-name” attribute have to start with char @.

primary-key-data-type By this attribute is defined which of datatypes is used as datatype for automatically created primary keys. If more datatypes have this attribute, the first found attribute will be used.

has-enum-values By this attribute are marked the datatypes of enumeration type. Currently using of this attribute has no influence on any ORM Designer functionality. We recommend to fill this attribute because it can be used in future ORM Designer versions with new functions implementation.

If you have any question about this or following chapter, don’t hesitate and ask us directly here on the blog or you can contact us at [email protected]

Introduction

Currently there exists a batch of smaller, rising or corporate ORM frameworks which can also benefit from ORM Designer. In next parts of this serial we are going to show how to easily implement a support for an own framework in ORM Designer.

The whole implementation is very simple and customizable. Configuration consists of settings of several configuration XML files, implementation of XSLT templates for data import and export from ORM Designer format into ORM framework native data and writing scripts that process the single steps and these configuration (the script arises from the syntax of script language Phing).

In these articles we are going to describe how to create a support for imaginary framework AtomixORM. Step by step we are going to show the implementation of required parts for allowing ORM Designer to work with target ORM.

Part I: create basic XML configuration for our framework.

We start with a creation of basic configuration file AtomixOrm.cfg.xml. We place it to a user’s configuration repository (more information you can find in the article Configuration files location and validation), which is in this directory:

%User_Application_Data%\OrmDesignerCore\config\AtomixORM

We are assuming that besides ORM you have also some MVC framework which this ORM uses. In our case we call the MVC framework as AtomixMVC. Hence, we write into our configuration file the following code:

By this code we define our AtomixMVC and AtomixORM. Now if you restart ORM Designer you should see the following screen during new project creation.

Note: For more information about the single elements and its all allowed attributes look at XML schema for configuration files - configuration.xsd. This and other schemata for all types of XML files are available in an application directory in subdirectory Schema (i.e.: “c:\Program Files (x86)\OrmDesignerCore\Schema”).

If you have any question about this or following chapter, don’t hesitate and ask us directly here on the blog or you can contact us at [email protected]