Architecture of a plugin Ametys

plugins are complementary modules to the Ametys base, each providing one or more functionalities.

Ametys offers a wide range of plugins (see plugins Ametys ). These "standard" plugins are supplied in the form of jar and must be added to the application's libraries (directory WEB-INF/lib) to be used.

Your application-specific plugins files are located in the plugins.

Directory organization

In the plugins of the CMS application, each plugin has its own sub-directory, organized as follows:

the directory i18n contains translation files (see the chapter oninternationalization )
the directory pages contains any graphics rendering files.

the directory resources contains plugin resources:

  • images in the img
  • files CSS in the css
  • files JavaScript in the js
the directory stylesheets contains files XSL for processing purposes
  • the file plugin.xml is mandatory. It contains the declaration of extension points, configuration parameters and site parameters required by plugin.
  • the file sitemap.xmap contains all the cocoon pipelines required for the plugin
  • the file cms-ribbon.xml defines ribbon buttons associated with plugin (optional)

File plugin.xml

The file plugin.xml is mandatory. It consists of one or more "features"These in turn comprise one or more extension points.
It's useful to group extensions that need to work together under a single "feature".

The file plugin.xml contains at least the <plugin> as follows:

<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>

Configuration parameters

If plugin requires configuration parameters, these should be declared at the beginning of the file, in the <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>

For details of the application's general configuration parameters, please refer to the Configuration parameters page.

Features

A plugin then defines (if necessary) a set of "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>

In each feature, the following can be defined:

  • <config> contains references to the necessary configuration parameters
  • <components> contains the list of components
  • <extensions> contains a list of new extensions (right, content type, service, user manager, ribbon button, etc.)

Feature example

<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>

Feature dependency

TODO

 

sitemap.xmap file

The sitemap.xmap file contains all the Cocoon pipelines required for plugin.

The sitemap.xmap file contains at least :

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

</map:sitemap>

Example of a 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>

For the new plugin to be taken into account, the Tomcat server must be restarted.

Back to top

Setup and integration manual