1. Standard Modules
Prev | Chapter 6. Modules | Next

## 1. Standard Modules

A web page is not just a block of text. Many pages on the web perform some common tasks: image galleries, mail forms, news and so on. While one can just write down those pages each time, it is clear that some automation is possible in those cases. The MeshCMS answer to this demand is the concept of module. A module is a configurable zone in a page: when you edit the page, you have some boxes where you can select a module and provide an argument (usually a file or directory) and some advanced parameters. If the argument is not specified, modules behave differently: some can default to the directory that contains the page, while others will do nothing.

### Note

the argument of a module is not necessarily a directory or a file. For example, in the mail module you can specify an e-mail address as argument, and a standard form will be created using that address as recipient.

When you edit a page, you will have the chance to configure as many modules as the page theme specifies. Normally all themes should contain a module at least. For each module you can also set a title and some advanced parameters. The former can be displayed in the page or not, according to the theme used. The latters depend on the module used and allow to customize it further, although modules are expected to provide an adequate default behavior when no parameters are specified.

MeshCMS provides some modules, and others can be created by everyone that is able to write a JSP page. Details about available modules are illustrated in the following sections.

### 1.1. Audio Player

The audio player module shows a MP3 player using the Flash-based XSPF Web Music Player. It will play all the MP3 files that are available in the directory passed as argument.

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

### 1.2. Blog

The blog module shows a preview of pages in a directory using a blog-like interface: content is truncated to a maximum length and links to full pages are provided. Pages are ordered by date and meta keywords are displayed as "article tags".

Starting from version 3.5, this module is highly configurable and can replace other modules like Most Visited and

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class;

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- `sort`: the preferred sorting order. Accepted values are `newest` (default, newest articles first) and `mostviewed` (most viewed articles first);

- `mode`: the text rendering, can be `html` (default) or `text`;

- `entries`: number of entries per page (default `5`);

- `maxchars`: maximum length of the excerpt for each article (default as per site configuration);

- `history`: shows a link to previous articles, `true` (default) or `false`;

- `keywords`: shows keywords (tags) after each article, `true` (default) or `false`;

- `readlink`: shows a link to the full article after the excerpt, `true` (default) or `false`;

- `updatedate`: updates page last modified time, `true` (default) or `false`. Note that this does not change the last modified time on disk, unless explicitly required by the lastmodified tag;

- `imagesize`: size in pixels of article images (images that are in the same folder have a name in the required format, i.e. `index_image.jpg` for `index.html` or `page_image.jpg` for `page.html`); if this parameter is not specified, images are not shown even if available;

- `tag`: if specified, only pages with that tag will be shown in the blog.

### 1.3. Blog Calendar

The blog calendar module shows a list of months/years to select articles in a specific month. It has been thought to be used in the same page as the blog module.

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

### 1.4. Blog Tag List

The blog tag list module shows a list of tags to select articles marked with a specific tag. It has been thought to be used in the same page as the blog module.

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class;

- `step`: step for item css classes (default `1` - use `0` to remove classes);

- `max`: maximum for item css classes (default no maximum).

### 1.5. Chat

The chat module has been created by Pierre Métras and provides a simple, AJAX-based chat. To use it, simply select the module: no argument is needed.

Advanced parameters:

- `css`: the name of a css class;

- `room`: chat room identifier, else use public room shared by all pages and all sites;

- `cols`: number of columns of the chat list;

- `rows`: number of rows of the chat list.

### 1.6. Comments

The comments module creates a form that allows site visitors to leave comments on that page. Authenticated users with edit permissions on that page can delete unwanted comments by visiting the page itself.

Argument: path to a directory used to hold comments. If not provided, a default directory will be used.

Advanced parameters:

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- `form_css`: the ccs class of the `div` that contains the entire form. The default value is `mailform`;

- `field_css`: the css class of the individual form fields. The default value is `formfields`;

- `notify`: an optional e-mail address to receive comment notifications;

- `html`: if `true`, shows a basic HTML editor (default `false`);

