CUSTOM.txt
  CalendarX 0.9.2(stable)  October 19 2009
  (last modified for CalendarX 0.9.2)
by +lupa+ (lupaz on sf.net, lupa at zurven dot com)
Released under the GPL (see LICENSE.txt)


-I.  Very Brief Notes for customizing CalendarX 0.9 branch (added Oct 2009)

Go to the "manage" tab of your calendar instance, when logged in as admin.
Use the various tabs to set the options for your calendar.  For example, when
you first start CalendarX it may not show the events because your workflow
uses different review states than what may be standard.  Click to the
"manage" tab of the CalendarX instance, use the dropdown to select the
"Calendar options", scroll down to the "List of review states to be
displayed" option, and fill out a list of review states, one per line, to
reflect your Plone site.  Some possibilities: 'published', 'pending',
'private', 'internal', 'external', 'internally_published', etc.

Read the other options to manage the look and feel and behavior of your
CalendarX instance.  Most of the configurations are the same as they were
in the 0.6 branch documentation, it's just that you can find them here now
instead of in property sheets (nice change).


THE REST IS FAIRLY OUT OF DATE for 0.9.0+  There is useful information
here, but to some extent there is misinformation.  The descriptions of
properties (attributes) is largely fine and accurate, but everything
about property sheets is old, gone, kaput... all the attributes are
now in Archetypes schemata now.  YOU HAVE BEEN WARNED.



Notes on customizing CalendarX 0.6 branch (and 0.4 branch).

I.  Quick Overview.
II.  Tips.
III.  Future.
IV.  Caveats.

I.  Quick Overview of customizing CalendarX.

FIRST:  Make sure you have followed ALL the instructions found in INSTALL.txt.
  CalendarX puts the "ALL" in "INSTALL".(tm)

A. Go to portal_skins/CalendarX.  Find one of the seven property sheets (named
   CX_props_yadayada).  Click on one of them to view it, and then click the
   "Customize" button to move a copy of the property sheet into the /custom
   folder.  Now you can modify the properties (use the Properties tab!) and
   start changing the calendar behavior.  In brief:

     CX_props_calendar: controls most basic calendar functionality, including
       what types of events are shown, how the Subject bar is displayed, etc.
     CX_props_css: provides many opportunities for changing the colors and
       fonts displayed in the calendar.
     CX_props_custom: does nothing.  If you add new functionality to your
       calendar and need properties, put them in here.
     CX_props_popup: checkboxes to select which text is displayed in the
       rollover text box associated with each event displayed in the calendar.
     CX_props_addeventlink: If you wish to have an "Add New Event" link
       displayed in the subject bar, configure the link here.
     CX_props_subcalendar: If you have subcalendars beneath your main calendar,
       you will need to configure them here.
     CX_props_eventdisplays: allows you to use different icons and CSS classes
       based on the Subject of each event.

  Almost definitely, you will want to customize CX_props_calendar.  It has many
  basic options for the calendar.

  TIP: In some Plone installs, I've run into the situation where the customized
  property sheets were being ignored by the skins mechanism.  Couldn't find any
  good reason for it, even though they were located in the /portal_skins/custom
  folder as usual.
  SOLUTION: Cut and paste your customized property sheets into your CalendarX
  instance folder, using the ZMI to do this.  So if your calendar is named
  "cal", in the ZMI this will be a folder... put the property sheets inside
  there, and the Zope acquisition mechanism will pick them up without using
  the skinning mechanism.

B. You can customize anything else in the /CalendarX folder. Page templates,
   macros, CSS or Python scripts, or Javascript... anything you find there.
   Usually this means clicking the "Customize" button which puts a copy of the
   object in the /custom folder for you, where you can change things and
   refresh your calendar to see the results.  TIP: see tip in #A above.

