Clio Models
===========

The next step is to define Clio models. A Clio model is a class that
is going to be mapped to a table by the SQLAlchemy ORM. A Clio model
also has a number of special methods that can be used to drive the
workflow process and that will be described later.

It is easy to create a Clio-based model, just subclass from
``clio.Model``::

  import clio

  class Address(clio.Model):
      pass

In many cases, a ``clio.Model`` needs to define its own
``__init__``. This looks like this::

  class Address(clio.Model):
      def __init__(self, code, street, city, country):
          super(Address, self).__init__(code)
          self.street = street
          self.city = city
          self.country = country

Note that it is required to call the superclass and pass it the
``code``.

Mapping
-------

After definining the tables and the model classes, we use the normal
SQLAlchemy object relational mapper to map the classes to the tables::

  from sqlalchemy.orm import mapper

  mapper(Address, address_table)

This is standard SQLAlchemy, and we have seen everything needed to
create a Clio-managed model. The situation becomes a bit more involved
when we want to create relations between models.

Workflow properties
-------------------

The Clio table columns described earlier will exist on the mapped
instances. The following properties are available:

id 
  An integer attribute uniquely identifying the record underlying the
  instance. Will be automatically set by the system.

code
  An integer that uniquely identifies the actual information managed
  this object. Other versions of this object in other workflow states
  will have the same ``code``, but not the same ``id``.

status
  An integer that indicates the workflow status that the particular
  version is in.

created_timestamp
  The moment this version was created.

created_userid
  The (app-specific) user id that created this version.

published_start_timestamp
  The moment this version became published (None if not yet published).

published_end_timestamp 
  The moment this version became archived (publication ended).

published_userid
  The (app-specific) user id of the user that initiated publication.

changed_timestamp 
  The moment this version was last changed. If a newly created object
  this is the same as the ``created_timestamp``. If a new version of
  an existing object the ``changed_timestamp`` of the previous version
  is copied. If the user changes the version, the application should
  notify the version by calling its ``mark_changed()`` method.

changed_userid
  The (app-specific) user id of the user that last changed this
  version. If a newly created object this is the same as the
  ``created_userid``. If a new version of an existing object the
  ``changed_userid`` of the previous version is copied. If the user
  changes the version, the application should notify the version by
  calling its ``mark_changed()`` method.
