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.



