Créer un package AMP pour Alfresco

Dans mon tutoriel sur les scripts Ant, j’avais évoqué les packages AMP (Alfresco Module Package). Ils sont utilisés pour ajouter des sets de fonctionnalités supplémentaires ou des fichiers pour personnaliser l’outil (images, icônes, modèles de données, scripts, etc.). Voyons comment transformer un projet en package AMP.

1. Le package AMP

Un package AMP est un dossier compressé qui possède une structure bien précise :

structure package amp

/config correspond à /WEB-INF/classe. Il contient les fichiers de configuration de vos extensions (web-client-config, modeles, -context.xml, resources.properties, etc.)

/lib correspond à /WEB-INF/lib et contient tous les fichiers .jar dont vous avez besoin.

/licences contient les éventuels fichiers de licence liés à des librairies externes que vous pourriez utiliser.

/web est mappé à la racine de la webapp Alfresco, soit /tomcat/webapps/alfresco/. Les noms des dossiers qu’il contient parlent d’eux-même. Mais vous pouvez en ajoutez d’autres selon vos besoins. La structure du package n’est pas figée.

Le fichier module.properties contient des informations sur votre module comme son nom, son id, une description et éventuellement des contraintes sur la version d’Alfresco à laquelle il peut s’appliquer. Nous y reviendrons plus tard.

Le fichier file-mapping.properties est optionnel et vous permet de modifier le mapping des dossiers de votre package AMP par rapport à la webapp Alfresco. Si vous n’utilisez pas ce fichier, le mapping par défaut (décrit précédemment) est utilisé.

2. Le projet Eclipse

Maintenant, voyons comment créer et structurer votre projet sous Eclipse.  La structure est un peu différente du package amp mais un script Ant permettra de facilement remodeler le projet pour générer un package conforme en sortie.

alfresco amp projet

Le dossier source contient les classes java. Le dossier build sera utilisé par le script Ant pour compiler les classes et générer le jar. Nous retrouvons les dossiers lib, web et config. Le dossier WEB-INF peut contenir votre fichier web.xml si vous le modifiez ou bien le fichier faces-config-custom.xml. Nous retrouvons également file-mapping.properties et module.properties. Enfin il y a le script Ant project-build.xml et son fichier de propriétés.

a. le fichier module.properties

# my module properties
module.id=myGreatModule
module.aliases=my-great-module, module-1
module.version=1.0
module.title=My Uber module for Alfresco
module.description=This module add great new features to the alfresco web client

module.repo.version.min=2.0
module.repo.version.max=2.1

module.depends.alfresco.custom.module.myFirstModule=1.0-*
module.depends.alfresco.custom.module.mySecondModule=*

Les propriétés marquée en bleu sont obligatoire ! Les deux lignes qui suivent la description du module permettent de spécifier la version d’Alfresco à laquelle peut s’appliquer votre module. Elles sont optionnelles. Les deux lignes suivantes indiquent que votre module ne peut être installé que si les deux modules cités sont déjà installés et avec une contrainte sur leur version. Concrètement, doivent être installés au préalable myFirstModule 1.0 minimum et mySecondModule toute version acceptée…

b. le fichier module-context.xml

L’autre fichier important pour créer notre package amp est le fichier module-context.xml. Ce fichier est un fichier de configuration Spring standard et va permettre de charger les différents fichiers xml de vos extensions au démarrage d’alfresco. Il se trouve dans le dossier /config/alfresco/module/<module.id>/

dossier config projet package amp alfresco

Et sont contenu peut être comme ceci:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>
     <import resource="context/bootstrap-context.xml" />
     <import resource="context/custom-models-context.xml" />
     <import resource="context/custom-actions-context.xml" />
     <import resource="context/web-ui-config-context.xml" />
     <import resource="context/resources-bundle-context.xml" />
</beans>

Bien sûr, vous pouvez tout aussi bien déclarer vos beans directement dans le fichier module-context.xml. Personnellement, je n’hésite pas à multiplier les niveaux dans mon arborescence pour que tout soit bien structuré.

c. le script Ant

Maintenant que votre projet est bien structuré et que vous disposez de tous les fichiers nécessaire à la création du package amp, vous pouvez vous attaquer au script Ant ! Voici un exemple de script :