- `parse`: if `true` (and if `html` is `false`), activates hyperlinks in comments (default `false`);

- `max_age`: maximum number of days after which comments are not shown (default no maximum);

- `moderated`: hides comments until approved by an authenticated user (default `false`);

- `math`: asks users to calculate the sum of two numbers (default `false`);

- `captcha`: shows a CAPTCHA image (default `true`).

### 1.7. Diary

The diary module creates a page showing the first words of a list of pages with links to the full pages, in a similar fashion to the headlines module. The Diary module allows you to filter and sort the summarized pages by date. The date used for sorting can be specified in two ways:

- By including the date in the page, and surrounding it in a CSS style, either in a `<div>` or `<span>` element. The default style is `diary-date`. The date itself must be in the `normal` date format, for example as output by the lastmodified tag. If you add the `diary-date` style to your theme stylesheet, you can use the page editor to easily tag the date in a page.

- If the date is not specified in the page, the last modified date of the file is used. This can be set using the File Manager if required.

- If the date us set to the string `IGNORE_FILE`, the file will be ignored and will not be indexed by the Diary module.

Argument: path to a directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: The name of a css class, for displaying the generated list;

- `date`: The date format to be used for labelling the list entries. `none` (default), `normal` (date only) or `full` (date and time);

- `start:` The date to start the listing from, either in `normal` format or as an offset from today of the form `[+-]NN[dwmy]`, where [dwmy] is the unit type - days, weeks, months, years and NN is the number of days, weeks, months or years. The default is the current date;

- `period`: The period for which entries are to be displayed (default is all past entries);

  - `+` all future entries

  - `-` all past entries

  - `+-` all entries, sorted new to old

  - `-+` all entries, sorted old to new

  - `[+-]NN[dwmy]` entries within a specified period, in the same format as the `start` parameter

- `date-style`: CSS style used to tag the date used for sorting (default = `diary-date`);

- `words`: The number of words to display for each item (default = 50);

- items: The maximum number of entries to display in the list, where -1 means all entries, default = 5.

Example 6.1. An example of tagging a date so that it is used to sort the page. Be sure to format the date appropriately for the locale you are using:

    <h1>Date: <span class="diary-date">01-Dec-2006</span></h2>

Example 6.2. An example showing how to use IGNORE_FILE to skip the indexing a file. The 'hide' style is used to stop the IGNORE_FILE string from being displayed.

    <span class="diary-date hide">IGNORE_FILE</span>

Example 6.3. An example using advanced parameters to display all future entries:

    period=+, items=-1

Example 6.4. An example using advanced parameters to display entries starting at a specified date, for a specified period. Again, the date needs to be formatted appropriately for the locale you are using:

    start=01-Jan-2006, period=-6m, items=-1

Example 6.5. An example of diary entries starting 1 year ago, forwards for a period of 1 month. If there are more than 10 entries only the first 10 would be shown:

    start=-1y, period=+1m, items=10

### 1.8. Downloads

The downloads module creates a list of downloadable files. An icon and the size are shown near the name of each file.

Argument: path to a file or directory. If not provided, the module does nothing.

Advanced parameters:

- `css`: the name of a css class;

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- `force`: forces download even for files that could be viewed in the browser (default `true`).

### 1.9. Embed

The embed module is useful to embed code snippets in the page (e.g. YouTube videos).

Argument: code snippet or path to a file that contains the code to be inserted. If not provided, the module does nothing.

Advanced parameters:

- `delay`: uses JavaScript to embed the code after page load (default `false`).

### 1.10. Frame

The frame module allows to display an external page in an IFrame.

Argument: path or URL of the page.

Advanced parameters:

- `height`: the height of the IFrame (default `40em`).

### 1.11. Gallery

The gallery module creates thumbnails for a list of images. Thumbnails link to full images, and file names are used as captions.

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class;

- `captions`: defines if the captions must be shown or not. Values are `true` (default) and `false`;

- `columns`: defines the number of columns (default `3`);

