INSTALL.txt  
-----------
* CalendarX 0.9.5(stable)  November 7 2009
* (last modified for CalendarX 0.9.5)
* by +lupa+ (lupaz on sf.net, lupa at zurven dot com)
* Released under the GPL (see LICENSE.txt)

Contents:
---------
I.   Software requirements  (Updated for 0.9.3)
II.  Using buildout to install from SVN  (0.9.3)
III.  Older instructions for Installation for the first time.  (0.9.0)
IV. i18n: Internationalization instructions.  WE NEED TRANSLATIONS! (0.9.0)
V.  Documentation available. (0.9.0)
VI.   Caveats.   (0.9.0)



I.  Software requirements 
-------------------------
CalendarX v0.9.5 is tested on: 
  1. Plone 3.3.1 (not yet tested in previous versions).
  2. Python 2.4.6
  3. Zope 2.10.9

Software Suggestions (NOT REQUIRED):
  1. AdvancedQuery [this is available at Dieter's site:
     http://www.dieter.handshake.de/pyprojects/zope/ ]
     and AQ is also now included with Plone 3!
     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 properties. 

    
II.  Using buildout to install from SVN  (0.9.3)
------------------------------------------------
By the time you read this there SHOULD be an egg at Pypi, ready to use as
Products.CalendarX.

Previous: We are working on one, but at present there is no official egg release
for CalendarX yet.  There is one based on CalendarX-0.9.1 in the 
collective called "Products.CalendarX" but I am not responsible for 
that fork, and am not maintaining it at this time.

In my buildout (based on the stock buildout.cfg on a stock install of 
Plone 3.3.1 for Mac OSX), there are two required things to get this branch
of CalendarX out of SVN at Plone and ready to run on your Plone: 

1. in your buildout.cfg, add the following 5 lines (I put mine near the 
very bottom, next to last recipe)::

    # This brings in CalendarX from the collective, puts it into /parts/productcheckouts in your instance folder
    [productcheckouts]
    recipe = infrae.subversion
    urls =
        https://svn.plone.org/svn/collective/CalendarX/branches/plone-3-compatibility/ CalendarX


2. In the section of buildout.cfg for [instance], find the 'products' 
listing (probably after eggs and zcml), and add the TWO LINES at the 
bottom of this (the rest is just there to show you where to put them)::

    [instance]
    recipe = plone.recipe.zope2instance
    ...
    products =
        ${buildout:directory}/products
        ${productdistros:location}
        # This tells buildout to be sure and precompile and use any products found here (where CalendarX is)
        ${productcheckouts:location}


**Explanation:** The first part is a recipe for bringing in the CalendarX code
from svn.plone.org.  It puts it into /parts/productcheckouts in your
instance.  The second part tells buildout to compile it and make it one
of your Plone products ready to be installed via quick_installer or with 
the setup Add Products section in your Plone instance. 


3. Finally: 

* run ./bin/buildout -v to refresh your buildout, and bring in CalendarX
* restart Zope
* add your CalendarX as a product in Plone
* add a CalendarX instance in your Plone wherever you want it
* configure with the 'manage' tab (lots of options) and go.



III.  Older instructions for Installation for the first time.
-------------------------------------------------------------
*NOTE* this was written for Plone 3.0.4 and CalendarX-0.9.0(dev). Untested
for any previous versions.  See installation instructions included with
earlier versions for installation in earlier Plones. 

1.  Make sure you have appropriate required software (see above).

2. FROM A TARBALL: Acquire the CalendarX-0.6.x.tar.gz file from sf.net.  
    This unzips as a tar file, which untars as a single folder, called 
    "CalendarX-0.9.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.9.x.  

4. FROM SVN: In a terminal window on your server, cd to your INSTANCE_HOME
    /Products folder.  Use the following command to check out the CalendarX
    SVN repository for the /plone-3-compatibility branch:
    
    svn co https://svn.plone.org/svn/collective/CalendarX/branches/plone-3-compatibility/ CalendarX
    
    This command grabs the appropriate branch, and creates a new folder called
    /CalendarX in your /Products folder.  No renaming required.    

5.  Restart Zope. 
    
6.  Go to your Plone portal, and log in as a manager.  Go to Site Setup 
    and Add-on Products.  Find CalendarX in the list and check it, and 
    click the Install button.  
    
7.  IN PLONE: Navigate to where you want a CalendarX instance, and add a 
    CalendarX in the normal fashion, using the dropdown "Add new..." menu.  
    Give it an id of "calendar" or whatever you want. 
    
    **NOTE: CalendarX is not an ordinary Plone folder.**  It is a lightly 
    modified Archetypes BaseFolder.  The default view is set as an attribute 
    (defaultView) and shows up when you use the CalendarX id as your URL.
    You CAN view the ordinary aspects and tabs of the CalendarX folder by 
    clicking the new "migrate" tab on the CalendarX view (only visible to 
    users with Modify Portal Content permissions).  All tabs except the "view"
    tab work normally... the view tab takes you back to CalendarX default view.
    
8.  That's it.  CalendarX will show up as the default view (month to start).
    Be sure to "publish" the CalendarX instance or nobody else will be able
    to use your calendar.  
    
9. To customize your CalendarX, click the "manage" tab... this is the same as
    typing "/edit" after the URL of your CalendarX instance, and customize 
    the properties there.  There are several categories of attributes that can 
    be customized: Calendar Options, Event display properties, Subcalendar
    properties, Popup properties, Add event link properties, and CSS properties
    (users of older CalendarX versions will recognize these categories as 
    being the names of the old property sheets).  These have some basic 
    descriptions of what they control written right there on the edit forms.

10. To create more than one instance of CalendarX is easy... just add another
    one from the dropdown list and give it a new name (id).  Each CalendarX 
    instance will use its own properties; they are not shared across instances.
   




IV. 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.

   **Some translations and status:**
   
   * calendarx-ca.po      - FINISHED 
   * calendarx-cs.po      - FINISHED 
   * calendarx-da.po      - FINISHED 
   * calendarx-de.po      - FINISHED 
   * calendarx-es.po      - FINISHED 
   * calendarx-fr.po      - FINISHED 
   * calendarx-it.po      - FINISHED 
   * calendarx-ja.po      - FINISHED 
   * calendarx-nl.po      - FINISHED 
   * calendarx-pt-br.po   - FINISHED 

   Other language .po files gladly accepted!  

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.  
  



V.  Documentation available
----------------------------
Contents of the CalendarX.0.9.x /docs folder:

* CREDITS.txt - some people who deserve our thanks.
* CUSTOM.txt - description of how to customize CalendarX with skins.
* 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.



VI.  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.  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 (or just email lupa).

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+

