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.
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.
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.
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.
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.
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).
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.
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
).
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.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
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
).
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
).
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
).
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
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
).
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).
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.
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
).
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.
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:
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;
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:
the first line specifies the recipient
address;
"Name" is a text field. This is the default when no other parameters are specified;
"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;
"Message" and is a text area of 12
rows;
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
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
).
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.
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
;
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.