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

I.  Software requirements  (Updated for 0.6.5)
II.  Instructions for Installation for the first time.  (0.6.5)
III. i18n: Internationalization instructions.  WE NEED TRANSLATIONS! (0.6.5)
IV. Documentation available.
V.  Caveats.  

Old Instructions for upgrading to new versions of CalendarX 
    (MOVED these instructions to MIGRATE.txt) 
Plone BUGFIXES: There are two known Plone bugs that should be fixed in 
  order for everything to work right in CalendarX... one in Plone 2.0.5
  and another in Plone 2.1.1.  Details are below.


I.  Software requirements
!!! DON'T USE Python 2.4 !!!  Well, ok, it does run on Python 2.4 but there 
  have been some peculiar problems, especially when a file accidentally had 
  DOS carriage returns in it.  Talk about picky!  Oh well.
Software Requirements for CalendarX (0.6 branch): 
  1. Plone 2.0+ (also tested working in 2.1.1).
  2. Python 2.2 or 2.3, NOT 2.4.
Software Suggestions (NOT REQUIRED):
  1. Zope 2.7.x+ (may work on earlier Zopes, but untested. Python 2.2+ is not
    standard until Zope 2.7+)
  2. AdvancedQuery [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 skins property sheet. 

    
II.  Instructions for Installation for the first time.
*NOTE* these instructions were written for Plone 2.0.5.  They still work 
  roughly the same in Plone 2.1.1, but there may be small differences.  I've 
  only just begun working in Plone 2.1.1 myself and haven't a lot of 
  experience here yet.  But it does work, no fear about that.

1.  Make sure you have the required software and additional Zope Products
    in place. Additionally, there may be bugfixes you need to apply to 
    your Plone install.  Here are the two I'm aware of, one for Plone 2.0
    and one for Plone 2.1.

#NOTE: IMPORTANT BUGFIX TO Plone version 2.0.5# 
There is a bug in Plone 2.0.5 that will bite you if you change your Events 
  from 24 hour clock to the 12am,pm style.  The bug is documented here on the
  Plone.org website: 

  http://trac.plone.org/plone/ticket/3641 or
  http://plone.org/collector/3641 (older link, reroutes to above)

and is also described on the CalendarX website here: 

  http://calendarx.org/issues/talkback/1104958175

You can patch the bug either on the filesystem, or through the ZMI in your 
  portal_skins/custom folder.

#NOTE: IMPORTANT BUGFIX TO Plone version 2.1.1# 
There is a bug in ATContentTypes, event.py distributed with Plone 2.1.1 that
  forces the Event to keep the Event vocabulary, even if you have repurposed
  an Event in portal_types and given it a new Type name.  The bug is 
  documented here on the Plone.org website: 

  http://trac.plone.org/plone/ticket/5307

and also is described on the CalendarX website here: 
  
  http://calendarx.org/issues/talkback/1135185404

and must be patched on the filesystem.  In brief: 

In YourZopeInstance/Products/ATContentType/content/event.py
change the definition of 'getEventTypes' from

        metatool = getToolByName(self, "portal_metadata")
        events = metatool.listAllowedSubjects(content_type = "Event")
        return events

to

        metatool = getToolByName(self, "portal_metadata")
        my_type = self.getPortalTypeName()
        events = metatool.listAllowedSubjects(content_type = my_type)
        return events


"Event" was hardcoded into the event.py, so that even repurposing it 
  failed to get the Vocabulary info from portal_metadata, and there may
  be other side effects.  FAILURE to fix this one means that the Resources 
  Calendar exercise in the Manual will NOT work properly.

    
2.  Acquire the CalendarX-0.6.x.tar.gz file from sourceforge.  This unzips as 
    a tar file, which untars as a single folder, called CalendarX-0.6.x.  

3.  RENAME!  In your Zope INSTANCE, place this folder in your 
    INSTANCE_HOME/Products/ folder and rename the folder to 
    /Products/CalendarX instead of /Products/CalendarX-0.6.x.  

4.  Restart Zope. 
    Note: If you are Reinstalling CalendarX, read MIGRATE.txt in the docs.
    There's really nothing to do if you haven't customized it at all, 
    but nearly everyone does some customizing, at least for the property
    sheets.
    
5.  Go to your Plone portal, and log in as a manager.  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 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.

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:  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.  To further customize it, find the object
     in /portal_skins/CalendarX that you want, hit the Customize button, then 
     CUT/PASTE it into your CalendarX instance, and then make your changes.
     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.


III. i18n: Internationalization instructions.  WE NEED TRANSLATIONS!
CalendarX-0.6 branch has i18n capability.  There are now eleven translations 
  (as of 0.6.4 release).  If you can help, please do!  Here's how: 

1. Go to the i18n folder.  This is where the translations are stored.

2. Choose one of the translated files as a starting point; any of them will do
  for getting started.  

3. Copy the file and rename it: here are the translations that are standard
  in Plone that we don't have yet, and would LOVE to have for CalendarX so 
  that we're compatible in all these.  And we would love to have even more
  than these... as many as we have languages for folks using CalendarX!  So 
  copy one of the translations we have, and translate all the terms into your
  language of choice.

Thirty-some translations and status:
  calendarx-af.po      - needed 
  calendarx-ar.po      - needed 
  calendarx-bg.po      - needed 
  calendarx-ca.po      - FINISHED 
  calendarx-cs.po      - FINISHED 
  calendarx-da.po      - FINISHED 
  calendarx-de.po      - FINISHED 
  calendarx-el.po      - needed 
  calendarx-eo.po      - needed 
  calendarx-es.po      - FINISHED 
  calendarx-es-ar.po   - needed 
  calendarx-es-es.po   - needed 
  calendarx-et.po      - needed 
  calendarx-eu.po      - needed 
  calendarx-fa.po      - needed 
  calendarx-fi.po      - needed 
  calendarx-fr.po      - FINISHED 
  calendarx-he.po      - needed 
  calendarx-hr.po      - needed 
  calendarx-hu.po      - needed 
  calendarx-hy.po      - needed 
  calendarx-it.po      - FINISHED 
  calendarx-ja.po      - FINISHED 
  calendarx-ka.po      - needed 
  calendarx-ko.po      - needed 
  calendarx-lt.po      - needed 
  calendarx-nl.po      - FINISHED 
  calendarx-nn.po      - needed 
  calendarx-no.po      - needed 
  calendarx-pl.po      - needed 
  calendarx-pt.po      - needed 
  calendarx-pt-br.po   - FINISHED 
  calendarx-ro.po      - needed 
  calendarx-ru.po      - needed 
  calendarx-sv.po      - needed 
  calendarx-tr.po      - needed 
  calendarx-uk.po      - needed 
  calendarx-zh.po      - needed 
  calendarx-zh-cn.po   - needed 
  calendarx-zh-hk.po   - needed 
  calendarx-zh-tw.po   - needed 

Other language .po files gladly accepted!  This is the list that is present
  in Plone 2.0.5.  If more will be available for Plone 2.1, let's get those
  all in here too.

4. Translate all the strings and the few date and time formatting strings that
  are present.  Also, if your translation should serve as a fallback 
  translation, include those translations that should fallback here... follow
  the other calendarx-xx.po files or (really) the examples in CMFPlone/i18n for  
  a guideline.  
  
5. Test your translation:  put it in your /Products/CalendarX/i18n folder, and
  restart your Zope.  Actually RESTART your Zope, don't just refresh the 
  CalendarX product -- that's not enough, because the i18n initialization takes
  place at Zope startup.  After the initial restart, you can test your new 
  translations or modifications you make by going in your ZMI to the Control
  Panel, select PlacelessTranslationService, find the po file you're working 
  on click it and hit the Refresh Catalog button to update the translation 
  catalog with your new work.  Then email your translated po files to lupa.
  
6. Check the results in your browser.  Set your browser's default language for
  your desired translation and see the difference.  Also, if desired, you can
  download PloneLanguageTool and install it, and use it to make a language 
  switcher in your site... that makes it easy to test different translations
  and see what they look like.  I use PLT on the Crashtest site where you can
  try out CalendarX-0.6.x translations.
  
7. Pay particular attention to getting the formatting strings localized... do 
  you want to say "April 2005" or "2005 Avril"?  There are more lots of these 
  formatting strings... make them the way YOU think your users visiting in your
  language translation would be comfortable seeing these strings.  Then be sure
  to test these all out.  
  



IV.  Documentation available:
Contents of the CalendarX.0.6.x /docs folder:
        CREDITS.txt - some people who deserve our thanks.
        CUSTOM.txt - description of how to customize CalendarX with skins.
        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_popup_text.txt - instructions for the popup properties
        CX_props_addeventlink_text.txt - how to control the Add New Event link
        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.
        README.txt - brief message identifying CalendarX.
        TODO.txt - some things to finish before this branch becomes (stable).
        VERSIONS.txt - explains version numbers used for CalendarX releases.
        CalendarXManual-065-draft06.pdf - a manual with all the 
          goodies from these documents, and some more besides.  

        
    

V.  Caveats.
0.  These caveats have been included here since the first releases of CalendarX
    and I've never had 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 dysfunction, as it is likely
    to function properly, thus causing failure of intended weapons. 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.
    
+lupa+