- `quality`: defines the algorithm used to create the thumbnails. Values are `low` and `high` (default). High quality requires more CPU and RAM (thumbnails are cached anyway);

- `order`: defines the sort order of the thumbnails. Values are `name` (default), `date` or `date_fwd` (sort forwards by date), `date_rev` (sort reversed by date), `random`;

- `lightbox`: if `true`, the Lightbox script is used to show images (default `false`). Please check that it is compatible with your theme.

- `colorbox`: if `true`, the Colorbox script is used to show images (default `false`). Please check that it is compatible with your theme.

By default, the labels which are displayed under the thumbnails are generated from the image filenames, using the following steps:

- The file suffix is removed;

- All underscores are replaced with spaces;

- The first character of each resulting word is converted to title (upper) case.

So by formatting the image filenames appropriately you can specify the thumbnail label. If this proves inconvenient, for example if you want to order the files by name but want to use different thumbnail labels, or if you want to use characters that are not valid as part of a filename, you can specify the thumbnail labels in a seperate text file. This file is called `gallery.captions` and must be in the same directory as the image files to which it refers. The format of this file is simple: it must contain a block for each required thumbnail caption. Blocks are seperated by a blank line, and each block consists of single image filename on a line, followed by one or more lines of caption text. If one of those lines starts with `link:`, it will be used as URL instead of the full image. An example is given below.

Example 6.6. An example gallery.captions file, containing thumbnail captions for three files:

    image_01.jpg
    This is the first image

    image_02.jpg
    This is the
    second image

    image_03.jpg
    link: http://www.yoursite.com
    This is the third image

### 1.12. Headlines

The headlines module shows the first words of a list of pages, adding links to go to the full pages.

Argument: path to a directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class;

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- `maxchars`: maximum length of the excerpt for each page (default `500`).

### 1.13. Include

The include module adds the contents of a list of pages.

Argument: path to a file or directory. If not provided, the module does nothing.

Advanced parameters:

- `css`: the name of a css class;

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- sort: file sorting. Can be `newest` (default) or `alphabetical`.

### 1.14. Include As Text

The include as text module adds the contents of a list of files as plain text (i.e. inside a `<pre>` tag).

Argument: path to a file or directory. If not provided, the module does nothing.

Advanced parameters:

- `css`: the name of a css class.

### 1.15. Latest Changes

The latest changes module shows the first words of the most recently modified pages, adding links to go to the full pages. Modified pages are searched in subdirectories too.

Argument: path to a directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class;

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- `maxchars`: maximum length of the excerpt for each article (default `500`).

- `items`: defines the number of pages to show (default `5`).

### 1.16. List Pages

The list pages module creates a list of links to the pages contained in the given directory.

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class.

### 1.17. Mail

The mail module creates a mail form. This allows visitors to your site to send you mail without you having to expose your email addresses on your site.

Argument: email address or path to mail form definition file (see below).

Advanced parameters:

- `form_css`: the ccs class of the `div` that contains the entire form. The default value is `mailform`;

- `field_css`: the css class of the individual form fields. The default value is `formfields`.

Note: There is a bug in Internet Explorer 6 that affects the display of the `textarea` form component. This results in the `textarea` being resized inappropriately as soon as text is entered into it. The workaround is to explicitly set the width of the `div` containing the form, and to set the width of the contained fields to `100%`. The default ccs for the `mailform` and `formfields` styles does this to avoid the bug, be aware of this if you choose to modify or override these styles.

The mail module can be used in one of two ways:

1. you can specify an e-mail address as argument. A simple form will be inserted into the page and the address you entered will receive the messages. The form can't be customized, but this method is very easy to apply and will be enough for most situations;

2. you can specify the name of a text file as argument. In this case, the form will be created accorded to the instructions contained in that file. This method offers more options and will be described in the rest of this section, since it requires you to learn the syntax used in the text file.

