Data models and forms

Introduction

This document introduces the setting and the administration of data models and forms for the beCPG software. It is intended to beCPG administrators. A video presents the creation of models and forms.

1. Modification du modèle de données (manuellement)

It’s possible to enrich the beCPG model by adding :

  • Properties: text values, integers, data lists etc...
  • Associations: association to an object type ;
  • Objects types: a compound of several properties/associations ;
  • Aspects: group of properties and/or associations which can be added to a type of object. This allows the re utilisation of a group of properties, common to many object types, for example a group of properties « Saleable products ».

This necessitates knowledge of XML and knowledge of content modelisation.

Files

The modification of the data model necessitates the modification of 3 files :

  1. [installLocation>/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/module/becpg-{$client}-core/model/{$client}Model.xml]{style="text-align:left;"} to modify the data model (addition of properties, associations) ;
  2. [installLocation>/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/module/becpg-{$client}-core/model/{$client}Model.properties]{style="text-align:left;"} to define the properties wordings ;
  3. [installLocation>/tomcat/webapps/share/WEB-INF/classes/alfresco/{$client}-form-config.xml]{style="text-align:left;"} to define the formatting of edition and consultation forms.

Where {$client}, is the name of the client.

The modified files [Model.xml]{style="$client;"} et [Model.properties]{style="$client;"} can be copied and pasted in the repertory [installLocation>/tomcat/shared/classes/alfresco/extension/]{style="text-align:left;"} to facilitate the identification of the modified files. The naming convention is the following :

  • ext-{$client}Model.xml
  • ext-{$client}Model.properties

The modified file [-form-config.xml]{style="$client;"} can be copied and pasted in the repertory [installLocation>/tomcat/shared/classes/alfresco/web-extension]{style="text-align:left;"} to facilitate it’s identification. The naming convention is the following :\ ext-{$client}-form-config.xml

In order to take into account the modifications, the application must be restarted by typing : sudo service alfresco restart

Setting of a property

Properties types are :

  • d:date
  • d:text
  • d:content
  • d:int
  • d:long
  • d:any
  • d:float
  • d:datetime
  • d:double
  • d:boolean
  • d:category
  • d:noderef
  • d:path

A property is defined by :

<code class="xml">
  <property name="...">
    <type>Type de données</type>
    <mandatory>obligatoire ou non</mandatory>
    <multiple>Valeur multiple ou non</multiple>
    <default>Valeur par défaut</default>
    <constraints>
       <constraint ref="ID" />
    </constraints>
  </property>
</code>

Example :

<code class="xml">
<property name="bcpg:productType">
    <type>d:text</type>
    <mandatory>true</mandatory>
    <multiple>true</multiple>
    <constraints>
    <constraint ref="bcpg:systemProductType" />
    </constraints>
</property>
</code>

Setting of a constraint

Constraints are defined in the section of the file {$client}Model.xml.

Here are some examples of constraints :

  • Regular expression :
<code class="xml">
<constraint name="test:regex1" type="REGEX">
       <parameter name="expression"><value>[A-Z]*</value></parameter>
       <parameter name="requiresMatch"><value>false</value></parameter>
</constraint>
</code>
  • Length Min/Max
<code class="xml">
<constraint name="test:stringLength1" type="LENGTH">
        <parameter name="minLength"><value>0</value></parameter>
        <parameter name="maxLength"><value>256</value></parameter>
</constraint>
</code>
  • Number Min/Max
<code class="xml">
<constraint name="test:minMax1" type="MINMAX">
        <parameter name="minValue"><value>0</value></parameter>
        <parameter name="maxValue"><value>256</value></parameter>
</constraint>
</code>
  • Data lists
<code class="xml">
<constraint name="test:list1" type="LIST">
        <parameter name="allowedValues">
            <list>
                <value>ABC</value>
                <value>DEF</value>
            </list>
        </parameter>
        <parameter name="caseSensitive"><value>true</value></parameter>
</constraint>
</code>

More details : http://wiki.alfresco.com/wiki/Constraints

Aspects

An aspect is a group of properties or associations which can be applied to a type. An aspect can be mandatory or not.

<code class="xml">
    <aspect name="cm:auditable">
         <title>Auditable</title>
         <properties>
            <property name="cm:created">
               <type>d:datetime</type>
            </property>
            <property name="cm:creator">
               <type>d:text</type>
            </property>
            <property name="cm:modified">
               <type>d:datetime</type>
            </property>
            <property name="cm:modifier">
               <type>d:text</type>
            </property>
            <property name="cm:accessed">
               <type>d:datetime</type>
            </property>
         </properties>
</aspect>
</code>

The addition of a mandatory aspect to a type is done in the section :

.

Example :

<code class="xml">
<type name="XXX">
    <parent>YYY</parent>
    <mandatory-aspects>
        <aspect>ZZZ</aspect>
    </mandatory-aspects>
</type>
</code>

Where ZZZ is the mandatory aspect defined on the type XXX.

2. Form configuration

Logs

The logs file is situated in the following repertory of the server: /var/log/alfresco/alfresco.log

Consultation, edition, creation and search forms

Forms are defined in the file :

/tomcat/webapps/share/WEB-INF/classes/alfresco/{$client}-form-config.xml

« Forms » refer to:

  • Creation form ;
  • Edition form ;
  • Consultation form ;
  • Search form ;
  • Bulk edition form

A form is defined by :

The form type :

  • Creation
<code class="xml">
<config evaluator="model-type" condition="bcpg:finishedProduct">
  <forms>
    <form id="create">
</code>
  • Edition
<code class="xml">
<config evaluator="node-type" condition="bcpg:finishedProduct">
</code>

* Recherche

