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.

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

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.