Architecture d'un plugin Ametys

Les plugins sont des modules complémentaires au socle Ametys apportant chacun une ou plusieurs fonctionnalités.

Ametys propose de nombreux plugins (voir l'espace dédié aux plugins Ametys). Ces plugins "standards" sont fournis sous forme de jar et doivent être ajoutés aux librairies de l'application (répertoire WEB-INF/lib) pour être utilisés.

Les plugins propres à votre application se trouvent quand à eux dans le répertoire plugins.

Organisation des répertoires

Dans le répertoire de plugins de l'application CMS, chaque plugin fait l'objet d'un sous-répertoire dont voici-ci l'organisation :

le répertoire i18n contient les fichiers de traductions (voir le chapitre consacrée à l'internationalisation )
le répertoire pages contient les éventuels fichiers de rendu graphique.

le répertoire resources contient les ressources du plugin:

  • les images dans le répertoire img
  • les fichiers CSS dans le répertoire css
  • les fichiers JavaScript dans le répertoire js
le répertoire stylesheets contient les fichiers XSL dans un but de transformation
  • le fichier plugin.xml est obligatoire. Il contient la déclaration des points d'extensions, des paramètres de configuration ou de site nécessaires au plugin.
  • le fichier sitemap.xmap contient l'ensemble des pipelines cocoon nécessaire au plugin
  • le fichier cms-ribbon.xml définit les boutons du ruban associés au plugin (optionnel)

Fichier plugin.xml

Le fichier plugin.xml est obligatoire. Il est constitué d'une ou plusieurs "features", qui regroupent elles-mêmes une ou plusieurs point d'extensions.
Il est utile de regrouper dans une même "feature" les extensions qui doivent travailler ensemble.

Le fichier plugin.xml contient au minimum la balise <plugin> comme suit :

<plugin xmlns="http://www.ametys.org/schema/plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.ametys.org/schema/plugin http://www.ametys.org/schema/plugin-2.0.xsd"
        runtimeVersion="2.0" version="2.0">
</plugin>
Paramètres de configuration

Si le plugin nécessite des paramètres de configuration, il convient de les déclarer  au début du fichier, dans la balise <config>.

<plugin xmlns="http://www.ametys.org/schema/plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.ametys.org/schema/plugin http://www.ametys.org/schema/plugin-2.0.xsd"
        runtimeVersion="2.0" version="2.0">

	<config>
		<param name="custom.myparam" type="string">
			<label i18n="true">PLUGIN_CUSTOM_MYPARAM_LABEL</param>
			<description i18n="true">PLUGIN_CUSTOM_MYPARAM_DESC</param>
		</param>
	</config>

</plugin>

Pour plus de détails sur les paramètres de configuration généraux à l'application, référez-vous à la page Paramètres de configuration.

Les features

Un plugin définit ensuite (si besoin) un ensemble de "features" :

<plugin xmlns="http://www.ametys.org/schema/plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.ametys.org/schema/plugin http://www.ametys.org/schema/plugin-2.0.xsd"
        runtimeVersion="2.0" version="2.0">

	<config>
		[...]
	</config>

	<feature name="feature1">	
		[...]
	</feature>

	<feature name="feature2">
		[...]
	</feature>
</features>

Dans chaque feature, peuvent être définis :

  • <config> contient les références vers les paramètres de configuration nécessaire
  • <components> contient la liste des composants
  • <extensions> contient la liste des nouvelles extensions (droit, type de contenu, service, gestionnaire d'utilisateurs, bouton du ruban, etc ...)

Exemple de feature

<feature name="runtime.monitoring">
		<!-- Utilisation d'un paramètre de configuration -->		
		<config>
            <param-ref id="custom.myparam"/>
        </config>

		<!-- Déclaration des composants -->
		<components>
            <component role="org.ametys.plugins.custom.MyComponent"
                       class="org.ametys.plugins.custom.MyComponent"
                       logger="org.ametys.plugins.custom.mycomponent"/>
        </components>
        
        <extensions>
			<!-- Déclaration d'un nouveau droit -->
			<extension point="org.ametys.runtime.plugins.core.right.RightsExtensionPoint"
                       id="org.ametys.plugins.custom.right">
                <right id="Plugin_Custom_Right">
                    <label i18n="true">PLUGINS_CUSTOM_RIGHT_LABEL</label>
                    <description i18n="true">PLUGINS_CUSTOM_RIGHT_DESC</description>
                    <category i18n="true">PLUGINS_CUSTOM_RIGHT_CATEGORY</category>
                </right>
            </extension>

			<!-- Déclaration d'un nouveau service -->
			<extension point="org.ametys.web.service.ServiceExtensionPoint"
                          class="org.ametys.web.service.StaticService"
                          id="org.ametys.custom.service">
                <url>service/view.html</url>
                <right>Plugin_Custom_Right</right>
            
                <label i18n="true">PLUGINS_CUSTOM_SERVICE_LABEL</label>
                <description i18n="true">PLUGINS_CUSTOM_SERVICE_DESC</description>
                <category i18n="true">plugin.web:PLUGINS_WEB_SERVICE_CATEGORY_20_CONTENT_EXTERNAL</category>
				
				<parameters>
					[...]
				</parameters>
			 </extension>
		</extensions>
</feature>
Dépendance de feature

TODO

 

Fichier sitemap.xmap

Le fichier sitemap.xmap comprend l'ensemble des pipeline Cocoon nécessaire au plugin.

Le fichier sitemap.xmap contient au minimum :

<?xml version="1.0" encoding="UTF-8"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

</map:sitemap>

Exemple de pipeline:

<?xml version="1.0" encoding="UTF-8"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

    <map:pipelines>
		
		<map:pipeline>
			<map:match pattern="services/view.html">
				<map:generate src="pages/db.xml"/>
				<map:transform src="pages/services/view.xsl"/>
				<map:serialize type="xhtml"/>
			</map:match>
		</map:pipeline>
	</map:pipelines>

</map:sitemap>

Pour que le nouveau plugin soit pris en compte, il faut relancer le serveur Tomcat.