C. To create more than one instance of CalendarX is easy... just add another
   one from the dropdown list.  However, all your calendars will use the same
   properties from the /portal_skins/custom or /portal_skins/CalendarX folders.

   To make each calendar different:
   IN ZMI:  CUT all the customized objects that you need from the
     /portal_skins/custom folder, and PASTE them into your CalendarX folder.
     Now your calendar can be customized locally and independently from any
     other calendars.  I like to use this approach anyway, even if I'm only
     using ONE CalendarX instance in my Plone site, because it cleans up the
     /custom folder for other uses.

D. If you want to use Subcalendars, move your customized objects out
   of the /portal_skins/custom folder and put them directly into your
   /calendar folder (using the ZMI).  You will need a copy of
   CX_props_subcalendar in each of your MAIN and SUBcalendar folders... and you
   will very very likely need CX_props_calendar in each of them as well.
   There's a detailed section later in the manual that provides an example of
   using Subcalendars.

E. READ UP.
   Also read everything you find in the /docs folder of the CalendarX product
   distribution or in the Manual.  And read the source code in the Python
   scripts.  We've added quite a bit of commentary to most of the Python
   scripts to make it all much more understandable, and more readily
   customizable.



II.  Tips.
1.  Slots/Portlets.  For most users, we recommend disabling the slots on your
    calendar folder, or more specifically, making the slots be empty.  If you
    want portlets appearing in the slots, click on the Properties tab of your
    calendar folder in the ZMI.   Add your portlets into left_slots and
    right_slots attributes, just like you would in your main Plone site.

2. The calendar uses categories based on the default Event Subjects.
    Currently these are Apppointment, Convention, Meeting, Work, Social Event.
    You can change these in the portal_metadata/Elements/Subject.  If you do
    this, CalendarX needs to be told about it... this will be fixed in a
    future version to be automatic.  Actually, it is now semi-automatic.  If
    you want CalendarX to choose Subjects based on all the Subjects available,
    see the instructions in CX_props_calendar_text.txt

    So, find the CX_props_calendar sheet, and list the Subjects line by line
    in the "listOfSubjects" attribute, just like you made them in
    portal_metadata.  And then you're done.

    Actually, there's more.  If you have used very LONG subject names,
    like "French Connection United Kingdom", there is an option to create
    shorter "nicknames" for each of your subjects, and show them at the top of
    the calendar instead of the LONG names.  For example, you could use
    the much shorter "FCUK" instead of the long, full name of the Subject
    used in the earlier example.

    And now there's even more!  You can make groupings of subjects, using the
    nicknames approach.  First, in the 'listOfSubjects' attribute, list your
    subject groupings with commas like this:
      Mrs Wilson 3rd Grade,Mr Smith 3rd Grade
      Mrs Farber 4th Grade,Mrs Jasper 4th Grade
      Mr Spinky 5th Grade,Mr Zurven 5th Grade
      Field Hockey,Jump Rope,Basketball,Soccer,Chess Club

    Then in the 'listOfSubjectTitles' attribute, put the nicknames in that
    will be shown in the Subject Bar, like so:
      3rd Grade
      4th Grade
      5th Grade
      Sports

    Now when a user clicks 'Sports', events from all the sports listed in the
    corresponding listOfSubjects line will be returned in a calendar.  This is
    usually much preferred to listing all 11 Subjects in the Subject Bar of
    CalendarX.

    Also, this functionality makes subcalendar usage very powerful, as you
    will see if you keep reading this drivel.

3.  Basic: Access to your calendar for your visitors
    First, publish your /calendar folder from within Plone so that it becomes
    available on the portlet_navigation.  Or not, if you don't want it to
    show up there.

    Second, another nice hook is to create a portal_tab to go to your new
    calendar.
      A. In the ZMI, go to portal actions.
      B. Add a new action as follows:
         Name: Calendar
         Id:  calendar
         Action:  string:${portal_url}/calendar
         Condition:  (empty or whatever)
         Permission:  View
         Category:   portal_tabs
         Visible?   (checked)

    This will display your defaultView (whichever view you have selected in
    the defaultView property in CX_props_calendar).  Default is 'month'.

