CX_props_calendar_text.txt CalendarX 0.6.6(stable) January 03 2006 (last modified for CalendarX 0.6.5) by +lupa+ (lupaz on sf.net, lupa at zurven dot com) Released under the GPL (see LICENSE.txt) Instructions for properties in CX_props_calendar. New attributes added in 0.6.x branch releases showPrivateEventsToGroupMembers (0.6.0) useHalfHours (0.6.2) numMonthsForMultiMonthView (0.6.2) earlyDayEventHour (0.6.4) Use the Properties tab to adjust the attributes of the calendar as available. === List of Attributes === title string Leave this title attribute alone. dayOfWeekToStart int Value indicates what day of the week the Month and Week views begin on. Sunday = 0, Monday = 1, etc. defaultView string Name of the default view to be displayed: month, weekbyday, weekbyhour, or day. useAdvancedQuery boolean If checked, CalendarX will use the AdvancedQuery product for making queries to the catalog to find events. Use this if you want to override those query methods in your skin folder. I find AdvancedQuery significantly easier to use in building complex queries, but it offers no other advantages for general use in CalendarX. dayViewStartHour string Hour of day for CalendarX to BEGIN display for day view and for weekbyhour view. 8 = 8am = 08:00, 20 = 6pm = 20:00. For a 24 hour calendar, set this to 0 (zero). dayViewEndHour string Hour of day for CalendarX to END display for day view and for weekbyhour view. 8 = 8am = 08:00, 20 = 6pm = 20:00. Must be later than dayViewStartHour. For a 24 hour calendar, set this to 24. earlyDayEventHour string Hour of day for CalendarX to use for deciding between events being classed as "later" or "earlier" in the Day and Weekbyhour views. Previous behavior was that events up to midnight showed as "later" events and "earlier" events from midnight to dayViewStartHour showed up as "continuing". This property is the hour that now serves as the boundary between these types of events. Default value is 0, representing 12 midnight, meaning there are no "later" events. Setting value to 3, will represent 3am. Seems a reasonable boundary to me, meaning that events running 1am-2am will show up on the previous day, say Saturday night instead of Sunday morning. Use Case: Calendar of events for a city where there are commonly late night movies or concerts after midnight... consider Las Vegas, for example. Now you can set the boundary to be 3 or 4am, so that when viewing the Day view for Friday, the later events as late as 3am on Saturday morning will show up on the Friday view. Limitations: ONLY applies to Day and WeekByHour views, not to other views. Therefore this could create some confusion among viewers who see a late night event on Saturday night on the Day view, but finding that same event displayed on Sunday on the month view. A fully consistent fix is for this situation is difficult, and I'm unwilling to program it at this time. I tried, and hence the long delay between the 0.6.4 and 0.6.5 releases. Instead I'm leaving it at this for now. hoursDisplay string Code to tell the "hoursdisplay" macro how to display the hours in your calendar views. Currently two possibilities and they only affect the left column display of hours: "12ampm" = 12 hour display, with am or pm. Ex. 6 pm "24.00" = 24 hour display, with period. Ex. 20.00 useHalfHours boolean If checked, CalendarX will display half-hour increments on the day and weekbyhour views instead of the default one-hour increments. There remains NO capability of starting the day on the half-hour... the dayViewStartHour and dayViewEndHour settings must be integer hour values. The default value is blank (false), meaning Hourly periods will be used. There is a modest performance penalty associated with this option, use at your discretion. numMonthsForMultiMonthView string How many months to display in the month view. Default value is 1, but may be extended up to 12 months. Next buttons move forward by one month, not by the number of months in the view. Querying time to generate several months at once may be excessive if many events are to be shown. A future TODO might be to allow the user a widget to select the number of months on-the-fly. However, this will necessitate changes in managing the URL querystring to accommodate this new parameter. At present, this feature is left as an exercise for the gentle reader. showHeaderTitleAndIcons boolean If checked, CalendarX will display the calendar title and description and email/print/favorites Action icons as it does for other Plone content. showHighlightFullEvent boolean If checked, CalendarX will show the full extent of Events on the calendar, even without rolling over with the mouse. Default is a blue color, can be changed in CSS property sheet. NOTE! If you use this, you might also want to disable the labelEventsOnlyAtStart property. Disabling labelEventsOnlyAtStart means that the events in the Month view that span several days will show labels for each of those days, instead of only on the first day of the event. showJumpToDateWidget boolean If checked, a date-picking widget will show up at the top and bottom of the calendar near the Next/Previous links. This widget lets users pick a date and jump to it, instead of using multiple Next, Next, Next click, or manually typing the date into the URL querystring. NOTE: this widget has been removed from the bottom of each of the views, where it has been for many months, in order to avoid a viewing Bug in IE6. It can be returned by changing the macro call at the bottom of each of the view templates from "prevnextcurrentlinks_nojump" to the previous "prevnextcurrentlinks" macro. useNumericMonthInJumpToDateWidget boolean If checked, the Jump-To-Date widget will show a numeric month value (ex. "2") instead of an abbreviation of the month (ex. "Feb"). These abbreviations are pulled from the python DateTime module, not coded into CalendarX code, in the getMonthName.py script. showPublicPrivateLink boolean If checked, the *Public* vs *My Events* link will be shown in the Subject Bar. This link allows users to switch between viewing all the published events, or ONLY their own private events. If your calendar is mainly for viewing by anonymous users, you probably don't need this. Default is OFF because this is a nice feature, but not a commonly chosen one. useMultiSubjects boolean If checked, the Subject category picker is a checkbox-style form, allowing users to select multiple subjects for viewing. If unchecked, it switches to (an older) single subject chooser that only allows one Subject category at a time. Default is ON for this new-style Multi-Subject chooser, because it is ever so much nicer. showSubjectBar boolean If checked, the Subject bar is shown, and if unchecked, it will disappear from view. Default is ON. Decomplicates the calendar if you don't want to use Public/Private or Subject categories. useCalendarHelp boolean Check this attribute to show a View tab for "Calendar Help". This brings up a new view page that is intended for you to use for help in case you have neophyte users who could use some calendar help. I've added some code that brings up one page of help for "Members" and a different page of help for "Anonymous" users. This could easily be extended to show different help screens for other Roles. See the "help" view page template for more information. The help text is quite minimal, so feel free to expand it for your users. Feel free to send me a copy of your nice help files, too! includeReviewStateVisible boolean Check this attribute to include events where the review state is 'visible' as well as 'published'. This is useful for calendars where the only users are trusted users and going through the publishing workflow only adds unnecessary complication. In particular, this could work well even on a site with many untrusted users. In that case, create a calendar for the trusted users that uses a repurposed Event with a new portal_type name. Use the 'restrictToThisListOfTypes' attribute to make this new calendar ONLY read this one type of Event. Then use a getNotAddableTypes.py script to restrict the use of this type of Event to your trusted users (as a role, or a group, or whatever). See the HowTo on plone.org for use of getNotAddableTypes. showPendingLink boolean Check this attribute to show a link in the subjectbar that, when clicked, tells the calendar to display events with "pending" state as well as the other events (published, and visible if includeReviewStateVisible has been selected). The link is not a toggle; to get out of the mode where the pending events are showing, simply click any other link on the calendar. This link ONLY shows up for Calendar Managers. Who is a Calendar Manager? User status as a Calendar Manager is determined by the isCalendarManager.py script. It is easily customized, but as a default is set to allow users with the "Manager" role. If this role is adequate for you, leave this script as is. An example is included in the script to show how to look up group membership to determine Calendar Manager status. showPrivateEventsToGroupMembers boolean Check this attribute to allow PRIVATE events to show up to anyone with the Plone privilege of viewing your PRIVATE events. In short, what this does is allow you to give one of your Groups or some other user a proxy ownership role for one of your review_status=Private events. That is enough to allow them to see it in Plone. But this attribute must be TRUE (checked) if you want such events to show up on a CalendarX instance. For a fuller explanation, what this does is change the standard query to allow searching for review_state "private" events as well as "published" and "visible" (if includeReviewStateVisible is checked). But they will ONLY be shown for those users (or group members) where they have expressly been given the right to do so, usually via use of the Sharing tab on the event. So to use this, we recommend the following: 1. Use a recent version of GRUF (GroupUserFolder) in your Plone (version 3.0 or higher, not the 2.x that comes with Plone 2.0.x). 2. Make a group and enter your event in the group folder (usually something like /groups/mygroup/myevent. 3. Make the event a "private" event (instead of submitting it for review for publishing. 4. Use the sharing tab, and give the group proxy ownership of the event. Now, with the use of this attribute, your group members can have a calendar that shows group-only events. showOnlyEventsInMonth boolean Check this attribute to restrict the Month view to display events ONLY in the current calendar month, and NOT those events that occur in the days before or after the month begins and ends (ie., if the month view shows the 30th and 31st of the previous month on the calendar, events will NOT be displayed for those dates. labelEventsOnlyAtStart boolean Check this attribute to put labels on the month view ONLY on the first day of an event that lasts multiple days. Default is SELECTED. Unselect this attribute if you'd like the event title and datestring to appear on each calendar day that the event is on (ie., a four day event will have the label show up on the calendar four times, on each of the four days of the event). NOTE! Disabling this (to show events on EVERY day) will only work if the showHighlightFullEvent property is turned ON (selected). It would make no sense (to me) to have the event labeled, but not highlighted. So make sure you use these together. No harm if you don't, but it won't behave the way you might have expected. It pays to read the documentation. listOfSubjects lines restrictToThisListOfSubjects boolean Together, these two attributes allow you to control the choice of what categories of events to display on your calendar. List of the Subjects in your CalendarX, for use in creating the macro that displays them on your calendar. 1. LEAVE "listOfSubjects" BLANK, if you want to just use the list of Subjects that is available from already created Events your Plone site. 2. LIST SUBJECTS ONE PER LINE, exactly as they are present in your portal_metadata, in the order you want them displayed. The default values included here are the default values that come with CMF Event and AT Event types. If "restrictToThisListOfSubjects" is checked, a query for "ALL" subjects is restricted to the Subjects in your listOfSubjects attribute. If unchecked, "ALL" will return all events found, regardless of their Subject. Use of this feature allows you to segregate certain events pertaining to certain Subjects to unique calendarx instances. This also means that if checked, the calendar WILL NOT pick up events that do not have a Subject selected. ADVANCED FEATURE: Each line in the listOfSubjects can also be a Comma-Separated-Values list (CSV) where each line becomes a list of subjects for viewing. This becomes very useful in the case where you have many Subjects, but would like to combine several of them at a time and use a Nickname (or abbreviation, or acronym) to show up in the Subject menu. For example: In a calendar for a school with five grade levels, and four classes of children in each grade level, you could try something like this in your listOfSubjects: Class1a,Class1b,Class1c,Class1d Class2a,Class2b,Class2c,Class2d Class3a,Class3b,Class3c,Class3d Class4a,Class4b,Class4c,Class4d Class5a,Class5b,Class5c,Class5d and then use this in the listOfSubjectTitles below: Class 1 Class 2 Class 3 Class 4 Class 5 In this way, your subject menu is less cluttered, but it is easy for your users to check one of these to filter and see only the events for children of Class 1 age. You may also want to use SubCalendars with this, so that users can drill all the way down and see ONLY events associated with Class1c, Class4b, etc. eventTypes list restrictToThisListOfTypes boolean Together, these two allow you to restrict what types of content objects will be picked up on your calendar. Put one portal_type per line in the eventTypes attribute, and check "restrictToThisListOfTypes" if you wish this feature to be activated. If unchecked, no check is done on the Type index, regardless of the content of the eventTypes attribute. Usage: For example, this feature means you can create a new Event type for certain users, and then use getNotAddableTypes.py to restrict which users can add those special Event types, which gives even more control over different calendar instances in your Plone site. This is very useful in subcalendars, where each subcalendar may have a different event Type. listOfPaths list restrictToThisListOfPaths boolean Together, these two allow you to restrict where (the paths) to event content objects that will be picked up on your calendar. This means you can restrict viewing to Events found in certain folders. To use this feature, use a full path exactly as found in your path index. An example: /clients/companyplonesite/Members/fred /clients/companyplonesite/staff These two paths represent folders where Events can be stored that will show up on the calendar, if restrictToThisListOfPaths is checked. ONLY those events in these two paths will be found. Events in fred's personal folder and events in the staff folder, and any folders deeper than that will be picked up for display on this calendar. For example, if there is a meetings folder inside the staff folder, events inside that folder will also be displayed. If you are having any trouble with this property, please go to the portal_catalog, click on the Catalog tab, and find one of the events that *should* show up on the calendar. Look near the bottom of the page to see what path is being indexed by the "path" index, and use that as the path to the folder that you will use in listOfPaths. restrictToThisFolder boolean This property restricts the calendar so that events are ONLY shown if they are found within or beneath the parent folder of the CalendarX instance. Example: add a CalendarX instance as /Members/lupa/cal. If you set this property to true, then only events found within /Members/lupa and any subfolders therein will be shown on this calendar instance. This could also be accomplished manually with the restrictToThisListOfPaths property, but this property helps in the special case where you want to allow your users to create a private calendar for their own area. In that case, you should probably set this property to "1" in the property sheet on the filesystem, so that all calendars created by your users will have this property by default. ADVANCED NOTE: as currently implemented, the restrictToThisFolder option trumps (overrides) the similar restrictToThisListOfPaths property. In other words, in the four query scripts, the restrictToThisListOfPaths property is evaluated first, and if restrictToThisFolder is also selected, the second one (restrictToThisFolder) takes precedence and overrides the first property. To change this precedence, simply go into these query scripts and rearrange the two-line calls for each one so that their order is reversed. listOfSubjectTitles list useSubjectTitles boolean Together, these two attributes allow you to use sensible (e.g., shorter) titles on the Subject Bar for your Subject categories. If your Subject category names are long, three or four subjects can produce an unwieldy list for your users to select from. Instead, use these attributes to include a list of shorter titles for each of your Subjects. *IMPORTANT* Be sure to use this feature in conjunction with the "listOfSubjects" attribute above. Be certain that both lists have the exact same number of entries, so that there is a single corresponding SubjectTitle for each Subject. If these do not match, the calendar may show an error. Simply test your calendar after any changes to this attribute to be certain that your calendar is working without error.