In both cases, messages sent through a mail form will be delivered to an address you specify (which will not be visible to anyone viewing your site, since it's not displayed in the page and not included in its source).

To create a form using the second method, you must write a text file that adheres to a specific syntax. As a first example, let's create the simplest form you could use (similar to the one provided by method 1, above):

    recipient:name@site.com

    Name

    E-mail
    email
    sender

    Message
    text:12

    Send
    submit

Field definition blocks are separated by empty lines. The first line of each block ia a field name on the resulting form. Let's look at each block separately:

1. the first line specifies the `recipient` address;

2. "Name" is a text field. This is the default when no other parameters are specified;

3. "E-mail" is a text field that is expected to contain an `e-mail` address (a check will be executed to verify this condition). Its value will be used as `sender` address;

4. "Message" and is a text area of `12` rows;

5. the next element is a `submit` button whose label is "Send this message".

Here's how to add a drop down box:

    recipient:name@site.com

    Name

    E-mail
    email
    sender

    Topic
    options: Information, Support Request, Feedback

    Message
    text:16

    Send Now
    submit

Other notes:

- the default field type is `text`;

- the `number` field type can be used for fields that require a numeric value;

- the `reset` field inserts a reset button. A label can be specified as for the `submit` button;

- the `textarea` field type is a synonym for `text:12`;

- the `value`: line can be used to provide a default value for all fields of type `text`, `email`, `number` and `textarea`;

- the `options`: line can be used to provide a list of values for a drop-down box;

- the `sendername` attribute indicates that the field value is to be used as name of the sender;

- the `sender` attribute indicates that the field value is to be used as the email address of the sender;

- the `subject` attribute indicates that the field value will be the subject of the message;

- the `message` attribute will insert the field value "as is", i.e. without specifying a field name;

- the `required` attribute may be specified to make a field mandatory. Required fields are shown in bold by default;

- the `hidden` attribute can be used to include a non-displaying value in the form;

- the `messagebody` attribute can be used to identify the field to be used as the body of the generated email;

- buttons are inserted at the end of the form, regardless of the field order;

- each parameter (field name, field type, options, etc.) must be on a single line.

A more complex example is shown here:

    recipient:name@site.com

    Note
    hidden
    value: This is a hidden note

    Name
    sendername

    E-mail
    email
    sender

    Gender
    options: male, female

    Age
    options: less than 13, 13-20, 21-30, 31-40, 41-50, 51-60, more than 60

    Subject
    subject
    value: Hello
    required

    Message
    text:16
    required

    Send Now
    submit

    Reset All Fields
    reset

And here's how it looks in the browser:

Finally, this is the default MeshCMS form in English (the recipient is not specified, since it is added in the page editor):

    Name
    sendername

    E-mail
    email
    sender

    Message
    textarea
    messagebody

    Send Now
    submit

### 1.18. Most Visited

The most visited module shows the first words of the pages that have been viewed more times in the latest days, adding links to go to the full pages. Pages are searched in subdirectories too.

Argument: path to a directory. If not provided, defaults to the directory that contains the current page.

Advanced parameters:

- `css`: the name of a css class;

- `date`: the type of file date to be shown. Possible values are `none` (default), `normal` (date only) and `full` (date and time);

- `maxchars`: maximum length of the excerpt for each article (default `500`).

- `items`: defines the number of pages to show (default `5`);

- `minvisits`: minimum number of page views that a page must have to be included in the list (default `0`).

### 1.19. Parse

The parse module includes a list of files using the `pageContext.include()` Java method.

Argument: path to a file or directory. If not provided, the module does nothing.

### 1.20. Site Map

The site map module creates a site map using an HTML unordered list.

Argument: path to a directory. If not provided, the site map will start from the directory that contains the current page.

Advanced parameters:

- `allowHiding`: defines if the module honours the "hide submenu" option or not. Values are `false` (default) and `true`;

### 1.21. Video Player

The video player module shows a FLV video player using the Flash-based FlowPlayer. It will play all the FLV files that are available in the directory passed as argument.

Argument: path to a file or directory. If not provided, defaults to the directory that contains the current page.

Prev | Up | Next
Chapter 6. Modules | Home | Chapter 7. Tag Library