<code class="xml">
<config evaluator="model-type" condition="bcpg:product">
   <forms>
      <form id="search"/>
</code>
  • Bulk edition
<code class="xml">
<config evaluator="model-type" condition="bcpg:product">
   <forms>
     <form id="bulk-edit"/>
</code>
  • Object type 
<code class="xml">
<config evaluator="node-type" condition="bcpg:finishedProduct">
</code>
  • Fields displayed in the section 
<code class="xml">
<show id="bcpg:legalName" />
</code>
  • The formatting in the section 
<code class="xml">
<field id="bcpg:meatCharacts" set="charact">
    <control template="/fr/becpg/components/form/controls/textarea.ftl" >
        <control-param name="rows">4</control-param>
    </control>
</field>
</code>

Where :

« set » defines the « fields » gathering; « template » defines the « Freemarker » template used to display the field. If nothing has been defined, the system takes the template by default; « control-param » defines a parameter of the « Freemarker » template.

More details : http://wiki.alfresco.com/wiki/Forms

3. Configuration files publication

Files update

To take in account the modification, we need to import the updated files.

  1. Import the model file {$client}Model.xml in the folder Repository>Data dictionnary>Model.

  2. Import the form file {$client}-form-config.xml in the folder Repository>Data dictionnary>Configurations.

Model refresh and publication

  1. To publish the model, it's possible to:
  2. activate the model by clicking on "Edit the properties" and tick the "Model active" box.

  3. with the designer, select the relevant model in the top left menu. The model and form content is displayed on the left pannel. Click the on the "Publish" button.

  4. Reload the model form the Administration beCPG.

Form refresh and publication

  1. The publication and reload of forms are depending on beCPG version:

  2. Before version 4.0 : in the admin tools, click on reload forms button.

  3. Since version 4.0 : click on More -> Publish, or publish from the designer (as presented in point 3)

Validation handler

A validation handler is a JavaScript function called by the form execution when a field value must be validated. beCPG uses 3 validation handlers defined in the becpg-validation-handler.js:

  • mandatoryIf: displays a field based on the selection of another field
  • hideIf: hides a field depending on the selection of another field
  • filterBy: filters the field based on the selection of the parent field
  • GTIN: validates the field if it's in GTIN format
  • It is also possible to use regular expression in the hideIf conditions

To use these handlers, constraints must be added to the <field> that has the ID of field that must be validated in the form. Don't forget to replace field by assoc or prop in the name of the field.


Example: Display the "acme:fieldId" field if the "field_bcpg_code" field is not empty:

<field id="acme:fieldId">
     <constraint-handlers>
         <constraint type="MANDATORY" validation-handler="beCPG.forms.validation.mandatoryIf" event='keyup,change@[{"prop":"field_bcpg_code", "condition": "NOTEMPTY"}]' />
     </constraint-handlers>
</field>


Example: Hide the field "acme:fieldId" if the field "field_bcpg_code" does not have the value Other:

<field id="acme:fieldId">
     <constraint-handlers>
         <constraint type="MANDATORY" validation-handler="beCPG.forms.validation.hideIf" event='keyup,change@[{"prop":"field_bcpg_code","condition":"RegExp_^(?!Other$).*"}]' />
     </constraint-handlers>
</field>


Example: Hide the "acme:fieldId" field if the "field_bcpg_code" field is empty:

<field id="acme:fieldId">
     <constraint-handlers>
         <constraint type="MANDATORY" validation-handler="beCPG.forms.validation.hideIf" event='keyup,change@[{"prop":"field_bcpg_code","condition":""}]' />
     </constraint-handlers>
</field>


Example: Validate the "acme:fieldId" field if it is in GTIN format

<field id="acme:fieldId">
     <constraint-handlers>
         <constraint type="MANDATORY" validation-handler="beCPG.forms.validation.GTIN" event="keyup" />
     </constraint-handlers>
 </field>


Example: Filter the "acme:fieldId" field to contain only values prefixed with the "field_bcpg_code" field value

<field id="acme:fieldId">
    <constraint-handlers>
        <constraint type="MANDATORY" validation-handler="beCPG.forms.validation.filterBy" event='keyup,change@[{"prop":"field_bcpg_code","condition":"STARTWITH"}]' />
    </constraint-handlers>
</field>

More details at : http://docs.alfresco.com/5.1/concepts/dev-extensions-share-form-field-validation-handlers.html

Data models (designer)

The beCPG models designer allows the creation of data models and forms. It’s accessible from the upper band with the administrator role.

The designer is composed of 3 panels :

  • The left panel displays a tree representative of the model and a tree representative of the forms ;
  • The central panel displays the edition forms for forms and models ;
  • The right panel displays a pallette for grouping and control.

The choice of the file to display the model and the form is done thanks to the drop down menu in the tool bar of the left panel.

The models tree allows the creation of types, aspects, properties and constraints by positionning on the tree and pressing the button « New child ». The choice of the element type to be created is asked and eventually, the choice of the model type too.

Once the model has been created or modified, at the model root, press « Publish ».

Notes :

  • Every mandatory field has to be filled,
  • A type can be deleted if neither of the elements in the repository or in the bin has it ;
  • A property can only be modified by overloading the type or the aspect.

The creation of a form is done by dragging and dropping a type to the forms tree or thanks to the « New child » button. The association between controls and fields or fields grouping is done by drag and drop from the pallet to the area corresponding in the central panel.

In order to publish a form, hover over the forms tree root and press « Publish ».

The overview is done by selecting, in the models tree, a type and by pressing « Overview ». The type should be published. The form with the « Create » identifier associated to the type should be published.

For more information: http://ecmarchitect.com/alfresco-developer-series-tutorials/content/tutorial/tutorial.html

results matching ""

    No results matching ""