<?xml version="1.0"?>

<project name="Alfresco extensions sample" default="package-amp" basedir=".">

	<property name="project.dir" value="."/>
	<property file="${project.dir}/project-build.properties"/>
	<property file="${project.dir}/module.properties"/>
	<property name="project.name" value="org.alfresco.custom.extensions"/>

	<property name="build.dir" value="${project.dir}/build"/>
	<property name="config.dir" value="${project.dir}/config"/>
	<property name="jar.file" value="${build.dir}/lib/${project.name}.jar"/>
	<property name="amp.file" value="${build.dir}/dist/${module.id}.amp"/>

    <target name="mkdirs">
        <mkdir dir="${build.dir}/dist" />
        <mkdir dir="${build.dir}/lib" />
    	<mkdir dir="${build.dir}/classes" />
    </target>

    <path id="class.path">
        <dirset dir="${build.dir}" />
    	<fileset dir="${project.dir}/lib" includes="**/*.jar" />
        <fileset dir="${alfresco.sdk.dir}/server" includes="**/*.jar" />
    </path>

	<target name="clean">
		<delete dir="${build.dir}" />
	</target>

    <target name="compile" depends="mkdirs">
        <javac classpathref="class.path" debug="${debug}" srcdir="${project.dir}/source"
        	destdir="${build.dir}/classes" target="1.5" encoding="UTF-8"/>
    	<copy todir="${build.dir}/classes">
    		<fileset dir="${project.dir}/source" defaultexcludes="false">
    			<exclude name="**/*.java"/>
    			<exclude name="**/.svn/**"/>
    			<exclude name="**/CVS/**"/>
    		</fileset>
    	</copy>
    </target>

    <target name="package-jar" depends="compile">
        <jar destfile="${jar.file}" encoding="UTF-8">
            <fileset dir="${build.dir}/classes"  defaultexcludes="false" />
        </jar>
    </target>

    <target name="package-amp" depends="package-jar" description="Package the Module" >
        <zip destfile="${amp.file}" encoding="UTF-8">
            <fileset dir="${project.dir}/build" includes="lib/*.jar" />
            <fileset dir="${project.dir}" includes="config/**/*.*" excludes="**/module.properties" />
            <fileset dir="${project.dir}">
            	<include name="module.properties"/>
            	<include name="file-mapping.properties" />
            	<include name="WEB-INF/**/*" />
            	<include name="lib/**/*" />
            	<exclude name="project-build.properties"/>
            	<exclude name="project-build.xml"/>
            </fileset>
        	<zipfileset dir="web" prefix="web"/>
        </zip>
    </target>

	<target name="install-amp" depends="package-amp" description="Uses the Alfresco MMT to install the AMP into ${alfresco.war.path}">
        <java dir="." fork="true" classname="org.alfresco.repo.module.tool.ModuleManagementTool">
			<classpath refid="classpath.server"/>
            <arg line="install ${amp.file} ${alfresco.war.path} -force -verbose"/>
        </java>
    </target>

    <target name="deploy-amp" depends="install-amp" description="Unzips the AMP'd WAR file into ${alfresco.web.dir}">
   		<unzip src="${alfresco.war.path}" dest="${alfresco.web.dir}" />
    </target>
</project>

ainsi que le contenu du fichier file-mapping.properties, utilisé ici pour mapper les dossiers web et WEB-INF :

# Custom AMP to WAR location mappings

#
# The following property can be used to include the standard set of mappings.
# The contents of this file will override any defaults. The default is
# ‘true’, i.e. the default mappings will be augmented or modified by values in
# this file.
#
include.default=true

#
# Custom mappings. If ‘include.default’ is false, then this is the complete set.
#
/WEB-INF=/WEB-INF
/web=/

Voilà :) Vous avez à peu près tout ce qu’il vous faut pour créer vos packages amp. Une fois généré, il vous suffit de le placer dans le dossier /amp ou /amp-share puis exécuter le script apply_amps.bat pour l’injecter dans le war alfresco. Pour comprendre le fonctionnement des packages amp, j’ai utilisé les resources suivantes :

AMP Files – wiki Alfresco
Developing an Alfresco Module – wiki Alfresco
Howto – Create a new Alfresco Module – A Geek’s perspective

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *