back to Modules

General Calendar Setup

What does this do?

Calendar is a module for displaying events on your page. When the module is installed, a Calendar admin page is added to the plugins menu that will allow you to manage your events.

Security

The user must belong to a group with the 'Modify Calendar' permission in order to add, edit, or delete calendar event entries.

How do I use it?

1. Put the cms_module tag in the page content. The code would look something like:

     {cms_module module="Calendar" table_id="big"}

The table_id parameter is required for the CSS (see below for details).

2. Edit the example calendar stylesheet which has been inserted into you css-list.

3. Associate this stylesheet with the template you are using for the calendar page.

To attach the stylesheet to your template:

  1. Go to "Layout -> Templates"
  2. Click the CSS icon (Attach Stylesheet to Template) button to the right of your template
  3. Choose "Calendar CSS example" from the drop-down menu.
  4. Click the "Add a Stylesheet" button.

Locale

Calendar also supports translation of all text strings to another language. To support your language, add a file named <language>.php to the modules/Calendar/lang directory. I would suggest copying en_US.inc.php as a starting point. You can then select your language from the Settings tab in the Calendar admin.

Note you can override the language used for a particular calendar displayed on the front end site by adding lang="xx_XX" to the {cms_module module="Calendar"} call. For instance: {cms_module module="Caldendar" lang="de_DE"}

What Parameters Exist?

Display >>

calendar - displays events for the current month in a traditional grid. Inclues links to prev. and next months.

list - displays events for the current month as a list. Includes links to prev. and next months.

yearlist - displays events for the current year in a list. Includes links to prev. and next years.

pastlist - displays all past events. No prev/next links.

upcominglist - displays all upcoming events. No prev/next links.

If no parameters are defined it defaults to "calendar" (optional)

category >> Only display items for that category. Leaving unset, will show all categories. Note that you can limit to muliple categories by separating each one with a comma.(optional)

month >> Display entries for a particular month. If year is not set, then the current year is assumed. This option only works if display is set to "list" or "calendar". (optional)

year >> Display entries for a particular year. This option only works if display is set to "list" or "calendar". (optional) limit Set to the maximum number of events to display. This option only works if display is set to "list", "pastlist" or "upcominglist". (optional)

first_day_of_week >> Set to the first day of the week as a number between 0 and 6 (0 = Sunday). Default is 1 (Monday). This option only works if display is set to "calendar". (optional)

summaries >> Set to 1 to display the summary information or 0 to not display it in calendar mode. Default is 1. (optional)

detail >> Set to 1 to display the detail information or 0 to not display it in list mode. Default is 0. (optional)

table_id >> Id to set for this calendar or list. This is useful for applying CSS styling. Default is "calendar-<autogenerated id number>". (optional)

date_format >> Format to display the event's date (as used in strftime()). Default is "%d/%b/%Y". (optional)

use_session >> Use a session variable to store the current month of the calendar. Default is true. (optional)

compact_view >> Set to 1 to hide the navigation links. Helpful to show current month's events on the home page. Default is 0. (optional)

inline >> Set to 0 to set all of the event links to inlined mode (they will replace the page content). Default is 1. (optional)

reverse >> Set to true to display events in reverse chronological order. Applicable to list, pastlist and upcominglist displays. Default is false. (optional)

detailpage="pagealias" >> Page to display Calendar event details in. This can either be a page alias or an id. Used to allow details to be displayed in a different template from the summary. Default is current page. (optional)

columns >> Makes Calendar output only a subset of relevant events for allowing displaying in columns. Allowed values 1/2. Default is 1. Implemented for upcominglist and pastlist only. (optional)

columnstyle >> If columns=2 this parameter sets whether the order of events in columns should be organized horizontally (0) or vertically (1). Default is 1. (optional)

currentcolumn >> If columns=2 this indicated whether Calendar should display content of column 1 or 2. Allowed values 1/2. Default is 1. (optional)

dblisttemplate >> Which template (from the database) to use for list. (optional) For example, if you have a template named "blog-post-month-archive-list" then you can call calendar like this:{cms_module module="Calendar" display="list" reverse="true" dblisttemplate="blog-post-month-archive-list"}

