CUSTOM.txt CalendarX 0.5.3(dev) March 26 2005 (last modified for CalendarX 0.5.3) by +lupa+ (lupaz on sf.net, lupa at zurven dot com) Released under the GPL (see LICENSE.txt) Notes on customizing CalendarX 0.5 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 nine property sheets (named CX_props_yadayada). Click on one of the Property Sheets. Then click the Customize button (to make this into a folder with properties that you can adjust) and start changing the properties. In brief: CX_props_calendar: controls most basic calendar functionality, how the Subject bar is displayed, etc. CX_props_eventstoallow: what events to allow on the calendar CX_props_eventstorestrict: what events to restrict from the calendar 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. 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. 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. You should like it too. 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 may 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. 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. The default installation in the 0.5 branch now sets the right_slots property to empty, and in the left_slots property it adds a line for the portlet_cx_choices... this provides all the controls formerly shown in the top of the calendar, like Public/Private events link, Subject category selection, etc. THIS IS AN OPTION. You can go back to the 0.4 branch method by emptying (or modifying) the slots on your CalendarX instance, and setting the new calendarOptionsMacro property in the CX_props_calendar property sheet to a string value of "subjectlinks" (this will display the old-style subject bar in the head of the calendar views). The default right now is to show "subjectlinks0", which shows nothing in the subjectlinks area, because all those controls are now in the portlet. Read the /docs for all the new properties of the subjectlinks macros available. Make up a new one and send me the code for it to include in future releases. 2. The calendar uses categories based on the default Event Subjects. Currently these are Appointment, 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 is only semi-automatic. If you want CalendarX to choose Subjects based on all the Subjects available, see the instructions in CX_props_eventstoallow_text.txt So, find the CX_props_eventstoallow 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, now 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. Now 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 calendars as you like, even one per member or more. Overall, if you DO customize property sheets and the like for your calendar, we recommend putting the customized version INSIDE your CalendarX instance folder. It's just neater that way, and a very tiny bit faster. 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_eventstoallow and CX_props_eventstorestrict properties. 5a. Subjects to allow. 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 Types to allow. 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. Paths to allow. 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. 5d. Many more. Read everything in CX_props_eventstoallow_text.txt and CX_props_eventstorestrict_text.txt. Many properties to adjust to control which events are shown to whom. 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. You can select what review_state for events you allow on the calendar. The default is "published" but you can add "visible" and custom review_states as well. 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: CalendarX gives you several ways to show a link that allows users to click on it and go to an appropriate folder where they can add a new Event... in the Subject Bar, in the control Portlet, or in each of the calendar cells for every view. 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. NOTE: Add New Event links also show up as plus signs (+) in the calendar cells, and send the specified date and time to the newly created Event. However, as of 0.5.3 this does NOT work properly with portal_factory... the proper date and time parameters are not picked up by the temporary event. By default in 0.5.3 the portal_factory is bypassed so that the parameters are properly passed along. There is an easy one-line change in the script called cxCreateEvent in the CalendarX skins folder that will allow you to use portal_factory despite this lack of passed parameters, and it is documented in the code in that script. This is a priority for fixing in a future release of CalendarX. 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 has been extensively modified in the 0.5 branch for speed optimization. The process isn't over now, but the calendar runs faster than the 0.4 branch by a significant margin, despite doing far more in the querying department. There's not much more you can do. Speed Tip: 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. Other speed tips from previous versions are now obsolete and will have no effect on speed in CalendarX. 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 might, but don't count on it. +lupa+