================
 collective.tin
================

The tin part of the alchemist's toolkit. You may find it useful in soldering
various zope 3 and zope 2/CMF concepts together.

This package provides useful components that enable RDBMS content to work
inside zope and plone.

Features
--------

RDBMS content is rooted in a TableFolder, so you may not place RDBMS content
freely all over your site. Each row of the associated table is treated as a
content item. These may be TableSubFolders which are further traversable over
a foreign key to rows in other tables.

RDBMS objects may also have an associated workflow table storing their
workflow_history.

Content is indexed in the portal_catalog as normal. To notify the catalogue of
updates fed directly into the RDBMS give your table a boolean reindex column,
setting the value to True in your external update / insert query. Calling

    >>> interfaces.IReindexer(sometablefolder)()

will then catalogue the new/updated row.

Or more likely, browse to /your/folder/@@tin.reindex -- This requires the
cmf.ManagePortal permission. You might want to set a clock-server in zope.conf

 <clock-server>
   # starts a clock which calls /your/folder/@@tin.reindex every 60 seconds
   method /your/folder/@@tin.reindex
   period 60
   user admin
   password 123
 </clock-server>

This approach requires no stub objects (apart from the TableFolder root),
allowing the RDBMS to be the canonical repository of your data. In a worst case
scenario the ZODB can be thrown away. Rebuild the portal_catalog and you are up
and running again. This approach was chosen so I could sleep soundly at night.

Row level versioning is available by implementing IVersionedItemContainer on the
Container and IVersionedItem on the Item. Your table structure should then be:

table: items
  id sometype primary key,
  current_version integer foreign key references items_versions.version_id,
  reindex bool

table items_versions
  version_id serial primary key
  id sometype foreign key references items.id,
  ... your data rows ...

table: items_workflow
  row_id serial,
  id sometype foreign key references items.id,
  workflow_id text,
  ... workflow variables ...


It's not ready yet. But it's getting closer.

Requirements
------------

  * Plone 3.x
  * z3c.sqlalchemy (and zope.sqlalchemy and SQLAlchemy, >= 0.5.3 recommeded)
  * DateTime >= 2.11.2
  * zope.schema >= 3.4
  * pytz>=2009a

You should probably include transaction as a fake-egg in your buildout.

You might find collective.mercury useful for generating the required
collective.lead Database definition, table interfaces and skeleton model
objects. XXX outdated now we don't use collective.lead

Example usage
-------------

The best example is in the test directory. Note that due to sqlite limitations
it will only work outside of a test if you run in single threaded mode... but
then presumably you wouldn't want your timesheets only stored in memory.

There is an incomplete and outdated `tutorial`_.

Installing the development version
----------------------------------

To specify the current `development`_ version you may use::

  eggs = collective.tin==dev

or get the `development buildout`_.

Copyright
---------

:

Copyright
    collective.tin is Copyright 2007, 2008, 2009 by `Laurence Rowe`_.



.. _tutorial: http://plone.org/documentation/tutorial/creating-sql-content-types-with-collective.tin
.. _development: https://svn.plone.org/svn/collective/collective.tin/trunk#egg=collective.tin-dev
.. _development buildout: https://svn.plone.org/svn/collective/collective.tin/buildouts/dev
.. _Laurence Rowe: http://objectvibe.net/blog