<< Back - Alkacon logo

OpenCms 6.0 interactive documentation:

The folder structure of a module

OpenCms logo - Forward >>

The folder structure of a module

When you create a new module, a skeleton folder structure is automatically created for your module. The main module directory will be placed in the /system/modules/ folder and it will have the package name of your module, so if your module is named org.opencms.mymodule the main module folder will be /system/modules/org.opencms.mymodule/.

The main module folder can contain several subfolders. All of these subfolders will be considered part of the module and automatically exported (or deleted) with the module. The subfolders of a module can be divided in three categories: "system" folders, "convention" folders and "custom" folders.

Module "system" folders

Module "system" folders are folders that require a fixed name so that OpenCms can find it's bits and bytes at the right place. These folders are:

/system/modules/org.opencms.mymodule/default_bodies/
/system/modules/org.opencms.mymodule/templates/
  • The default_bodies/ subfolder contains OpenCms XMLTemplates with HTML fragments for the "body" section of your pages. By putting files in default_bodies/, you can add pre-defined page layouts (e.g. complex table layouts) to your OpenCms installation. The titles of the default bodies found are displayed at the "new page" dialog in the "Copy content from" selectbox that is shown to the user. User permissions are also checked during this process, so that you can hide default bodies with the "v" flag for certain users or groups.
  • The templates/ subfolder contains OpenCms templates. When a user creates a new page, OpenCms checks the templates/ subfolder of all installed modules to search for templates. The titles of the templates found are displayed at the "new page" dialog in the "Template" selectbox that is shown to the user. User permissions are also checked during this process, so that you can hide templates with the "v" flag for certain users or groups.

In case you either selected the Export classes/ folder and/or Export lib/ folder options during module creation, these folders are additionally created:

/system/modules/org.opencms.mymodule/classes/com/opencms/mymodule/
/system/modules/org.opencms.mymodule/lib/
  • Inside the classes/ subfolder, an entire subfolder structure with the package name of your module is created. All subfolders of the classes/ subfolder and their contents will be exported to WEB-INF/classes/ when your module is published. For example you could place a localization Java resource bundle in the module subfolder classes/org/opencms/mymodule/my.properties.
  • In the lib/ subfolder you could place any Java archives (JAR) that are to be shipped with your module. All contents of the lib/ subfolder will be exported to WEB-INF/lib/ when your module is published.
Module "convention" folders

Module "convention" folders are folders that you must add manually to your module. You are free to create any subfolders in your modules and name them as you like. However, we suggest you to follow the conventions outlined here that we have established for certain module functionalities. This will make it a lot easier for other people to understand your module if you ever contribute modules to the OpenCms community.

The following module folders are considered to be "convention" folders:

/system/modules/org.opencms.mymodule/resources/
/system/modules/org.opencms.mymodule/elements/
  • The resources/ subfolder by convention keeps any images, JavaScripts and other static resources like CSS style sheets that are part of the HTML of your templates or otherwise required by your module.
  • The elements/ subfolder by convention is used for the storage of further JSP or legacy XML template elements, such as navigation elements, forms etc.

As said already, it is not a system requirement that these folders are named this way, but we suggest you follow these conventions.

Module "custom" folders

Any other subfolders you create for your module are considered to be "custom" module folders. How much of these "custom" folders a module has is entirely up to the module developer.

©2003-2005 Alkacon Software (http://www.alkacon.com) - The OpenCms experts