4.  Multiple Calendars.
    You can have multiple calendars on your site.  Place another CalendarX
    instance wherever you want the calendar to appear.  Chances are that if you
    have multiple calendars, each one will be configured differently.  In that
    case, simply customizing a property sheet won't be enough, because
    portal_skins/custom can't have two different property sheets both
    named the same thing.  SO... go into the ZMI and cut any CalendarX
    property sheets, scripts, icons or templates out of portal_skins/custom,
    and paste them directly into your CalendarX folder instance.  Now these
    customized sheets will ONLY be found by the desired calendar instance, and
    you can have as many

5.  Restricting events on your calendars.
    A common request is to restrict the types of events shown on a calendar.
    There are now several ways to do this without customizing the calendar views
    or macros, by using attributes in CX_props_calendar properties.

    5a.  Subject restrictions.
    If you want to display ONLY events that contain certain subjects, you can
    use the "restrictToThisListOfSubjects" attribute along with the
    "listOfSubjects" attribute.  Read the directions, and simply
    list the Subjects that you wish to show.  For example, this might be a way
    to have a Music Events calendar on your site, with multiple types of Music
    events, as well as an Arts Events calendar, with its own set of Arts
    event categories.

    5b.  Event Type restrictions.
    If you want to display ONLY events of a certain "portal_type", use the
    "restrictToThisListOfTypes" attribute along with the "listOfTypes"
    attribute.  A "portal_type" is the type of Plone object that you are using
    for your events.  For example, you can go to portal_types in the root of
    your Plone site, copy and paste the existing Event type, and modify it so
    that its type is a "Staff Event".  Then you can create a calendar that
    will ONLY show Staff Events, just for Staff usage.  A good idea is to add
    a getNotAddableTypes.py script in your site that will restrict usage of the
    "Staff Event" type to just members of your "Staff".  See howtos on the
    Plone.org website for more instructions on how to use getNotAddableTypes.

    5c.  Path restrictions.
    If you want to display ONLY events that are found within certain folders
    of your Plone site, you can use the "restrictToThisListOfPaths" attribute
    along with the "listOfPaths" attribute.  Read the directions, and simply
    list the full paths (as found in the Path index in the portal_catalog)
    for the folder objects you wish to use.  Then ONLY those events found within
    those folders will display on your calendar.

6.  Look at all the calendar properties, and read about them in the /docs
    folder.  There are lots of things you can adjust, and they're all
    documented. Try them and see what you like.

7.  There's an attribute in calendar properties that lets 'visible' as well
    as 'published' events show up on the calendar.

8.  Nearly all the most important CSS attributes are now adjustable from
    the CSS properties sheet.  Font sizes are all expressed in percentages
    so that they can vary the way the rest of Plone can, with simple stylesheet
    changes.

9.  "Add New Event" link:  A new addition to 0.4 branch is the ability to put
    a link in the Subject Bar that allows users to click on it and go to an
    appropriate folder where they can add a new Event.  There is a property
    sheet that controls this behavior (i.e., where the link goes and who gets
    to see the link at all).  In brief, the macro controlling this link first
    checks to see that the user is Authenticated on the site (few sites allow
    un-Authenticated users to add Events, and those who do can easily disable
    this in the macro code).  The link then can be set to the following
    possibilities:
      A. Link to the Member's personal folder.
      B. Link to a specified folder.
      C. Link for certain users to go to different folders (one specified
         folder per specified user).
      D. Link for users with specific Roles to go to different folders (one
         specified folder per specified Role).
      E. Link to a specified subfolder within the Member's folder.
    If choice C or D is selected, and the current users is not listed among
    the possible choices (for listed users or Roles), then the link will roll
    back to choice B or A, if either of these has been checked.  If the user
    is not found in C or D and neither B nor A has been checked, then the
    "Add New Event" link will NOT be displayed for this user.

