Manuel de développement de BlueCourrier¶
Introduction¶
Contexte¶
Ce document détaille l'ensemble des manipulations nécessaires pour la personnalisation de BlueCourrier
Objectif¶
L'objectif de ce document est de présenter les opérations nécessaires à la mise en place des différents composants du projet à partir d'un environnement vierge. Ce document s'adresse aux équipes techniques des clients de BlueCourrier.
Ajout d'une métadonnée¶
L'ajout d'une métadonnée implique les étapes suivantes :
- créer un modèle de données définissant les propriétés qu'on souhaite ajouter ;
- créer un modèle de formulaire venant se superposer au formulaire par défaut afin de présenter les nouvelles métadonnées.
Attention, il n'existe pas actuellement de points d'extension permettant de modifier les colonnes apparaissant à l'affichage de la liste des tâches.
Création d'un modèle de données¶
La création d'un modèle de données dans Alfresco sort du cadre de ce tutoriel. Pour plus d'informations, vous pouvez consulter la documentation Alfresco à ce sujet.
Pour illustrer l'ajout de métadonnées, nous allons créer un modèle de données minimal, contenant :
- le type de courrier ;
- le numéro de recommandé ;
- la date de réponse souhaitée ;
Pour être stockées dans Alfresco, il faut définir certaines informations techniques comme le nom de la métadonnée, son type, son indexation... Les métadonnées sont regroupées dans ce qu'Alfresco appelle un 'aspect'.
Le modèle de données dans notre cas est le suivant :
<?xml version='1.0' encoding='iso-8859-1'?>
<model name="BlueCourrierCustom:model" xmlns="http://www.alfresco.org/model/dictionary/1.0" xmlns:xi="http://www.w3.org/2001/XInclude">
<description>BlueCourrier personalization</description>
<author>Generated by BlueDolmen</author>
<version>1.0</version>
<imports>
<import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d" />
<import uri="http://www.alfresco.org/model/content/1.0" prefix="cm" />
<import uri="http://www.alfresco.org/model/datalist/1.0" prefix="dl" />
</imports>
<namespaces>
<namespace uri="http://www.bluexml.com/model/content/BlueCourrierCustom/1.0" prefix="BlueCourrierCustom" />
</namespaces>
<data-types>
</data-types>
<constraints>
</constraints>
<types>
<type name="BlueCourrierCustom:MailTypes">
<title>Mail Types</title>
<description>Mail types values a mail can have</description>
<parent>dl:dataListItem</parent>
<archive>false</archive>
<properties>
<property name="BlueCourrierCustom:MailTypes_shortLabel">
<type>d:text</type>
<index enabled="true">
<atomic>true</atomic>
<stored>false</stored>
<tokenised>true</tokenised>
</index>
</property>
<property name="BlueCourrierCustom:MailTypes_longLabel">
<type>d:text</type>
<index enabled="true">
<atomic>true</atomic>
<stored>false</stored>
<tokenised>true</tokenised>
</index>
</property>
</properties>
</type>
</types>
<aspects>
<aspect name="BlueCourrierCustom:AspectPerso">
<archive>false</archive>
<properties>
<property name="BlueCourrierCustom:AspectPerso_type">
<type>d:text</type>
<index enabled="true">
<atomic>true</atomic>
<stored>false</stored>
<tokenised>true</tokenised>
</index>
</property>
<property name="BlueCourrierCustom:AspectPerso_specificId">
<type>d:text</type>
<index enabled="true">
<atomic>true</atomic>
<stored>false</stored>
<tokenised>true</tokenised>
</index>
</property>
<property name="BlueCourrierCustom:AspectPerso_responseDate">
<type>d:date</type>
<index enabled="true">
<atomic>true</atomic>
<stored>false</stored>
<tokenised>true</tokenised>
</index>
</property>
</properties>
</aspect>
</aspects>
</model>
Adaptation du formulaire existant¶
En parallèle, nous devons créer un modèle de formulaire pour afficher ces nouveaux champs.
Il existe déjà un formulaire qui affiche les métadonnées disponibles
Création du modèle de formulaire¶
Formulaire de liste de données¶
Le champ MailTypes défini dans le modèle de données est une liste de valeurs, aussi appelée nomenclature ou liste de données dans le vocabulaire Alfresco. Alfresco propose une interface d'administration pour gérer ces listes. Ce sont également des formulaires et il faut donc aussi définir un modèle de formulaire pour afficher le formulaire de création, de mise à jour et de lecture.
Le formulaire de création est défini à l'aide de l'attribute evaluator="model-type" :
<config evaluator="model-type" condition="BlueCourrierCustom:MailTypes">
Le formulaire de mise à jour est défini à l'aide de la balise evaluator="node-type" :
<config evaluator="node-type" condition="BlueCourrierCustom:MailTypes">
Le modèle de formulaire est le suivant :
<?xml version="1.0" encoding="iso-8859-1"?>
<alfresco-config>
<!-- CREATE Mode -->
<config evaluator="model-type" condition="BlueCourrierCustom:MailTypes">
<forms>
<form>
<field-visibility>
<show id="cm:name" force="true" />
<show id="BlueCourrierCustom:MailTypes_shortLabel" force="true" />
<show id="BlueCourrierCustom:MailTypes_longLabel" force="true" />
</field-visibility>
<appearance>
<set id="mailTypes.default" label="Types de courrier" />
<field id="cm:name" set="mailTypes.default" mandatory="true" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl"></control>
</field>
<field id="BlueCourrierCustom:MailTypes_shortLabel" set="mailTypes.default" mandatory="true" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl"></control>
</field>
<field id="BlueCourrierCustom:MailTypes_longLabel" set="mailTypes.default" mandatory="true" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl"></control>
</field>
</appearance>
</form>
</forms>
</config>
<!-- EDIT Mode -->
<config evaluator="node-type" condition="BlueCourrierCustom:MailTypes">
<forms>
<form>
<field-visibility>
<show id="cm:name" force="true" />
<show id="BlueCourrierCustom:MailTypes_shortLabel" force="true" />
<show id="BlueCourrierCustom:MailTypes_longLabel" force="true" />
</field-visibility>
<appearance>
<set id="mailTypes.default" label="Types de courrier" />
<field id="cm:name" set="mailTypes.default" mandatory="true" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl"></control>
</field>
<field id="BlueCourrierCustom:MailTypes_shortLabel" set="mailTypes.default" mandatory="true" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl"></control>
</field>
<field id="BlueCourrierCustom:MailTypes_longLabel" set="mailTypes.default" mandatory="true" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl"></control>
</field>
</appearance>
</form>
</forms>
</config>
</alfresco-config>
Formulaire de courrier¶
Le formulaire suivant va fusionner avec le formulaire par défaut. Si vous souhaitez cacher des champs, il faut ainsi utiliser la balise <hide> à la place de <show>.
Dans l'exemple suivant, le champ object, qui affiche l'objet du mail est ainsi caché. Cette définition surcharge ainsi la définition par défaut qui est d'afficher ce champ.
Il est également possible d'indiquer dans quelle partie du formulaire les champs doivent s'afficher. Le formulaire est structuré autour de regroupements de champs appelé 'set'. L'analyse du formulaire par défaut fourni en annexe nous apprend que les groupes suivants sont définis :
- mail.default
- mail.default.Identification
- mail.default.Dates
- mail.default.Instruction
- mail.default.Classification
- mail.Sender
- mail.Sender.organization
- mail.Sender.instructor
- mail.Sender.signator
- mail.Sender.contactDetails
- mail.Recipient
- mail.Recipient.organization
- mail.Recipient.person
- mail.Recipient.contactDetails
Dans l'exemple ci-dessous, nous indiquons le groupement 'set' dans lequel nous voulons injecter les champs que nous avons définis.
<?xml version="1.0" encoding="iso-8859-1"?>
<alfresco-config>
<config evaluator="node-type" condition="cm:content">
<forms>
<form id="mail">
<edit-form template="/fdk/templates/tab-edit-form.ftl" />
<view-form template="/fdk/templates/tab-edit-form.ftl" />
<field-visibility>
<!--
<hide id="bluecourrier:object" force="true" />
-->
<show id="BlueCourrierCustom:AspectPerso_type" force="true" />
<show id="BlueCourrierCustom:AspectPerso_specificId" force="true" />
<show id="BlueCourrierCustom:AspectPerso_responseDate" force="true" />
</field-visibility>
<appearance>
<field id="BlueCourrierCustom:AspectPerso_specificId" set="mail.default.Identification" label="Id spécifique" mandatory="false" read-only="false">
<control template="/org/alfresco/components/form/controls/textfield.ftl">
</control>
</field>
<field id="BlueCourrierCustom:AspectPerso_responseDate" set="mail.default.Dates" label="Date de réponse souhaitée" mandatory="false" read-only="false">
<control template="/org/alfresco/components/form/controls/date.ftl">
</control>
</field>
<field id="BlueCourrierCustom:AspectPerso_type" set="mail.default.Classification" label="Type de courrier" mandatory="false" read-only="false">
<control template="/org/bluedolmen/components/form/controls/dynamic-dropdown.ftl">
<control-param name="datasourceUrl"><![CDATA[bluedolmen/forms/datalist/bluecourrier/BlueCourrierCustom:MailTypes/items?valueProperty=cm:name]]>
</control-param>
</control>
</field>
</appearance>
</form>
</forms>
</config>
</alfresco-config>
Gestion des accents¶
Remplacement des lettres accentuées par les entités html correspondantes¶
Si les libellés des champs contiennent des accents, ceux-ci doivent être traduits en entités ISO-8859-1 avec leur valeur hexadécimale. L'utilisation des entités html classiques (é) ne fonctionne pas. Ainsi :
- é = é
- à = à
Attention, le ';' fait partie du code à écrire, ce qui donne :
- Date de réponse souhaitée = Date de réponse souhaitée
Je vous invite à consulter la page suivante pour déterminer avec quelles valeurs remplacer les lettres accentuées :
Nous obtenons finalement le modèle suivant :
Internationalisation de votre formulaire¶
Le mécanisme précédent ne rend pas votre extension i18n, c'est à dire utilisable en plusieurs langues. Pour cela, il est nécessaire d'utiliser l'attribut label-id sur les <field> à la place de l'attribut label. Les label-id sont alors des références à des chaines de traduction stockées dans un fichier message caractéristique de la langue de l'utilisateur. Les entités sont alors codées en UTF-8 :
- é = \u00E9
- à = \u00E0
Je vous invite à consulter la page suivante pour déterminer avec quelles valeurs remplacer les lettres accentuées (prendre la valeur hexa et la précéder par \u00)
Ainsi, si vous utilisez les définitions suivantes :
- label-id="BlueCourrierCustom.specificId" en lieu de place de "Id spécifique"
- label-id="BlueCourrierCustom.responseDate" en lieu de place de "Date de réponse souhaitée"
- label-id="BlueCourrierCustom.mailTypes" en lieu de place de "Type de courrier"
il faudra définir un fichier avec le contenu suivant :
-
messages_fr.properties :
BlueCourrierCustom.specificId=Id sp\u00E9cifique BlueCourrierCustom.responseDate=Date de r\u00E9ponse souhait\u00E9e BlueCourrierCustom.mailTypes=Type de courrier
-
messages_en.properties :
BlueCourrierCustom.specificId=Specific Id BlueCourrierCustom.responseDate=Expected Response Date BlueCourrierCustom.mailTypes=Mail Type
Modification du css du formulaire¶
La plupart des éléments peut être modifiée dans la définition du thème. Cependant, certains éléments ne sont pas paramétrés et il faut donc ajouter une règle css.
Afin que les éléments soient pris en compte simplement, vous pouvez modifier le fichier presentation.css du thème choisi.
Réduction de l'espace avant le formulaire¶
Pour réduire cet espace, il faut réaliser les étapes suivantes :
- Depuis le répertoire où est installé Alfresco, éditer le fichier tomcat/webapps/share/themes/lightTheme/presentation.css
- Ajouter en début de fichier les 3 lignes suivantes :
body .sticky-wrapper #template_x002e_formPortlet_x002e_extjseditform {
margin-top: -50px;
}
- Aller sur l'url http://${YOUR_SERVER}/share/service/index
- Cliquer sur le bouton "Clear Dependency Caches" situé en bas de page
- Aller sur un formulaire d'indexation des métadonnées dans BlueCourrier
- L'espace avant le formulaire a disparu
Attention, cette modification ne survivra pas une mise à jour de BlueCourrier qui remplacerait la webapp share.
Pour plus d'information, consulter ce lien.
Déploiement¶
A l'issue des personnalisations que nous avons faites, nous avons les éléments suivants :
- BlueCourrierCustomModel.xml contient votre modèle de données ;
- BlueCourrierCustom-share-forms-config.xml contient la définition de chaque formulaire :
- formulaire d'édition des métadonnées de BlueCourrier (il n'y a pas de formulaire de création car elle est assurée par le système);
- formulaire de création et d'édition des types de mail
Le déploiement peut être fait de différentes manières :
- via le système de fichiers
- via Blue AppStore
Déploiement via le système de fichiers¶
Pour le modèle de données, il faut copier et renommer le fichier BlueCourrierCustomModel.xml dans tomcat/shared/classes/alfresco/extension/customModel.xml.
Pour les formulaires, il faut ajouter les définitions des formulaires définis dans ce tutoriel dans le fichier tomcat/shared/classes/alfresco/web-extension/share-config-custom.xml déjà existant en insérant uniquement les balises <config> et leur contenu bien sûr.
Vous devez maintenant arrêter puis redémarrer Alfresco.
Déploiement via Blue AppStore¶
Le déploiement le plus simple se déroule à travers BlueDolmen AppStore qui utilise les mécanismes de déploiement dynamique d'Alfresco, et les étend, afin de permettre un déploiement simple et aisé.
Pour utiliser Blue AppStore, il faut d'abord procéder à son installation.
Lorsque ce module est installé, vous avez 2 nouveaux répertoires dans le dictionnaire de données à la racine de votre entrepôt :
- Modèles : les modèles de données déposés dans ce répertoire sont déployés automatiquement ;
- Extension de configuration Share : les modèles de formulaires déposés dans ce répertoire sont chargés automatiquement. Attention, les noms des modèles doivent absolument se terminer par share-forms-config.xml
Dans l'exemple traité, une liste de données 'Type de courrier' permet de sélectionner le type du courrier. Cette liste doit être initialisée
Déploiement manuel¶
Dans le cadre de l'exemple que nous avons réalisé, il faut ainsi créer les fichiers suivants :
- BlueCourrierCustomModel.xml à stocker dans Dictionnaire de données/Modèles ;
- BlueCourrierCustom-share-forms-config.xml à stocker dans Dictionnaire de données/Extensions de configuration Share.
Déploiement automatique¶
Le déploiement automatique n'est possible que si les modules ont été déposés sur Blue AppStore.
Si les modules sont disponibles via Blue AppStore :
- Connectez-vous sur http://localhost:8080/share/page/marketplace ;
- Identifiez-vous avec vos login et mot de passe ;
- Installez les modules définissant vos personnalisations :
- Installez BlueCourrierCustom Model
- Installez BlueCourrierCustom UI
Test¶
- Connectez-vous sur http://localhost:8080/share/page/yamma ;
- Double-cliquez sur une tâche dans BlueCourrier : les éléments personnalisés (Id spécifique, date de réponse souhaitée, type de courrier...) doivent appapraître.
Initialisation¶
Afin d'initialiser la liste de données des types de courrier, il faut aller dans l'écran de gestion des listes de données du site Configuration de BlueCourrier, accessible soit depuis Alfresco Share, soit depuis le menu Listes de données de BlueCourrier.
- Cliquez sur Nouvelle liste
- Sélectionnez la liste de données 'MailTypes...'
- Saisissez le titre de cette liste, par exemple, 'Types de courrier de mail'
- Rajoutez les différents types de listes attendues
Annexes¶
Les annexes suivantes sont disponibles :
- bluecourrierModel.xml modèle de données défini par défaut dans BlueCourrier
- share-config-custom.xml : modèle de formulaire défini par défaut dans BlueCourrier