Event Calendar Admin's Manual

4. Managing Categories

4.4. Displaying Categories

In this section we'll see how to control the way Categories and Category Groups are displayed in your calendar interface.

1. Categories

Categories are displayed in Calendar Views and Event Views.

Calendar Views

The way categories are displayed in Month, Week or Day views is identical:
The Categories from the first Category Group are displayed with a colored background while the categories in other groups are displayed with their icon. See the note under Choose Category Group To Edit.
They are inserted into the rendered page via macro calls in the corresponding itemTemplate (see Month View, Week View and Day View for more informations about these templates).
The macro calls are identical in these three templates (as usual, they're in the form ):

eventFirstCategoryColor
This will be replaced with the category color of the category, from the first category group, attached to the event.

eventFirstCategoryTextColor
This will be replaced with the category text color of the category, from the first category group, attached to the event.

eventFirstCategoryName
This will be replaced with the name of the category, from the first category group, attached to the event. Use it if you want to display the name of the category (it's not used by default).

eventCategoryIcons
This will be replaced with the icons of all the categories attached to the event (you can limit the maximum number of icons from the "Max. number of Category Icons" property of the corresponding view in the calendar's property editor.

Event Views

Categories are displayed in the Event Viewer, via the  macro call. Each Category Group has a line, where is displayed the name of the Category Group, the icon, and the name of each Category in that group.
Categories aren't displayed on their own in the Event Editor, but they'll appear in their Category Group list box or popup menu.

2. Category Groups
Category Groups are displayed in the Event Editor and in the Filters Box.

Event Editor
The Event Editor is the screen where you create/edit/delete an event (see the User's Manual).
To be usable, your Category Groups must be in this screen. They're inserted into the screen via a couple of macro calls, so if you create more category groups in your calendar, you'll have to add macro calls in there for them too.
The template that controls the Event Editor is in your calendar's properties page.
If you're in the Categories Editor or in the Category Groups Editor, click on the link that reads "Back to page properties". Else, go to:
"/yourSite/admin/conversations/yourSite/structure$path=yourSite%2FyourCalendar"
Scroll the window down until you find the section "6. Event View". The Event Editor's template, is the second one, entitled "Template for creating/editing events". This template beeing pretty long, you may prefer to edit it in a text editor that doesn't force the text to wrap. Just use copy/paste to do so.
Here's the part of a template that inserts the Category Groups into the Event Editor (it's identical to the default template, except for the second category group which has a "All" item):
	<tr>
		<td valign='middle' align='left'>
			<hr>
			<table border='0' cellpadding='3' cellspacing='0' width='100%'>
				<tr>
					<td valign='top' align='left'>
						<span class='eventDlogText'>
							:
						</span>
					</td>
					<td valign='top' align='left' width='1'>
						
					</td>
					<td valign='top' align='right' width='20%'>
						<span class='eventDlogText'>
							:
						</span>
					</td>
					<td valign='top' align='right'>
						
					</td>
				</tr>
			</table>
		</td>
	</tr>
And here's the rendered result:

As you can see, the eventCategoryName macro returns the category name, and the eventCategorySelector macro returns a form element, popup menu or list box.
eventCategoryName
This macro takes one parameter, "groupId". This is the unique identifier of a Category Group (see the note under Choose Category Group To Edit for more info about this). This parameter is required.
eventCategorySelector
This macro as seven possible parameters.

groupId
the id of the category group
optional if groupName is provided

groupName
the name of the category group
optional if groupId is provided

size
optional defaulting to 1
the size attribute of the select element:
1 will make a popup menu - single selection
greater than 1 will make a listbox with n rows (where n is the passed size) - multi-selection

flAny
(addAny is supported too for backward compatibility but you'd better avoid using it)
Display "Any" item?
May be set to "true", "false", "1" or "0"
Defaults to false

flAll
Add a "All" item?
May be set to "true", "false", "1" or "0"
Defaults to false

flNone
Display "None" category?
May be set to "true", "false", "1" or "0"
Defaults to true

default
Category to use as default (if no value provided)
May be set to a categoryId, or to "all" or "any"

Note that most of these parameters are optionals, and should be used in particular circumstances. For example, you wouldn't use flAny in the Event Editor because it wouldn't make any sense to set an event's category to "Any". On the other hand, it makes sense to display the "Any" item in the Filters Box, where it would be useful to search events without looking at their categories.
flAll adds a "All" item in the Category Group form. You can use it in both the Event Editor and the Filters Box, but you may not need it. This allows to give all the categories in a group at once (except "none") to an event (in the Event Editor), or to search for events with all the categories (but "none") in a group (from the Filters Box).
flNone defaults to true, so you won't generaly use it. But it can be useful to set it to false in the Event Editors, preventing the "none" item from appearing, if you want to force your users to choose a category.
default allows you to select which item will be selected by default (as longer as no item is selected because of the recorded setting, of course). This allows you to define the default categories in the Event Editor that will be used when a new event is created. You can set it to the categoryId of any category (see Managing Categories, to "any" or to "all" (if you use the "All" item).
IMPORTANT
If you look at the bottom of the Events Editor's template, you'll see a form whose every element is hidden. Here's an excerpt of the default template:
<span id='eventDlogSubpanel' class='eventDlogSubpanelClass'>
	
		<input type='hidden' name='eventId' value=''>
		<input type='hidden' name='msgNum' value=''>
		<input type='hidden' name='c_1'> 
		<input type='hidden' name='c_2'> 
		<input type='hidden' name='eventSubject'>
		<input type='hidden' name='eventBody'>
This hidden form is used to collect the data from every panels of the dialog, whatever the panel from which the user submits the request. There's a different form for each panel, and the data from these forms is collected by a Javascript script, put into the hidden form, and that's the hidden form which is actually submitted.
When you add or remove a category group from the Event Editor, you'll have to add or remove the corresponding hidden element. These hidden elements must be named on the model: "c_N" where N is the Category Group ID without its leading zeros (for example "c_1" for the Category Group whose ID is "0000001" or "c_27" for the Category Group whose ID is "0000027". The two hidden elements corresponding to the category groups in the code above are indicated with the  comments.
Filters Box

The Filters Box allows the users of a calendar to filter the events displayed in the calendar views depending on their categories. See the User's Manual for more info about this (from the user's point of view).
We've already seen the Filters Box's template and the macros it uses in the section 3.7. Filters Box, and the additional information given in the section above apply too.
Up to Table of Content. Previous Page Next Page

View in DG