Anatomy of an M2M2 module
Module properties
At the bottom of every M2M2 module is the module.properties file. This file resides in the root of the module folder, and provides basic information about the module to the core.
Note: the properties file of modules that you download from the M2M2 store will be signed to prevent tampering. In this state they will not be humanly readable.
Modules can have the following properties. Keys are case-sensitive, and must be entered in the properties file as shown.
| Key | Value | Notes |
|---|---|---|
| name | All modules must have a name, and the name must be unique among all modules in an M2M2 instance. If you upload your module to the M2M2 store for distribution your module name will be required to be unique among all modules offered on the site. Valid names must be three or characters in length but not longer than 30 characters, and can include letters (a-z, upper and lower case), numbers, dash, and underscore. Any other characters are not allowed. Finally, modules may not be named "core". | Required |
| version | All modules must have a version. The version consists of three numbers separated by dots. The numbers are referred to as major, minor, and micro repectively. Numbers may not be negative. | Required |
| description | A textual description of the module in English for use in the M2M2 store. It is required if the module is to be distributed in the M2M2 store, and may not be longer than 255 characters. | Required if the module is distributed in the M2M2 store |
| descriptionKey | A reference to translatable text (found in the i18n.properties files), and used in M2M2 to briefly describe the module. If not provided, the description value will be used instead. | Optional |
| vendor | The name of the vendor of the module. This is typically the name of the company or individual that created it. If the module is distributed in the M2M2 store any value provided in the properties file will be overwritten with the name of the account that owns the module. | Optional |
| vendorUrl | The full URL of the vendor's web site. This can point to any address, and so can be specific to the module if desired. If the module is distributed in the M2M2 store any value provided in the properties file will be overwritten with the URL of the account that owns the module. | Optional |
| classes | A comma-delimited list of fully qualified class names of M2M2 definitions. See "Types of modules" for more information on definition classes. | Optional |
| logo | A URL to a logo that should be used in place of the M2M2 logo in the top-left of the page. | Optional |
| styles | A list of CSS stylesheet files that should be used. These styles can override the default M2M2 styles, and so this can be used to apply a visual theme (or a 'skin') to an instance. | Optional |
| scripts | A list of Javascript files that should be used. These can provide additional functionality to M2M2 pages. | Optional |
| documentation | A folder reference relative to the module where translatable documentation files can be found. See 'Documenting your module' for more information. | Optional |
| locales | A comma-delimited list of the locales for which the module provides translations. This is used if your module is or contains a translation - or a supplement of a translation - of a language or dialect. See 'Translations' for more information. | Optional |
| tagdir | A folder reference relative to the module where JSP tag files are located. (See JSP tag files for more information.) | Optional |
| graphics | A folder reference relative to the module where graphics directories can be found. See the documentation on view graphics for more information. | Optional |
Key folders
There are a few folders into which certain assets must be placed.
| Name | Description |
|---|---|
| classes | This folder will be added to the Java class path, and so can contain resources loaded by the class loader(s). This typically includes property files (e.g. 'env', 'i18n'). |
| lib | This folder should contain all supplemental JAR files required by the module. |
| web | This folder name is used by convention only. It typically will contain assets such as HTML, JSP, JSP tags, and image files. |
Release notes
It is strongly recommended that each version of your module include detailed release notes. This is done by including the file RELEASE-NOTES (all upper case, no extension) in the module's base directory (where modules.properties is). This file is only used when the module is uploaded to the server. The content should be written in English, and formatted in Textile.