Configuration File Structure


The main part of the ORM framework configuration is stored in Skipper XML configuration files. You can easily extend or change these files to customize Skipper for your own needs.

Configuration file name

Skipper looks for the XML configuration files based on the file names. This means that valid configuration files must use specific extension to be recognized. The extension is following:

\*.skipper.cfg.xml

XML configuration file structure

Every XML configuration file has root element skipper-configuration. Configurations are defined in four types of child elements:

  • global-configuration defines global settings available for all frameworks.
  • orm-configuration defines the ORM framework specific configurations.
  • mvc-configuration defines the MVC framework specific configurations.
  • mvc-support-orm connects and configures specific combination of MVC and ORM.
  • extension-configuration defines external extension for specific ORM framework
  • orm-support-extension connects and configures specific combination of ORM and extension
<skipper-configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <global-configuration />

  <orm-configuration name="Doctrine2" image="logoDoctrine2.png" caption="Doctrine2">
  </orm-configuration>

  <mvc-configuration name="Symfony2" caption="Symfony2" image="logoSymfony2.png">
  </mvc-configuration>

  <mvc-support-orm mvc-name="Symfony2" orm-name="Doctrine2" />

  <extension-configuration name="GedmoExtension" caption="Gedmo extension">
  </extension-configuration>

  <orm-support-extension orm-name="Doctrine2" extension-name="GedmoExtension"/>

</skipper-configuration>

Note: All these elements can contain the same types of configuration child elements. Based on the location of these child elements their values will be used for specific ORM, MVC or MVC+ORM combination.

ORM and MVC frameworks definition

Every framework is explicitly identified by its name. When more definitions with the same name are found these configuration elements are merged. Configurations are loaded in the following order:

  • Global configurations.
  • MVC configurations.
  • ORM configurations.
  • ORM+MVC configurations.
  • Extension configurations.
  • ORM+Extension configurations.

Note: The load order and merging of the definition types works similar to configuration files load order.

This means that in case you define the same setting (with different value) in global context and ORM context, setting with ORM context will be used. Following examples show configuration element for Doctrine2 ORM and Symfony MVC. First example is Doctrine2 configuration:

<orm-configuration name="Doctrine2">
  <application-settings> ... </application-settings>
  <script-settings>...</script-settings>
  <import-export-formats>...</import-export-formats>      
  <attribute-types>...</attribute-types>
  <inheritances-types>...</inheritances-types>		
  <data-types>...</data-types>
  <element-templates>...</element-templates>
</orm-configuration>

Next example shows configuration element for Symfony MVC.

<mvc-configuration name="Symfony">
  <application-settings> ... </application-settings>
  <script-settings>...</script-settings>
  <import-export-formats>...</import-export-formats>      
  <attribute-types>...</attribute-types>
  <inheritances-types>...</inheritances-types>		
  <data-types>...</data-types>
  <element-templates>...</element-templates>
</mvc-configuration>

Last example illustrates how to define data types available only when Doctrine2 ORM is used with Symfony MVC. The configuration element for this combination looks like this:

<mvc-support-orm mvc-name="Symfony2" orm-name="Doctrine2">
  <data-types>...</data-types>
</mvc-support-orm>

Configuration subelements table

Subelement tag Description
application-settings defines special functionality, usually conected to single feature or single function
script-settings contains information about script files and functions. Importing and exporting ORM models is done via scripting
import-export-formats describes formating of ORM definitions i.e. XML, YML.
attribute-types definitions of framework-speciffic attributes
inheritances-types inheritance model for given framework
data-types contains data types definitions
element-templates contains naming conventions and possibly default names for entities in the ORM model

Application settings

These settings are used to enable specific behavior of Skipper application, model elements or some functions. They are most often connected with on ORM specific features, user request or custom features.

<application-settings>
 <setting name="Model/Association/AllowAssociationToNonPk" value="true"/>
</application-settings>

All available switches you can find in XML reference manual.

Scripting, Import, Export

Following example shows how to define a script file and a script function in the configuration file. Scripting language used in Skipper to extend scripting in Skipper is JavaScript and files have the .osc extension.

<script-settings>
  <script-file name="Doctrine2.import.osc"/>
  <function type="import-function" name="Doctrine2Import"/>
</script-settings>

ORM Attributes

This element defines the ORM attributes for specific framework. Attributes for Project, Module, Region, Entity, Field, Association, ManyToMany, ManyToManyEntity, Inheritance, Index and Comment can be defined inside the attribute-types element. Detailed description how to configure ORM attributes is available in a standalone article.

<attribute-types>
  <struct name="Module">
    <struct name="options">
      <attribute name="charset" type="string"/>
      <attribute name="collate" type="string"/>
      <attribute name="type" type="string"/>
    </struct>
    ...
  </struct>
  <struct name="Entity">...</struct>
</attribute-types>

Entities inheritance

This element describes inheritance types for specific ORM framework.

<inheritances-types>
  <inheritance-type name="SINGLE_TABLE" caption="Simple"/>
</inheritances-types>		

Data types definitons

Each ORM framework has its own data types used in the entity field definitions. These types are defined in data-types section of the configuration file.

<data-types>
  <data-type name="boolean" unified-name="@BOOL"/>
  <data-type name="integer" unified-name="@INTEGER,@INT"/>
</data-types>
param description
name name of the data type
unified-name list of posible aliases for the type. Used during import.
has-enum-values mark datatype as the enum type

Templates and naming conventions

Skipper uses the definitions in this element to customize templates. Templates will help you to set the rules and naming conventions for new entities and associations.

<element-templates>

  <template element='entity' use-case='user-create'>
    <entity name='NewEntity'>
      <field name="id" type="integer" required="true" unique="true" primary="true"/>
      <field name="name" type="string" size="255"/>
      <orm-attributes><attribute name="table">db_{entityName#UL}</attribute></orm-attributes>							
    </entity>
  <template/>

  <template element='field' use-case='wizard-create' selector='association-field'>
    <field name="__{inverseEntityName#UL}_{inverseFieldName#UL}__"/>
  </template>

<element-templates/>					

Dynamic words

Dynamic words are used to customize Skipper GUI, so it better reflects ORM or MVC framework you are using. At the moment only the Module dynamic word is supported.

<dynamic-words>
	<dynamic-word name='module' value='bundle' />
</dynamic-words>