Skip to content
OpenCms documentation
OpenCms documentation

Modules app

In OpenCms functionality and also content is encapsulated in modules. The default installation contains the modules for the core functionality and modules including demo content and functionality. If you add new functionality or resources, provide your own XML content types or write your own templates and formatters we recommend encapsulating the new functionality in a well-structured set of modules. Also web pages can be encapsulated in modules to move them easily between different OpenCms installations. Modules can be created, imported, exported, and (re-)configured via the modules app. Only in some rare cases manually touching configuration files is necessary.

Go to the launchpad and click “Modules" to open the modules app.

The app 'Modules' in the launchpad

The apps main view looks as follows.

The modules app's main view

It allows you to create new modules or import modules already on the server or uploaded via HTTP. Furthermore, the list of all imported modules is shown. Modules from the searchable list can be edited, exported or deleted. Moreover, you can switch to the module's main folder in the explorer.

  • publishBigIconActive

    Opens the publish dialog for publishing your changes.

  • Opens a dialog for creating a new module

  • upload

    Opens a dialog to import a module either via HTTP or directly from the server.

  • elementsBigIcon

    Shows how many modules are installed.

Opens a dialog that shows the modules package name, name and description and lists all resource types declared in this module (with name and id).

Opens a dialog for editing the module. The dialog is similar to the one for adding a new module, but hides settings that should not be changed.

Removes the module and deletes all resources belonging to the module

Exports the module, including all module resources. A zip file is produces that can be imported again. The module itself remains on the system unchanged.

Opens the module folder in the explorer.

To create a new module on your OpenCms instance, choose the "New module" option () in the toolbar. A dialog opens to configure your new module. Here are explanations on the options.

A name according to the Java package name syntax. It is the unique identifier for the module. Typically names like com.mycompany.xxx.

A human readable name for the module.

A description for the module

Version of the module. Specified in format xx.xx.xx.xx, e.g., 1.0 or 1.0.0.12 etc.

A human readable name for a group of modules. It has no programmatical influence, but helps to keep an overview on which modules belong together. E.g., you may have several modules making up you template then you might group them by providing the same group name for all of them.

The fully qualified name of a Java class implementing I_CmsModuleAction. You write and configure such module actions to perform special actions during the OpenCms lifecycle if the module is installed, e.g., on startup or shutdown.

An OpenCms shell script that is triggered during installation right after the module's resources are imported.

The site relative to which the module resources are handled. Typically the root folder should be used.

If checked, the module can only be imported to the site specified in "Site". Otherwise, you can choose to import the (of course, formerly exported) module into another site. Typically, it makes sence to fix the import site to the root folder.

Name of the modules author.

E-mail of the modules author.

Check this option, to reduce the meta-information exported for the resources. This makes typically sence. In particular, it will prevent merge conflicts when you use version control for your modules. See in the topic about developer tools for more information.

Since OpenCms 11 the auto-increment mechanism is enhanced. If you export a module, it is checked if either the module resources or the configuration has changed. The version number is only updated if at least one of the two conditions if fulfilled.

A modules resources are typically located und /system/modules/{module package name}/. Check this option to create that folder automatically.

If checked, the folder /system/modules/{module package name}/templates is created automatically. In this folder the template JSPs are typically placed.

If checked, the folder /system/modules/{module package name}/i18n is created automatically. In this folder the message bundles are typically placed.

If checked, the folder /system/modules/{module package name}/formatters is created automatically. In this folder the formatter JSPs and the corresponding formatter configurations are typically placed.

If checked, the folder /system/modules/{module package name}/lib is created automatically. In this folder Java libraries shipped with the module are typically placed. The folder is then configured as export point to the webapp's lib folder on the RFS. Hence, after module installation and restart of the servlet container the library is automatically present.

Be careful shipping the libraries as part of the module and using the export point mechanism. In particular when replacing or deleting a module, your servlet container may crash, since - depending on the servlet containers configuration - it will miss the exported jar that is removed in module deletion. You might simply deploy your libraries separately to prevent such issues.

If checked, the folder /system/modules/{module package name}/resources is created automatically. In this folder statically served contents are typically placed, e.g., images, css, javascript.

Specify which VFS resources belong to the module. If you specify a folder under "Included resources" the folder and the resources below will be added to the module resources, except the ones excluded via "Excluded resources"

Avoid overlapping of resources of different modules.

Module parameters are key-value pairs written as key=value that can be accessed in JSPs/Java classes. These parameters are typically used to configure options that are related to the specific OpenCms instance the module is installed on. E.g., if your module's code needs to connect to a database that might vary from installation to installation, you can provide the connection string as parameter.

Via export points, you specify that a resource in the VFS - or a specific folder and all resources in it - should be exported to a specific place at the RFS. This is in particular used to export Java libraries or classes to the place where your servlet container expects them.

A module can depend on other modules. Here you can specify this dependency. You can also specify the minimal version of the required module. Dependencies are checked when modules are imported or deleted. You are not allowed to break dependencies on import or deletion of a module.