Manuel de développement de BlueAppStore¶

Introduction¶

BlueAppStore est un catalogue de modules prêts à l'emploi permettant l'installation en 1 clic de composants par un administrateur fonctionnel.

Ce document détaille l'ensemble des manipulations nécessaires pour déployer un module sur BlueAppStore. Il prend pour exemple le modèle de données et les modèles de formulaires générés dans le tutoriel sur la personnalisation faite pour BlueCourrier.

Eléments¶

Il est possible d'utiliser un module pour publier n'importe quel contenu dans le repository, aussi bien des éléments de configuration que des documents, des arborescences :

Eléments de configuration¶

Les éléments de configuration peuvent être :

modèle de données
formulaire
définitions de processus
règles de contenu
code javascript

Contenu¶

Le contenu peut être :

un fichier de n'importe quel type (texte, pdf, vidéo...)
un modèle de fichier Office, LibreOffice ou OpenOffice
une arborescence
un modèle d'arboresce
des éléments de configuration d'un module que vous avez écrit

Stratégie de packaging¶

D'expérience, certains modules évoluent plus souvent que d'autres. Par exemple, un modèle de données est généralement assez stable, ainsi qu'un processus alors qu'un modèle de formulaire évolue souvent pour refléter des évolutions esthétiques et ergonomiques. En outre, certains modules sont plus sensibles que d'autres : les modèles de données évoluent ainsi principalement par ajout, les mécanismes d'intégrité empêchant la modification du modèle de données si cela a un impact sur les données stockées.

Ainsi, nous créerons :

un module pour le modèle de données
un module pour les formulaires

Dans le cas où nous aurions des processus, nous aurions également créé : * un module pour chaque processus

Il est également possible de créer des modules avec n'importe quel contenu et pas seulement des éléments de configuration. On peut ainsi

Packaging¶

Un module pour BlueAppStore est un fichier JAR respectant la structure suivante :

racine du module
- META-INF
  - MANIFEST.MF
  - file-mappings.properties : fichier décrivant à quelle répertoire de destination les répertoires locaux correspondent
  - module.yml : fichier décrivant le module
  - logo.png : logo du module. Idéalement, sa taille est de 128x128
- space-templates : répertoire local
- init-doclib : répertoire local
- scripts : répertoire local

Le contenu de file-mappings.properties est le suivant :

    space-templates=/app:dictionary/app:space_templates
    init-doclib=/st:sites/cm:app-subvention/cm:documentLibrary
    scripts=/app:dictionary/app:scripts

Ces informations indiquent que les fichiers contenus dans les répertoires locaux space-templates, init-doclib et script, situés au même niveau que META-INF, seront copiés respectivement dans les répertoire /app:dictionary/app:space_templates, /st:sites/cm:app-subvention/cm:documentLibrary et /app:dictionary/app:scripts de l'entrepôt Alfresco de destination. Notez que le répertoire init-doclib implique que le site app-subvention doit exister sinon les fichiers contenus dans ce répertoire ne pourront être copiés et l'installation du module échouera.

Script ant¶

Deux scripts ant sont disponibles pour vous aider à packager et publier vos modules sur BlueAppStore :

META-INF/build.xml : ce script, stocké dans le répertoire META-INF de votre module, est chargé de construire votre module
./build-commond.xml : ce script, stocké à la racine de vos projets, contient les fonctions de bas niveau pour gérer les numéros de version, le packaging et la publication de votre module sur BlueAppStore.

Prérequis¶

Il faut installer Ant. Pour cela, téléchargez et installez la dernière version sur votre poste sans oublier de mettre à jour la variable d'environnement PATH de votre système :

apache-ant-1.9.6

Vous devez ainsi pouvoir exécuter la commande suivante sans erreur :

    ant -version

Le système doit vous répondre quelque chose comme ci-dessous :

    Apache Ant(TM) version 1.9.6 compiled on June 29 2015

Structure des projets Ant pour BlueAppStore¶

Afin de faciliter la génération des modules, les scripts Ant fournis ajoutent quelques fichiers supplémentaires :

