============
Installation
============

* CalendarX 0.9.6(stable)  December 6 2009
* (last modified for CalendarX 0.9.6)
* by +lupa+ (lupaz on sf.net, lupa at zurven dot com)
* Released under the GPL (see LICENSE.txt)

.. contents::


Software requirements
=====================

CalendarX v0.9.5 is tested on:

1. Plone 3.3.1, 3.3.2 and should (but untested) work with any Plone 3.x
2. Python 2.4.6
3. Zope 2.10.9


Production installation
=======================

Using ``zc.buildout``, ust add ``Products.CalendarX`` in your "eggs" list,
either in ``[buildout]`` or in the ``[instance]`` section.

Developer installation
======================

Follow these instructions::

  $ svn co https://svn.plone.org/svn/collective/Products.CalendarX/trunk Products.CalendarX
  $ cd Products.CalendarX
  $ python bootstrap.py
  $ bin/buildout

You may tweak buildout.cfg to use another Plone version, add development
helpers, etc.


Older instructions for Installation for the first time
======================================================

.. warning::

   As of version 0.9.3, this section is **deprecated**, please use one of the
   two above mentioned installation methods.

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





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.




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.



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+

