AMP Files

From AlfrescoWiki

Jump to: navigation, search


Back to Developer Guide

[edit] What is an AMP file?

An AMP file (or Alfresco Module Package) is a collection of code, XML, images, CSS, etc. that collectively extend the functionality or data provided by the standard Alfresco repository.

An AMP file can contain as little as a set of custom templates or a new category. It can contain a custom model and associated UI customisations. It could contain a complete new set of functionality, for example records management.

As a general rule of thumb, anything that is considered to be an 'installable' extension to the Alfresco repository should be called a module and packaged as an AMP file.

AMP files can be installed into the Alfresco WAR using the Module Management Tool. An AMP file has a standard format described below which can be customised if required.

AMP files can now also be created via Apache Maven 2 archetypes and have their lifecycle and deployment into Alfresco managed by the Maven Alfresco AMP archetype. For a full description of Maven AMPs Alfresco support see here

Once the contents of the AMP file has been mapped into an Alfresco WAR using the Module Management Tool, the WAR can be deployed to the application server. When the repository is next started, the installed module configuration will be detected, and the repository will be bootstrapped to include the new module functionality and data.

[edit] The structure of an AMP file

An AMP file is ZIP compressed and has a well known default structure as shown below: 

  /
  |
  |- /config
  |
  |- /lib
  |
  |- /licenses
  |
  |- /web
    |
    |- /jsp
    |
    |- /css
    |
    |- /images
    |
    |- /scripts
  |
  |- module.properties
  |
  |- file-mapping.properties
  • /config

This directory will be mapped into the /WEB-INF/classes directory in the WAR file. Generally your Spring and UI config will reside in the standard package structure within this directory.

Resources that are used by your extension, such as XML import files or ACP's, may also reside in here, as it can often be convenient to place such things on the classpath for loading from Spring.

As a module developer, you will be required to provide a module-context.xml (and optionally a module-disable-context.xml and module-uninstall-context.xml) in the alfresco.module.<moduleId> package. (see Developing an Alfresco Module for more details) These will reside in the /config directory.

  • /lib

This directory will be mapped into /WEB-INF/lib. It should contain any jar files that relate to your module.

  • /licenses

If your module includes any 3rd party jars that require the inclusion of licences that are not currently included in the standard repository WAR, then these should be placed here.

  • /web/jsp

This directory should contain any custom or modified JSP's that relate to your module. The contents are mapped into the /jsp directory in the WAR file.

  • /web/css

This directory should contain any CSS files that relate to your module. The contents are mapped into the /css directory in the WAR file.

  • /web/images

Any images that relate to you module should be placed here. The contents are mapped into the /images directory in the WAR file.

  • /web/scripts

JavaScript files that are used by the user interface should be placed here. The contents are mapped into the /scripts directory in the WAR file.

Any folder structures found in any of these directories are mapped, as they are found, into the destination folders in the WAR.

If a file already exists it is overridden in the WAR; however, a recoverable backup is taken by the Module Management Tool.

Any of these directories can be missing or empty.

  • module.properties

The module.properties file is required to be present in an AMP file. It contains meta-data about the module, most importantly the id and version of the module that this AMP file relates to. See Developing an Alfresco Module for more details.

  • file-mapping.properties

If you wish to customise the way in which your AMP file is mapped into the WAR file using the Module Management Tool, then this file should be provided in the AMP file. If it is not provided, then the default mapping information will be used. See Customising the structure of an AMP file for more information.

[edit] Customising the structure of an AMP file

Note: This feature now available in the post 2.0 HEAD codeline.

In order to customise the structure of your AMP file, a file-mapping.properties file must be provided which describes how the structure of your AMP file will be mapped to the Alfresco WAR when the AMP file is installed by the Module Management Tool.

If no file-mapping.properties file is provided the default mapping, as described above, will be used.

The structure of file-mapping.properties file is that of a standard Java property file, with the 'key' of each entry being the a directory in the AMP file structure and the 'value' being the location that the contents for that directory should be copied to in the WAR file.

If the source directory does not exist in the AMP file, then the mapping will be ignored; however, if the destination directory in the WAR file does not exist then a runtime exception will be raised when the Module Management Tool tries to install the AMP.

If a mapping provided in the file-mapping.properties file overrides one of the default mappings, then this will take precedence when the installation into the WAR takes place. If a mapping is declared that has a folder as the source, then the folder will be recursively copied into the WAR file.

See below for an example of a file-mapping.properties file: 

# 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=false

#
# Custom mappings.  If 'include.default' is false, then this is the complete set.
#
/WEB-INF=/WEB-INF
/web=/
Retrieved from "http://wiki.alfresco.com/wiki/AMP_Files"