CUSTOM.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)

Notes on customizing CalendarX 0.4 branch. (also 0.6 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+
