OpenCms documentation
OpenCms documentation

Modules app

module

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.

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.

  • searchBigIconActive

    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.

Information

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

Edit

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.

Delete

Removes the module and deletes all resources belonging to the module

Export

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.

Explorer

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.

Package name

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

Module name

A human readable name for the module.

Module description

A description for the module

Module version

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

Module group

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.

Action class

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.

Import script

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

Site

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

Fixed import site

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.

Author name

Name of the modules author.

Author email

E-mail of the modules author.

Export with reduced meta-data

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.

Auto-increment version

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.

Create module folder

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

Create templates subfolder

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

Create i18n subfolder

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

Create formatters subfolder

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.

Create lib subfolder

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.
Create resources subfolder

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.

Module resources

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

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.

Export points

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.

Dependencies

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.