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+