Latest Events Module Help
This module is designed to display upcoming events and possibly recent past events from the events component provided by Eric Lamette. A set of optional parameters can be specified to alter the behavior of this module via the administration module management parameters window. Although this module is not packaged with the events component, it is available for download at mosforge.net: mod_events_latest. It will need to be installed separately and made visible (ie. published) thru the mambo admin interface similarly to any other module.
Note also that the following documentation refers to the module parameters being used in the module parameter list thru the mambo module backend I/F. This is the default usage and takes priority over any parameters which may be specified within the events component configuration interface here.
Output Format:
The module outputs the events within an html table structure of n rows by 1 column, where n is the number of events displayed. The absolute max. number of events that can be displayed is 10 (for those that are php literate, this is easily changed in the code if desired.). The default max. number of events displayed is 5. This can be changed by specifying the parameter 'maxEvents' to the module thru the admin interface.
CSS Styling:
Each event will display a start date and time in the first line of the table cell, followed by the event's title in a second line. Both the date/time and event title are assigned separate css classes if style customization is desired.
The first event displayed has its own css style assigned to it (mod_evets_latest_first). Any events beyond the first will use a separate style (mod_events_latest). This is done simply to control the appearance of a horizontal line which separates each event.
Note that the latest events style classes are now integrated with the event components stylesheet and is accessible in this component interface.
Module Parameters:
This module will support the use of the following optional customization parameters thru the Mambo admin module management interface. These parameters mostly alter the behavior of the module by specifying a date range relative to the current day to look for events to display. There is also another parameter called 'displayLinks' which if set to 1, will display the event's title as a link to the event detail form within the events component module.
Parameters Definitions:
Parameter | Description |
maxEvents | max. no. of events to display in the module (1 to 10, default is 5) |
mode |
= 0 (default) display closest events for current week and following week only up to maxEvents. = 1 same as 'mode'=0 except some past events for the current week will also be displayed if num of future events is less than maxEvents. = 2 display closest events for +'days' range relative to current day up to $maxEvents. = 3 same as mode 2 except if there are < maxEvents in the range, then display past events within -'days' range relative to current day. = 4 display closest events for current month up to maxEvents relative to current day. |
days | (default=7) range of days relative to current day to display events for mode 1 or 3. |
displayLinks | = 1 (default is 0) display event titles as links to the 'view_detail' com_events task which will display details of the event. |
displayYear | = 1 (default is 0) display the year (ie. YYYY) in the event's date field. |
disableDateStyle | = 1 (default is 0) do not apply the default mod_events_latest_date css class to the date field |
disableTitleStyle | = 1 (default is 0) do not apply the default mod_events_latest_content css class to the title field |
norepeat | = 1 (default is 0) display any event which has a repeat type only once in the latest events output. |
customFormatStr | = string (default is null). allows a customized specification of the desired event fields and
format to be used to display the event in the module. The string can specify html directly.
As well, certain event fields can be specified as ${event_field} in the string. If desired,
the user can even specify overriding inline styles in the event format using <div> or <span>
to delineate. Or the <div>'s or <span>'s can actually reference new css style classes which you
can create in the template's css file. Event fields available: ${startDate}, ${eventDate}, ${endDate}, ${title}, ${category}, ${contact}, ${content}, ${addressInfo}, ${extraInfo}, ${createdByAlias}, ${createdByUserName}, ${createdByUserEmail}, ${createdByUserEmailLink}, ${eventDetailLink}, ${color} The ${startDate}, ${eventDate} and ${endDate} are special event fields which can support further customization of the date and time display by allowing a user to specify exactly how to display the date with identical format control codes to the PHP 'date()' or 'strftime() functions. If a '%' sign is detected in the format string, strftime() is assumed to be used (supports locale international dates). An example of a specified date and time format used: ${startDate('D, M jS, Y, @g:ia')} This will display the date and time as: 'Fri, Oct 23rd, 2003, @7:30pm' Note that the default customFormatStr is '${eventDate}<br />${title}' (changed in rev 1.2) which will display the date of an event, or the particular date of an event instance in the case of a repeating event type. Not specifying any date format specifiers within parenthesis of the startDate, eventDate or endDate fields will result in a default format as shown above. |
Date Formatting Parameter Reference:
For those not familiar with these date/time format specifiers, you can view the php manual online. A quick reference for these codes is shown below. Note that you can only use the date() or the strftime() specifiers separately. You cannot mix them from each table below.
php date() function format specifiers:
a | Lowercase Ante meridiem and Post meridiem am or pm |
A | Uppercase Ante meridiem and Post meridiem AM or PM |
B | Swatch Internet time 000 through 999 |
d | Day of the month, 2 digits with leading zeros 01 to 31 |
D | A textual representation of a day, three letters Mon through Sun |
F | A full textual representation of a month, such as January or March January through December |
g | 12-hour format of an hour without leading zeros 1 through 12 |
G | 24-hour format of an hour without leading zeros 0 through 23 |
h | 12-hour format of an hour with leading zeros 01 through 12 |
H | 24-hour format of an hour with leading zeros 00 through 23 |
i | Minutes with leading zeros 00 to 59 |
I | (capital i) Whether or not the date is in daylights savings time 1 if Daylight Savings Time, 0 otherwise. |
j | Day of the month without leading zeros 1 to 31 |
l | (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday |
L | Whether it's a leap year 1 if it is a leap year, 0 otherwise. |
m | Numeric representation of a month, with leading zeros 01 through 12 |
M | A short textual representation of a month, three letters Jan through Dec |
n | Numeric representation of a month, without leading zeros 1 through 12 |
O | Difference to Greenwich time (GMT) in hours Example: +0200 |
r | RFC 822 formatted date Example: Thu, 21 Dec 2000 16:01:07 +0200 |
s | Seconds, with leading zeros 00 through 59 |
S | English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j |
t | Number of days in the given month 28 through 31 |
T | Timezone setting of this machine Examples: EST, MDT ... |
U | Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) |
w | Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday) |
W | ISO-8601 week number of year, weeks starting on Monday (added in PHP 4.1.0) Example: 42 (the 42nd week in the year) |
Y | A full numeric representation of a year, 4 digits Examples: 1999 or 2003 |
y | A two digit representation of a year Examples: 99 or 03 |
z | The day of the year 0 through 366 |
Z | Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 through 43200 |
php strftime() function format specifiers:
%a | abbreviated weekday name according to the current locale |
%A | full weekday name according to the current locale |
%b | abbreviated month name according to the current locale |
%B | full month name according to the current locale |
%c | preferred date and time representation for the current locale |
%C | century number (the year divided by 100 and truncated to an integer, range 00 to 99) |
%d | day of the month as a decimal number (range 01 to 31) |
%D | same as %m/%d/%y |
%e | day of the month as a decimal number, a single digit is preceded by a space (range ' 1' to '31') |
%g | like %G, but without the century. |
%G | The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. |
%h | same as %b |
%H | hour as a decimal number using a 24-hour clock (range 00 to 23) |
%I | hour as a decimal number using a 12-hour clock (range 01 to 12) |
%j | day of the year as a decimal number (range 001 to 366) |
%m | month as a decimal number (range 01 to 12) |
%M | minute as a decimal number |
%n | newline character |
%p | either `am' or `pm' according to the given time value, or the corresponding strings for the current locale |
%r | time in a.m. and p.m. notation |
%R | time in 24 hour notation |
%S | second as a decimal number |
%t | tab character |
%T | current time, equal to %H:%M:%S |
%u | weekday as a decimal number [1,7], with 1 representing Monday |
%U | week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week |
%V | The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. (Use %G or %g for the year component that corresponds to the week number for the specified timestamp.) |
%W | week number of the current year as a decimal number, starting with the first Monday as the first day of the first week |
%w | day of the week as a decimal, Sunday being 0 |
%x | preferred date representation for the current locale without the time |
%X | preferred time representation for the current locale without the date |
%y | year as a decimal number without a century (range 00 to 99) |
%Y | year as a decimal number including the century |
%Z | time zone or name or abbreviation |
%% | a literal `%' character |
Using the Module Parameters:
To specify these parameters in the module's admin management interface, insert them into the
'parameters' text window at the very bottom on separate lines like so:
mode=1
days=3
displayLinks=0
customFormatStr='${startDate('M jS, g:ia -')}${endDate(' g:ia')}<br />${category}: ${title}'
The customFormatStr example shown above will display the date/time as: 'Oct 23rd, 7:30pm - 8:30pm', and the category
and title on the following line.
Other Not-so-Obvious event Variables:
${createdByUserEmail} - creator's email address
${createdByUserEmailLink} - this provides a link address to invoke an email form to send mail to the event creator.
To create a hyperlink with this, it would be used like: <a href=${createdByUserEmailLink}>inquire</a>
${eventDetailLink} - a link to the event details page within the events component. Note that this is a little
different to the use of the event link on the event title field as enabled by the 'displayLinks'
parameter. An example of the use of this variable is shown in the section below.
${color} - the assigned 'color' for the event as was done when the event was created in the event
component. This can be used in an inline css style within the ${customFormatStr} to control
background color, font color.
Further Examples for Using the '${customFormatStr}' Parameter:
Ex. 1.
displayLinks=1
mode=0
customFormatStr='<div style='background-color:${color};'>${startDate('m/d/y')}, ${title}</div>'
This will display a simple date in MM/DD/YY format followed by the hyperlinked event title, with the same background
color assigned as when the event was created in the events component. You need to be careful using this since there
currently is no foreground color selection in events. So depending on colors, you can get poor contrast or sometimes
the text can disappear into the background if the same color.
Ex. 2.
displayLinks=1
disableDateStyle=1
disableContentStyle=1
mode=2
days=14
customFormatStr='<span class='mod_events_latest_date'>${startDate('%x, %X - ')}${endDate('%X')}</span><br /><span class='mod_events_latest_content'>${category}: ${title}</span>'
This example will print the date and time in a default 'preferred' format according to the locale, whatever that may be
with respect the the php function 'strftime()'. The appropriate language will be used, whether that be english, german, french,
or anything else. Notice that the 'disableDateStyle' and 'disableContentStyle' parameters are used to suppress the module's
autoformatting of these around the ${startDate}, ${endDate}, or ${title} fields since we are using several custom fields with
embedded text. So it is more appropriate to explicitly specify the css class names using a HTML <span> element to delineate
the text to be formatted.
Also note that text will wrap around end of the module's right edge if there is not enough room on the line. You will either
need to downsize display fonts thru style control, widen the left display area for modules in your mambo template, or
some other method.
Ex. 3.
displayLinks=0
customFormatStr='<div style='cursor: default;' onMouseOver="this.style.border='thin dotted red';" onMouseOut="this.style.border='none';" onclick="parent.location = ${eventDetailLink};">${startDate}<br />${title}</div>'
This is a fairly sophisticated example using inline css styles and mouse events, but it demonstrates the power of the new
customFormatStr fairly well. These parameter settings above will display the standard date and title fields of the event.
However, now when the cursor is over ANY part of an event's info, a red dotted border surrounds the event. Clicking the
mouse will now display the event's detail from the events component in the main area of the page. Basically, what is
being done is a hyperlink.