10. New Icons and CSS classes, selected by Event Subject.  Now your calendar
    can really show its colors by letting you highlight each event on your
    calendar in color and with icons depending on the Subject.  Simply
    check the appropriate box and follow the examples, listing a single line
    for each of your Subjects that tells it what icon to use.  Add those icons
    to your /custom folder, or /calendar instance folder, and your calendar
    will take on a whole new look.  Read the details in the
    CX_props_eventdisplays.txt file in the /docs folder.  Or just check the
    box and try it with the icons included in the default settings.

    You'll also need to add special CSS classes for your subjects.  The
    default ones are in calendar.css... look at them to see how to do it for
    yourself.  There are currently two classes for each subject: one class for
    the link shown within the calendar proper, and one class for the Subject
    bar up at the top of the calendar page.

    Also: Icons and CSS by Event Type.  Same as above, but works for the
    specified Event types listed. Should come in handy for tricky subcalendars.

11. SPEED TIPS.  CalendarX is a busy product, doing lots of queries and lookups
    in order to display a full-featured calendar.  Here are two speed tips to
    make sure that CalendarX is running as fast as reasonable.  The first one
    is imperative, the second is definitely optional.  Neither have been
    rigorously benchmarked, but informal benchmarks give the first one a
    potential speed up of as much as five-fold (in Plone 2.0; this whole
    discussion is less critical for Plone 2.1.x).  SO DO #1, if it's not
    already done for you.  It's quite painless.


    Speed Tip #1: The skins of Plone create a performance hit to some extent.
    This tip speed up the calendar by putting it near the top of the skins
    list of layers.  Moving it up from the bottom of the skin layers list
    can increase speed severalfold.  Go to portal_skins in your Plone
    site, and click on the Properties tab.  Then find CalendarX in the listing
    for your plone skin (usually Plone Default or Plone Tableless) and move
    CalendarX up to the second spot, right underneath "custom".  That's it.
    Now your calendar skin will be found very quickly.

    Note: CalendarX tries to install up at the top below "custom" at
    installation.  So this is probably already done for you.  But if you
    install other products AFTER CalendarX, they may install ahead of
    CalendarX in your skins.  So you may need to go back and move CalendarX
    up in the layers at some future time.

    Speed Tip #2: Customize the query methods from /portal_skins/CalendarX
    folder and move them locally to the location of the calendar instance
    itself... no more skin-inefficiency, because they are found locally.  This
    should help, but I have no real benchmarks to prove it.  In order to
    really work, you should move virtually all the scripts and property sheets
    to your CalendarX instance.  This should definitely be faster than having
    your scripts all in the skin layers hierarchy, but probably not much of a
    boost over Speed Tip #1 and it is more work, so don't bother.

    I'll keep looking for other tips and speed ups.  I made some code changes
    in 0.6 branch to speed up the page renderings over the 0.4 branch.  The
    0.5 branch already contains most of these changes.  Also, Plone 2.1.x runs
    CalendarX faster than Plone 2.0, without bothering with these tweaks...
    these may help too, but do upgrade if you haven't already.



III.  Future.
1. Tips on creating a custom view.
   It is now easier than ever to make a custom view.  Much of the convoluted
   tal:  code has been removed from the view page templates and converted to
   python scripts.  More to come, but in short: make your view, give it a
   decent name, add some code for it among the various python scripts and in
   the macros that show the tabs for the views.  That's all ;-)



IV.  Caveats.

  We will release and archive all versions of CalendarX on Sourceforge, so that
  the community should always have access to the version of CalendarX that your
  skins were built for.  Correspondingly, you should keep the version of
  CalendarX that comes with your skins intact, or at least the numeric part
  (i.e., 0.2.4), for future reference.  If we get support for CalendarX
  development in the future, we will likely develop scripting methods for
  upgrading skins between releases, if that becomes necessary.  For now, it
  shouldn't take very long at all to upgrade any skins you create to
  future releases in the same branch.  A few minutes, actually, if you stick
  mainly to using the new property sheets and macro sheets.  Also, don't count
  on any future releases (beyond the 0.2 branch) being compatible with
  the earlier Plone 1.0.  They probably won't be.


+lupa+
