Tutoriel composant example
Contents |
Tutoriel développeur basé sur le composant example de framework
Contexte
Ce tutoriel a pour but la modification de l'entité Exemple et l'ajout de nouvelles fonctionnalités. Il présente dans une première partie les modifications du diagramme UML (classe et activité). Une seconde partie présente la création d'une page qui permet l'appel à des services de création et de modification en mini-langage. La troisième partie permet l'affichage en liste des éléments de l'entité Example, afin de visualiser les paramètres d'un élément lors de sa recherche et pour simplifier sa modification. La dernière partie explique l'utilisation des decorators ainsi que des fichier .ftl qui permettent de créer des entêtes.
Diagramme UML des entités du composant
Le diagramme de classe suivant représente la classe du projet avant l'ajout d'une entité Example2
Nous souhaitons en fin de modifications que le projet respecte ce diagramme.
Voici le diagramme d'activité representant la modification ou la création d'un nouvel élément ainsi que l'affichage de la table Example2 après succés des opérations.
Ce diagramme represente la recherche d'un élément à l'aide du service PerformFind.
Ajout de example dans le projet
Dans un premier temps nous modifions le fichier applications/component-load.xml en ajoutant la ligne:
<load-component component-location="${ofbiz.home}/framework/example"/>
nous pouvons ainsi inclure le dossier /framework/example pour le compiler et l'exécuter.
Provisoirement il nous faut commenter le decorator screen dans framework/example/widget/example/CommonScreens.xml tant que nous n'avons pas encore mis les decorators à nos views
<screen name="main">
<section>
<widgets>
<!-- <decorator-screen name="main-decorator">
<decorator-section name="body"> -->
<container style="screenlet">
<container style="screenlet-header">
<label style="boxhead" text="Example Main Page" />
</container>
<container style="screenlet-body">
<section>
<condition>
<if-empty field-name="userLogin" />
</condition>
<widgets>
<container>
<label text="${uiLabelMap.ExampleMessage}" />
</container>
</widgets>
</section>
<container>
<label text="${uiLabelMap.ExampleWelcome}" />
</container>
</container>
</container>
<!-- </decorator-section>
</decorator-screen>-->
</widgets>
</section>
</screen>
Réalisation d'un écran example
- une entité example2 : avec 3 champs
Nous créons une nouvelle entité qui se nommera Example2 en ajoutant une ligne dans framework/example/entitydef/entitygroup.xml
<entity-group group="org.ofbiz" entity="Example2"/>
Puis il nous faut définir les champs de l'entité Example2, pour cela nous ajoutons dans framework/example/entitydef/entitymodel.xml une balise field pour chaque nouveau champ. Notre table Exemple2 possédera donc le champ exampleId (identifiant d'un élément), exampleTypeId qui nous donne le type d'un élément) et statusId (qui corespond au statut d'un élément).
<entity entity-name="Example2" package-name="org.ofbiz.example.example" title="Example Entity2">
<field name="exampleId" type="id-ne"></field>
<field name="exampleTypeId" type="id-ne"></field>
<field name="statusId" type="id-ne"></field>
<prim-key field="exampleId"/>
</entity>
- un screen (sans decorator)
Il nous faut pouvoir insérer ou modifier des données pour cela nous créons un screen qui ne contiendra pas de decorator.
Dans framework/example/widget/example/ExampleScreens.xml nous ajoutons un screen
<screen name="EditExample2"> <section> <widgets> <include-form name="EditExample2" location="component://example/widget/example/ExampleForms.xml" /> </widgets> </section> </screen>
- une form single
Le screen précédent fera appel à une forme définie dans framework/example/widget/example/ExampleForms.xml. Cette forme affiche automatiquement tous les champs de la table Example2.
<form name="EditExample2" type="single" target="createExample2" title="" default-map-name="example">
<auto-fields-entity entity-name="Example2"/>
<field name="submitButton" title="Submit"><submit button-type="button"/></field>
</form>
- une entrée dans le controller
Dans framework/example/webapp/example/WEB-INF/controller.xml nous ajoutons l'uri qui correspondra à la view-map affichée. La page affichée possédera une adresse se terminant par EditExample2.
<request-map uri="EditExample2"><security https="true"/><response name="success" type="view" value="EditExample2"/></request-map>
puis dans ce même fichier nous créons une view-map
<view-map name="EditExample2" type="screen" page="component://example/widget/example/ExampleScreens.xml#EditExample2"/>
- 2 services réalisés en mini-language
Nous ajoutons 2 services, le service createExample2 et le service updateExample2 définis dans le fichier framework/example/servicedef/services.xml. createExample2 va créer une nouvelle entrée dans la table Example2 avec un identifiant donné automatiquement et les autres paramètres saisis par l'utilisateur. updateExample2 modifie les champs de l'élément dont l'utilisateur aura fourni son identifiant en entrée.
<service name="createExample2" default-entity-name="Example2" engine="simple" location="org/ofbiz/example/example/ExampleServices.xml" invoke="createExample2"> <description>Create a Example2</description> <attribute name="exampleTypeId" mode="IN" type="String" /> <attributes name="statusId" mode="IN" type="String" /> </service>
<service name="updateExample2" default-entity-name="Example2" engine="simple" location="org/ofbiz/example/example/ExampleServices.xml" invoke="updateExample2"> <description>Update a Example2</description> <auto-attributes mode="IN" entity-name="Example2" optional="true" /> </service>
Les 2 services précédents sont en mini langage et leur corps se trouve dans framework/example/script/org/ofbiz/example/example/ExampleServices.xml
<simple-method method-name="createExample2" short-description="create a Example2"> <make-value entity-name="Example2" value-name="newEntity" /> <sequenced-id-to-env sequence-name="Example2" env-name="newEntity.exampleId" /> <set-nonpk-fields map-name="parameters" value-name="newEntity" /> <create-value value-name="newEntity" /> </simple-method>
<simple-method method-name="updateExample2" short-description="update a Example2"> <entity-one entity-name="Example2" value-name="lookedUpValue" /> <set-nonpk-fields value-name="lookedUpValue" map-name="parameters" /> <store-value value-name="lookedUpValue" /> </simple-method>
Dans framework/example/webapp/example/WEB-INF/controller.xml nous ajoutons les uri qui correpondent aux services.
<request-map uri="createExample2"><security https="true"/>
<event type="service" path="" invoke="createExample2"/>
<response name="success" type="view" value="ListExample2"/>
<response name="error" type="view" value="EditExample2"/>
</request-map>
<request-map uri="updateExample2">
<security https="true" auth="true"/>
<event type="service" path="" invoke="updateExample2"/>
<response name="success" type="view" value="ListExample2"/>
<response name="error" type="view" value="EditExample2"/>
</request-map>
Voici un aperçu de la view pour createExample2
complément sur les form
- réalisation de la form de recherche
Pour effectuer une recherche dans la table Example2 nous devons créer 2 forms. La première form "LookExample2" nous permet de saisir un identifiant et de lancer la recherche par le bouton "Recherche". La deuxième form "FindExample2" affiche le résultat s'il est existant sous forme de liste. Chaque élément est affiché avec un bouton "edit" à son coté. L'appui sur le bouton edit renvoie sur la page "createExample2" avec les champs existant de cet élément près remplis. Ceci permet la modification d'un des attributs de l'élément.
Ces formes sont ajoutées dans framework/example/widget/example/ExampleForms.xml:
<form name="LookExample2" type="single" target="FindExample2" default-map-name="Example2" focus-field-name="exampleId">
<auto-fields-service service-name="createExample2" />
<field name="submitButton" title="Recherche">
<submit button-type="button" />
</field>
<field name="cancelLink" title="" widget-style="smallSubmit">
<hyperlink target="${donePage}?partyId=${partyId}" also-hidden="false" description="${uiLabelMap.CommonCancelDone}" />
</field>
</form>
<form name="FindExample2" type="list" list-name="listIt" target="EditExample2"> <actions> <service service-name="performFind" result-map-name="result" result-map-list-name="listIt"> <field-map field-name="inputFields" env-name="parameters" /> <field-map field-name="entityName" value="Example2" /> </service> </actions> <auto-fields-service service-name="updateExample2" default-field-type="display" /> <field name="submitButton" title="edit"> <submit button-type="button" /> </field> </form>
Il nous faut par la suite ajouter les entrées dans le controleur example/webapp/example/WEB-INF/controller.xml
<request-map uri="LookExample2"> <security https="true" /> <response name="success" type="view" value="LookExample2" /> </request-map>
<request-map uri="FindExample2"><security https="true"/> <response name="success" type="view" value="FindExample2"/> </request-map>
ainsi qu'une view-map pour chaque screen
<view-map name="LookExample2" type="screen" page="component://example/widget/example/ExampleScreens.xml#LookExample2"> </view-map>
<view-map name="FindExample2" type="screen" page="component://example/widget/example/ExampleScreens.xml#FindExample2"></view-map>
- réalisation du screen de recherche - list
Dans framework/example/widget/example/ExampleScreens.xml nous ajoutons les 2 screens qui utiliseront les forms réalisées précédemment:
<screen name="LookExample2">
<section>
<widgets>
<!--
<decorator-screen name="main-decorator" location="component://example/widget/example/CommonScreens.xml">
<decorator-section name="body">
-->
<include-form name="LookExample2" location="component://example/widget/example/ExampleForms.xml" />
<!--
</decorator-section>
</decorator-screen>
-->
</widgets>
</section>
</screen>
<screen name="FindExample2"> <section> <widgets> <!-- <decorator-screen name="main-decorator" location="component://example/widget/example/CommonScreens.xml"> <decorator-section name="body"> --> <include-form name="FindExample2" location="component://example/widget/example/ExampleForms.xml" /> <!-- </decorator-section> </decorator-screen> --> </widgets> </section> </screen>
- réalisation de la form de list
La form ListExample2 nous permet d'afficher tous les éléments de la table Example2 en liste après création ou modification d'un élément. Pour cela nous ajoutons dans framework/example/widget/example/ExampleForms.xml
<form name="ListExample2" type="list" list-name="ListExample2" target="EditExample2"> <actions> <entity-condition entity-name="Example2" list-name="ListExample2"> <condition-expr field-name="exampleId" operator="not-equals" value="" /> </entity-condition> </actions> <auto-fields-service service-name="createExample2" default-field-type="display" /> <field name="submitButton" title="edit"> <submit button-type="button" /> </field> </form>
dans example/webapp/example/WEB-INF/controller.xml
<request-map uri="ListExample2"> <security https="true" auth="true" /> <response name="success" type="view" value="ListExample2" /> </request-map>
<view-map name="ListExample2" type="screen" page="component://example/widget/example/ExampleScreens.xml#ListExample2" />
et nous ajoutons dans framework/example/widget/example/ExampleScreens.xml
<screen name="ListExample2"> <section> <widgets> <decorator-screen name="main-decorator" location="component://example/widget/example/Example2Screens.xml"> <decorator-section name="body"> <include-form name="ListExample2" location="component://example/widget/example/ExampleForms.xml" /> </decorator-section> </decorator-screen> </widgets> </section> </screen>
- ajout d'une association avec la table status
Nous allons ajouter 2 associations. La première association sera entre Example2 et ExampleType et la seconde entre Example2 et StatusItem. Ces 2 relations unitaires (relation type="one") ont respectivement pour nom "ExampleType" et "StatusItem" et pour clé "exampleTypeId" et "statusId". dans framework/example/entitydef/entitymodel.xml
<entity entity-name="Example2" package-name="org.ofbiz.example.example" title="Example Entity2">
<field name="exampleId" type="id-ne"></field>
<field name="exampleTypeId" type="id-ne"></field>
<field name="statusId" type="id-ne"></field>
<prim-key field="exampleId"/>
<relation type="one" fk-name="EXMPL_TYP" rel-entity-name="ExampleType">
<key-map field-name="exampleTypeId"/>
</relation>
<relation type="one" fk-name="EXMPL_STTS" rel-entity-name="StatusItem">
<key-map field-name="statusId"/>
</relation>
</entity>
- ajout d'un drop down dans le form edit et find
Afin de faire apparaître une liste déroulante nous ajoutons un nouveau champ contenant un drop down dans LookExample2 et dans EditExample2.
<form name="LookExample2" type="single" target="FindExample2" default-map-name="Example2" focus-field-name="exampleId">
<auto-fields-service service-name="createExample2" />
<field name="exampleId" tooltip="${uiLabelMap.CommonRequired}" widget-style="required">
</field>
<field name="statusId" title="${uiLabelMap.CommonStatus}">
<drop-down allow-empty="true">
<entity-options entity-name="StatusItem" description="${description}">
<entity-order-by field-name="sequenceId" />
</entity-options>
</drop-down>
</field>
<field name="submitButton" title="Recherche">
<submit button-type="button" />
</field>
<field name="cancelLink" title="" widget-style="smallSubmit">
<hyperlink target="${donePage}?partyId=${partyId}" also-hidden="false" description="${uiLabelMap.CommonCancelDone}" />
</field>
</form>
Aperçu de la view pour une recherche dans la table Example2.
- ajout du display entity
<form name="EditExample2" type="single" target="updateExample2" title="">
<alt-target use-when="exampleId==null" target="createExample2" />
<auto-fields-entity entity-name="Example2" />
<field name="exampleItemSeqId">
<display-entity entity-name="ExampleItem" description="${description}">
</display-entity>
</field>
<field name="statusId" title="${uiLabelMap.CommonStatus}">
<drop-down allow-empty="true">
<entity-options entity-name="StatusItem" description="${description}">
<entity-order-by field-name="sequenceId" />
</entity-options>
</drop-down>
</field>
<field name="submitButton" title="Submit">
<submit button-type="button" />
</field>
</form>
- ajout d'une association avec une entité avec 2 primaryKeys
<entity entity-name="Example2" package-name="org.ofbiz.example.example" title="Example Entity2">
<field name="exampleId" type="id-ne"></field>
<field name="exampleItemSeqId" type="id-ne"></field>
<field name="statusId" type="id-ne"></field>
<prim-key field="exampleId"/>
<relation type="one" fk-name="EXMPL_STTS" rel-entity-name="StatusItem">
<key-map field-name="statusId"/>
</relation>
<relation type="one" fk-name="EXMPL_ITEM" rel-entity-name="ExampleItem">
<key-map field-name="exampleId,exampleItemSeqId"/>
</relation>
</entity>
- ajout d'un row-actions au niveau de la liste pour pouvoir faire une display de la description
<form name="ListExample2" type="list" list-name="ListExample2" target="EditExample2"> <actions> <entity-condition entity-name="Example2" list-name="ListExample2"> <condition-expr field-name="exampleId" operator="not-equals" value="" /> </entity-condition> </actions> <row-actions> <set field="statusId" value="statusId" /> </row-actions> <auto-fields-service service-name="updateExample2" default-field-type="display" /> <field name="submitButton" title="edit"> <submit button-type="button" /> </field> </form>
les decorators
- decorator avec ftl d'entête
- faire un petit ftl d'entête: juste des libéllé fixe et l'affichage de 2 variables
On a créé un fichier /framework/example/webapp/example/includes/header.ftl.
<h2>${uiLabelMap.Welcome}</h2>
<h2>${uiLabelMap.ExampleApplication}</h2>
Pour internationaliser l'affichage, on a ajouté des textes dans les fichiers de propriété. Par exemple, dans le fichier par défaut /framework/example/config/ExampleUiLabels.properties, les champs sont définis comme ci-dessous:
ExampleApplication=Example Application Welcome=Welcome
- faire un screen l'affichant
On a créé un fichier /framework/example/widget/example/Example2Screens.xml
<?xml version="1.0" encoding="UTF-8"?> <screens xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.ofbiz.org/dtds/widget-screen.xsd"> <screen name="main"> <section> <actions> <property-map resource="ExampleUiLabels" map-name="uiLabelMap" global="true"/> </actions> <widgets> <platform-specific> <html> <html-template location="component://example/webapp/example/includes/header.ftl"/> </html> </platform-specific> </widgets> </section> </screen> </screens>
- faire un screen de type decorator
Dans le fichier /framework/example/widget/example/Example2Screens.xml, on a ajouté un decorator.
<screen name="main-decorator">
<section>
<actions>
<property-map resource="ExampleUiLabels" map-name="uiLabelMap" global="true"/>
<set field="layoutSettings.styleSheets[+0]" value="/images/maincss.css" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/calendar1.js" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/selectall.js" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/fieldlookup.js" global="true"/>
<set field="layoutSettings.shortcutIcon" value="/images/ofbiz.ico" global="true"/>
<set field="parameters.uiLabelComponentName" value="example"/>
</actions>
<widgets>
<platform-specific><html><html-template location="component://common/webcommon/includes/header.ftl"/></html></platform-specific>
<platform-specific>
<html><html-template location="component://example/webapp/example/includes/header.ftl"/></html>
</platform-specific>
</widgets>
</section>
</screen>
- modifier les screens précédents pour utiliser ce decorator
Dans le fichier /framework/example/widget/example/Example2Screens.xml,le screen <<main>> devient:
<screen name="main"> <section> <widgets> <decorator-screen name="main-decorator"> <decorator-section name="body"> </decorator-section> </decorator-screen> </widgets> </section> </screen>
- decorator dans 1 decorator
- ajout du menu dans un decorator
On a modifié le fichier /framework/example/webapp/example/includes/appheader.ftl comme ci-dessous:
<#assign selected = headerItem?default("void")>
<div id="app-navigation">
<h2>${uiLabelMap.ExampleApplication}</h2>
<ul>
<li<#if selected = "List"> class="selected"</#if>>
<a href="<@ofbizUrl>ListExample2</@ofbizUrl>">${uiLabelMap.List}</a>
</li>
<li<#if selected = "Create"> class="selected"</#if>>
<a href="<@ofbizUrl>CreateExample2</@ofbizUrl>">${uiLabelMap.Create}</a>
</li>
<li<#if selected = "Edit"> class="selected"</#if>>
<a href="<@ofbizUrl>LookExample2</@ofbizUrl>">${uiLabelMap.Find}</a>
</li>
<#if userLogin?has_content>
<li class="opposed"><a href="<@ofbizUrl>logout</@ofbizUrl>">${uiLabelMap.CommonLogout}</a></li>
<#else>
<li class="opposed"><a href="<@ofbizUrl>${checkLoginUrl?if_exists}</@ofbizUrl>">${uiLabelMap.CommonLogin}</a></li>
</#if>
</ul>
<br class="clear" />
</div>
Après, il faut ajouter les champs correspondants dans le fichier /framework/example/config/ExampleUiLabels.properties.
ExampleCreate=Create ExampleFind=Find ExampleList=List
En suite, on a ajouté un nouveau decorator dans le fichier /framework/example/widget/example/Example2Screens.xml en utilisant le fichier ftl.
<screen name="menu">
<section>
<widgets>
<container style="centerarea">
<platform-specific>
<html><html-template location="component://example/webapp/example/includes/appheader.ftl"/></html>
</platform-specific>
</container>
</widgets>
</section>
</screen>
- ajout dans ce decorator de l'appel au decorator précédent
Le decorator est ajouté via la balise <<include-screen>>.
<screen name="main-decorator">
<section>
<actions>
<property-map resource="ExampleUiLabels" map-name="uiLabelMap" global="true"/>
<set field="layoutSettings.styleSheets[+0]" value="/images/maincss.css" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/calendar1.js" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/selectall.js" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/fieldlookup.js" global="true"/>
<set field="layoutSettings.shortcutIcon" value="/images/ofbiz.ico" global="true"/>
<set field="parameters.uiLabelComponentName" value="example"/>
</actions>
<widgets>
<platform-specific><html><html-template location="component://common/webcommon/includes/header.ftl"/></html></platform-specific>
<platform-specific>
<html><html-template location="component://example/webapp/example/includes/header.ftl"/></html>
</platform-specific>
<include-screen name="menu"/>
</widgets>
</section>
</screen>
- affichage des screens précédent
Pour activer le nouveau screen, il faut changer le lien d'entrée dans le fichier /framework/example/webapp/example/WEB-INF/controller.xml.
<view-map name="main" type="screen" page="component://example/widget/example/Example2Screens.xml#main"/>
Et puis, pareil pour les decorators dans le fichier /framework/example/widget/example/ExampleScreens.xml.
<screen name="EditExample2">
<section>
<actions>
<set field="examleId" from-field="parameters.exampleId"/>
</actions>
<widgets>
<decorator-screen name="main-decorator" location="component://example/widget/example/Example2Screens.xml">
<decorator-section name="body">
<include-form name="EditExample2" location="component://example/widget/example/ExampleForms.xml"/>
</decorator-section>
</decorator-screen>
</widgets>
</section>
</screen>
<screen name="ListExample2"> <section> <widgets> <decorator-screen name="main-decorator" location="component://example/widget/example/Example2Screens.xml"> <decorator-section name="body"> <include-form name="ListExample2" location="component://example/widget/example/ExampleForms.xml" /> </decorator-section> </decorator-screen> </widgets> </section> </screen>
<screen name="LookExample2">
<section>
<widgets>
<decorator-screen name="main-decorator" location="component://example/widget/example/Example2Screens.xml">
<decorator-section name="body">
<include-form name="LookExample2" location="component://example/widget/example/ExampleForms.xml"/>
</decorator-section>
</decorator-screen>
</widgets>
</section>
</screen>
<screen name="FindExample2">
<section>
<widgets>
<decorator-screen name="main-decorator" location="component://example/widget/example/Example2Screens.xml">
<decorator-section name="body">
<include-form name="FindExample2" location="component://example/widget/example/ExampleForms.xml"/>
</decorator-section>
</decorator-screen>
</widgets>
</section>
</screen>
- decorator avec 2 include : les search et le list
On a l'entête de la page. Maintenant, il faut ajouter le corps dans le <<main-decorator>> du fichier/framework/example/widget/example/Example2Screens.xml.
<screen name="main-decorator">
<section>
<actions>
<property-map resource="ExampleUiLabels" map-name="uiLabelMap" global="true"/>
<set field="layoutSettings.styleSheets[+0]" value="/images/maincss.css" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/calendar1.js" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/selectall.js" global="true"/>
<set field="layoutSettings.javaScripts[]" value="/images/fieldlookup.js" global="true"/>
<set field="layoutSettings.shortcutIcon" value="/images/ofbiz.ico" global="true"/>
<set field="parameters.uiLabelComponentName" value="example"/>
</actions>
<widgets>
<platform-specific><html><html-template location="component://common/webcommon/includes/header.ftl"/></html></platform-specific>
<platform-specific>
<html><html-template location="component://example/webapp/example/includes/header.ftl"/></html>
</platform-specific>
<include-screen name="menu"/>
<container id="content-main-section" style="${MainColumnStyle}">
<platform-specific><html><html-template location="component://common/webcommon/includes/messages.ftl"/></html></platform-specific>
<decorator-section-include name="body"/>
</container>
</widgets>
</section>
</screen>
Avant, nous avions enlevé le paramètre <<auth>> dans le <<request-map>> dans le fichier /framework/example/webapp/example/WEB-INF/controller.xml. Avec le decorator, nous pouvons desormais le remettre pour activer la securité.
<request-map uri="EditExample2">
<security https="true" auth="true"/>
<response name="success" type="view" value="EditExample2"/>
</request-map>
<request-map uri="CreateExample2">
<security https="true" auth="true"/>
<response name="success" type="view" value="EditExample2"/>
</request-map>
<request-map uri="createExample2">
<security https="true" auth="true"/>
<event type="service" path="" invoke="createExample2"/>
<response name="success" type="view" value="ListExample2"/>
</request-map>
<request-map uri="ListExample2">
<security https="true" auth="true"/>
<response name="success" type="view" value="ListExample2"/>
</request-map>
<request-map uri="LookExample2">
<security https="true" auth="true"/>
<response name="success" type="view" value="LookExample2"/>
</request-map>
<request-map uri="FindExample2">
<security https="true" auth="true"/>
<response name="success" type="view" value="FindExample2"/>
</request-map>
objet : Tutoriel basé sur le composant example du framework OFBiz/Néogia langue de la page de référence : Français auteurs : multiples (Wenlong, Jing, Julien)
