INSTALL.txt CalendarX 0.5.3(dev) March 26 2005 (last modified for CalendarX 0.5.2) by +lupa+ (lupaz on sf.net, lupa at zurven dot com) Released under the GPL (see LICENSE.txt) New: portlet_calendarxp requires mods to ploneCustom.css. See section II-10. below. Note: CalendarX 0.5 branch is a Plone Product. It installs as a Product in your Products folder. The instructions below explain this. I. Software requirements II. Instructions for Installation for the first time. III. Documentation available. IV. Caveats. Old IV. Instructions for upgrading to new versions of CalendarX (MOVED these instructions to MIGRATE.txt) I. Software requirements Software Requirements for CalendarX (0.5 branch): 1. Plone 2.0+ along with Python/Zope. Tested on Plone 2.0.5, Zope 2.7.3. As of branch 0.5+, CalendarX no longer works on Plone 1.0.x. Software Options, Suggestions (NOT REQUIRED): 1. Python 2.2+ (required if AdvancedQuery is used.) 2. Zope 2.6.2+ (may work on earlier Zopes, but untested. Python 2.2+ is not standard until Zope 2.7+) 3. AdvancedQuery Product for Zope this is available at Dieter's site: http://www.dieter.handshake.de/pyprojects/zope/ AdvancedQuery is one of two query techniques used. By default, the traditional ZCatalog query method is used, but using AQ is simply a switch option in the CX_props_calendar property sheet. II. Instructions for Installation for the first time. 1. Make sure you have the required software and additional Zope Products in place. 2. Acquire the CalendarX-0.5.x.tar.gz file from sourceforge. This unzips as a tar file, which untars as a single folder, called CalendarX-0.5.x. 3. Place this folder in your INSTANCE_HOME/Products/ folder and rename it the folder to /Products/CalendarX instead of /Products/CalendarX-0.5.x. 4. Restart Zope. 5. IN PLONE: Go to plone_setup and Add New Products. Find CalendarX in the list and check it, and click the Install button. This is equivalent to navigating in the ZMI to your Plone instance, and using the portal_quickinstaller to install CalendarX. 6. IN PLONE: Navigate to where you want a CalendarX instance, and add a CalendarX in the normal fashion. Name it "calendar" or whatever you want. It creates an "empty" folder, but when you now navigate to it in Plone, it will display the Calendar, set to the default view (Month view). NOTE: CalendarX is *not* an ordinary Plone folder. The folder_listing and folder_contents have been disabled. Do NOT attempt to store Plone content inside your CalendarX instance. Certain advanced features of CalendarX require you to use this folderish behavior to store CalendarX scripts and other files within it (such as having multiple calendars on one site, and the use of subcalendars). See step #9 below for more information. 7. That's it. Navigate in Plone to your calendar folder and the default (month) view should appear. You may then publish (or not) your calendar as you wish. 8. To customize your CalendarX, go to portal_skins/CalendarX, and customize any of the files there (property sheets, scripts, page templates, etc.). For more information on customizing CalendarX, read the CUSTOM.txt file in the /docs folder, and each of the separate text documents that describe the attributes in each property sheet. NOTE: Using the /custom folder is fine, but the next note (#9) explains why you might not want to. 9. 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: Find and click on an object in /portal_skins/CalendarX that you want to customize (start with CX_props_calendar), hit the Customize button to make a copy of it in your /portal_skins/custom folder, then CUT/PASTE it out of /custom and into your new CalendarX instance, and then make your changes to this property sheet, or python script, or page template. Only the objects that you want to customize need be CUT/PASTED to your CalendarX instance. All the other ones needed will be acquired from the /portal_skins/CalendarX folder in a normal fashion. 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. 10. PORTLET_CALENDARX. There are now THREE portlets shipping with CalendarX. One is a controller portlet that moves the choices (selecting subjects, etc) off the calendar view and over into a slot on the side. The other two are portlets that can be used to replace the standard "portlet_calendar" that comes with Plone: portlet_calendarx, and portlet_calendarxp. Portlet 1. portlet_calendarx: A miniature CalendarX in a slot. This one is a little bit big for a regular side portlet, but should be good for custom work when you need a mini-calendar on your site. This portlet can be used on any page in your site the way that you might use portlet_calendar, except this one uses the configuration in a CalendarX instance to control which events are shown on your calendar. The event icons are shown, along with the normal popup descriptions. The month name links to the CalendarX instance that is controlling the portlet. To use it, there are two steps in the ZMI: A. Add the following line to your right_slots property (using the Properties tab) of your portal root (or any slot, anywhere in your Plone site): here/portlet_calendarx/macros/portlet Looks just like the line for the regular calendar portlet, but adds an x. B. Put a copy of portlet_calendarx in your /custom folder so that it can be found by your slots, and then change one line in the code so that it looks for a CalendarX instance (you MUST have a CalendarX instance installed somewhere on your site for this portlet to work). The line that says: PATH2CX string:/cal; should be changed to lead to the CalendarX instance on your site. So if you have a CalendarX instance called "calendar" located in a Plone Folder called "quepasa" that's located in your portal root, then your line should read: PATH2CX string:/quepasa/calendar; That's it. Now the portlet will show the same events that your CalendarX instance is showing. Porlet 2. portlet_calendarxp: Near CLONE of the original portlet_calendar. This portlet works great out of the box. The Just like portlet_calendarx, this portlet can be used on any page in your site the way that you might use portlet_calendar, except this one uses the configuration in a CalendarX instance to control which events are shown on your calendar. The event icons are shown, along with the normal popup descriptions. The month name links to the CalendarX instance that is controlling the portlet. Follow the same install structions for Portlet 1. IMPORTANT CSS INFO. At first, I had trouble getting this portlet to behave the same way the original portlet_calendar (Plone default) does. So, I made some changes in the ploneCustom.css code that helped. Later the problem seemed to disappear completely. Just in case you have problems, here are some CSS class mods that you can try in your ploneCustom.css file in your /custom folder in order to make this portlet work properly. I think you won't have to use it, but I include it here for completeness. You may not have to do this, but then again you might find it works. Try without, see how it looks, then try with these mods if desired: **** START OF ploneCustom.css MODS ***** .ploneCalendar a { text-decoration: none; color: &dtml-fontColor;; } .ploneCalendar a:hover { text-decoration: none; color: &dtml-fontColor;; } .ploneCalendar th .plain{ background-color: &dtml-globalBackgroundColor;; font-weight: normal; font-size: 6px; text-align: center; padding: 2px; } .ploneCalendar .weekdays td { background-color: &dtml-globalBackgroundColor;; border: &dtml-borderWidth; &dtml-borderStyle; &dtml-globalBorderColor;; border-style: &dtml-borderStyle; none; font-weight: normal; text-align: center; padding: 2px; } .ploneCalendar .noevent { font-weight: normal; } **** END OF ploneCustom.css MODS ***** Porlet 3. portlet_cx_choices: Controls subjects, etc for the main CalendarX instance. Comes pre-installed, but you can disable it by removing it from the slots and then changing the CX_props_calendar settings to call one of the alternative "subjectlinks" macros that will put all those controls back up on the header of the CalendarX instance. III. Documentation available: Contents of the CalendarX.0.5.x /docs folder: CREDITS.txt - some people who deserve our thanks. CUSTOM.txt - description of how to customize CalendarX with skins. CX_props_addeventlink_text.txt - how to control the Add New Event link CX_props_calendar_text.txt - instructions for the calendar properties CX_props_css_text.txt - instructions for the CSS properties CX_props_custom_text.txt - instructions for the Custom property sheet CX_props_eventdisplays_text.txt - use icons and css to control events CX_props_eventstoallow_text.txt - which events to allow in your calendar CX_props_eventstorestrict_text.txt - events/users to restrict from calx CX_props_popup_text.txt - controls on the rollover popup text block CX_props_subcalendar_text.txt - instructions for subcalendar properties HISTORY.txt - all the changes in this CalendarX branch so far. INSTALL.txt - this file, describing the installation. LICENSE.txt - brief synopsis licensing for CalendarX (GPL). LICENSE.GPL - a current copy of the General Public License. MIGRATE.txt - a quick how-to on migrating/upgrading CalendarX. OVERVIEW.txt - synopsis of what CalendarX is, and does. TODO.txt - some things to finish before this branch becomes (stable). VERSIONS.txt - explains version numbers used for CalendarX releases. and these two in the root CalendarX folder: README.txt - brief message identifying CalendarX. version.txt - version of CalendarX currently in use. IV. Caveats. 0. These caveats have been included here since the first releases of CalendarX and I've never had much excuse to need them. But here they are. 1. For your health, and mine, I've tried to document nearly everything you need to accomplish significant things with CalendarX. Please read all the documentation before you ask questions to the list or at CalendarX.org. There's lots of it, even to the point of explaining each configurable attribute in the property sheets. It is not, however, capable of explaining all the possible things you can do with CalendarX. Be creative, and share your successes and failures with us at CalendarX.org. 2. Part of the code for CalendarX at this point in time comes from the previous products it builds on -- mainly PloneCalendar (see the README). I know most of that code now, and have replaced large parts of it with my own. But I can't vouch for everything it does yet. Do with this product what you will, but use it responsibly. 3. At this point, I have no idea how CalendarX may interact with or interfere with any other Zope/Plone products or other software. There are likely to be name overlaps between objects in this code and those in other apps, and in a world with Spammish Acquisition, many things are possible. I have seen no bad such interactions, although one potential user claimed to be totally unable to import the Fezzik folder (on the 0.2 branch) no matter how he tried (a month later, this user wrote back and said there are no problems now with the most recent version). I think this must have been an interaction with this particular Plone setup, but I have no idea. I've tried it without any problems on several systems and operating systems, but I don't know what will happen on your site, because you may have customizations that do cause problems. Forewarned should be four armed, but you never know. In the meantime, do with this product what you will, and remember to use it responsibly. 4. This product has not been thoroughly tested and is likely to have bugs. In fact, it doesn't even have a unit test suite for it yet. You have been warned. That said, I and many others use this product routinely in production Plone sites, and deliver versions of it to clients for use on their production sites. Do with this product what you will, but use it responsibly. Practice safe Plone. 5. No animals were harmed in the creation of this Product, and no testing on live animals was performed. You should not attempt to use this Product in the manufacture or assembly of weapons of mass disfunction, as it is likely to function properly, thus causing failure of intended weapon disfunction. Any attempt to dissassemble or reverse engineer the functionality of this Product is strictly encouraged, and any successes in such endeavor should be shouted from the mountaintops. Or at least let me know, because I sure can't figure it out. Hence bugfix releases. I might start going the route of Microsquish and just start putting them out once a month instead of all the time. Sheesh. +lupa+ Lupa Zurven, CalendarX.org