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 added the classes/folder and/or
the lib/ folder on 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.
|