racine du module BlueAppStore
- META-INF
  - build.number : numéro de version du module, généré automatiquement par le système
  - build.properties : propriétés du module (nom, groupId, moduleId)
  - module.yml.tpl : fichier décrivant le module (description, tags...). Ce fichier sert de modèle pour générer le fichier module.yml qui sera finalement packagé

Se trouve également dans le répertoire META-INF le fichier build.xml décrit ci-dessus.

Vous avez finalement l'aborescence suivante :

BlueAppStore addons :
- src/addons/com/bluedolmen/training/mymodule :
  - META-INF :
    - MANIFEST.MF
    - build.number
    - build.properties
    - file-mappings.properties
    - logo.png
    - module.yml
    - module.yml.tpl
  - models
  - forms
  - rules
  - scripts
- build-common.xml

avec :

file-mappings :

forms=/app:dictionary/app:share_configs
models=/app:dictionary/app:model
space-templates=/app:dictionary/app:space_templates
scripts=/app:dictionary/app:scripts
init-doclib=/st:sites/cm:app-subvention/cm:documentLibrary

build.properties :

#addon.name=Subvention - Business Code
addon.name=<Nom de votre module>

#addon.groupId=fr.franche-comte.domain.investment.subvention
addon.groupId=<Nom technique de votre module en dns inversé>

#addon.moduleId=bizcode
addon.moduleId=<Nom du module dans le groupId>

modul.yml.tpl :

name         : @addon.name@
groupId      : @addon.groupId@
moduleId     : @addon.moduleId@

version      : 1.2
packaging    : alfrescomodel

description  : >
  Ce module décrit les données liées à la gestion des fiches
  marchés publics dans les collectivités. Les données sont stockées dans
  un répertoire dont le path est calculé à partir de règles de nommage.
  D'autres règles de nommage permettent également de déterminer le nom du
  document à partir de valeurs des méta-données.

license      : license.md

author       :
  username   : @addon.username@
  contact    : @addon.email@

cost         : EUR 0

category     : /Collectivites/Marches Publics/Data

tags         :
  - tag1
  - tag2
  - tag3

Les seuls éléments que vous pouvez modifier dans ce fichier sont :

description
tags

Génération du module¶

Pour construire le module, il suffit de lancer la target 'package' dans le répertoire META-INF du module. Dans notre exemple de module :

    cd <BASE> où BASE est le répertoire contenant votre projet
    cd src/addons/com/bluedolmen/training/mymodule/META-INF
    ant package

Vous obtenez alors le résultat suivant :

Publication sur BlueAppStore¶

Pour publier le module, il faut d'abord renseigner les login et mot de passe pour se connecter sur BlueAppStore. Ces informations doivent être stockés dans votre répertoire utilisateur dans un fichier .build-bdas.properties avec le contenu suivant :

.build-bdas.properties

# Dans notre exemple, la variable base correspond au répertoire racine de votre projet:
#
base=<chemin absolu du répertoire de votre projet>
bdas.user=<votre nom d'utilisateur>
bdas.passwd=<votre mot de passe>

Pour publier le module, il suffit de lancer la target 'publish' :

    cd <BASE> où BASE est le répertoire contenant votre projet
    cd src/addons/com/bluedolmen/training/mymodule/META-INF
    ant publish

Vous obtenez alors le résultat suivant :

Génération et publication simultanées¶

Une fois rodées, les 2 commandes précédentes peuvent être appelées directement :

    cd <BASE> où BASE est le répertoire contenant votre projet
    cd src/addons/com/bluedolmen/training/mymodule/META-INF
    ant packageAndPublish

Interface web BlueAppStore¶

BlueAppStore propose une application de création de modules. Elle peut aussi être utilisée pour packager des fichiers déjà existants sur votre ordinateur.

Exemple¶

Afin d'illustrer

Les éléments ont été définis précédemment dans le tutoriel de personnalisation de BlueCourrier. Vous avez donc en votre possession les éléments suivants : * Modèle de données : * Formulaire : -