dbupcominglisttemplate >> Which template (from the database) to use for list of past or upcoming events. (optional) For example, if you have a template named "blog-post-list-with-content" and you want to show the latest 50 posts in the "General" category, then you can call calendar like this: {cms_module module="Calendar" display="pastlist" category="General" dbupcominglisttemplate="blog-post-list-with-content" limit="50"}

Templates

All four types of display used on the front end are controlled from templates that can be changed in the admin. If you want to reset a template back to the default, then delete the entire template content in the admin and it will be reset on the next display of that calendar view on the front end site.

Custom Fields

It is possible to define a number of custom fields to associate with each event using the Fields tab in the admin. Once one or more fields has been defined the values of that field for each event can be set using the events tab in the admin. These field values can be rendered using a template using the syntax event.fields.fieldname. Hint - insert {debug} into your template see all the data passed to the template.

Sample CSS Styles

An example of CSS rules to make the calendar view look good has been added to your stylesheet list. To see in action use:

{cms_module module='Calendar' table_id='big'}

Examples

Example of allowing Comments on Calendar events

Install the Comments module and put this in your Calendar "Event Template":

{cms_module module='comments' modulename='Calendar' pageid=$event.event_id} Parameters

   * (optional) lang="en_US" - Parameter is used to specify what language to use for display on the frontend. Not all modules support or need this.

Importing From CSV

When importing from CSV, the import wizard will show you that you will have to ensure that the columns are of the following format:

Start Time MM-DD-YYYY - hh:mm, End Time MM-DD-YYYY - hh:mm, Title, Summary, Description, Category

This is NOT correct.

The correct format should be:

YYYY-MM-DD hh:mm, YYYY-MM-DD hh:mm, Title, Summary, Description, Category

where the first column is the start date/time and the second column is the end date/time.

Here is an example line from a CSV file which is proven to work with the importer:

"2009-03-20 11:44","2009-03-20 11:44","Spring Equinox","Spring begins in the Northern Hemisphere of Earth.","Times listed are Universal Time (GMT).",

Also, note that the first line of the CSV file should be actual event data. It should not contain text labels describing the columns, as some CSV files do.

Declined month names

Some languages use declination of month names. For example, in Czech, name for january is "leden", but if we want to say, that something occured on that day, we use e.g. "1. ledna". Calendar module isn't prepared for such possibility by default. It can be adjusted in few steps:

1. Open file calendar.module.php
2. Look for function GetMonthNames()
3. Select entire function and copy it directly below
4. Perform changes to create your new function for declined names. This is example for january:

   function GetDeclinedMonthNames(){
   $declined_month_names[1] = $this->Lang('cal_january_declined');
   $declined_month_names["01"] = $this->Lang('cal_january_declined');
   return $declined_month_names;
   }

5. Open file function.display*.php (select file for display type, in which you want to use declination; in my case, I use it for function.displayevent.php)
6. Look for: $month_names = $module->GetMonthNames();
7. Copy it directly below. Cange the copy to: $declined_month_names = $module->GetDeclinedMonthNames();
8. Look for: $module->smarty->assign_by_ref('month_names', $month_names);
9. Copy it directly below. Change the copy to: $module->smarty->assign_by_ref('declined_month_names', $declined_month_names);
10. Open template in which you want to perform changes and replace every $month_names to $declined_month_names
11. Add translations. Use the names, that you used in calendar.module.php. Example: If you used $declined_month_names["01"] = $this->Lang('cal_january_declined');, then use cal_january_declined as key of $lang variable.
12. It should be done. Check it. If you have problems, please ask in forum or send me PM (my nick is Milhaus).
13. Lastly, don't forget to backup your changes, because they will be overwritten by any update. You have to perform them over and over again.

back to Modules

This page in: English - Deutsch - Español - Français - Italiano - Lietuvių - Nederlands - Norsk - Polski - Česky - Русский - Svenska - Tiếng Việt - عربي - 日本語 简体中文

User Handbook/Admin Panel/Content/Calendar

From CMSMS