Metadata-Version: 1.0
Name: dolmen.content
Version: 0.6.2
Summary: Dolmen content type framework
Home-page: http://gitweb.dolmen-project.org/
Author: Souheil Chelfouh
Author-email: souheil@chelfouh.com
License: GPL
Description: ==============
        dolmen.content
        ==============
        
        The package `dolmen.content` is a convenient way to define content
        types.
        
        .. contents::
        
        About
        =====
        
        Content types usually have several attributes defined in a
        schema and a name. In addition, they often need security to control the
        creation or the modification (update, deletion, etc.). This is what
        provides `dolmen.content`, with an easy-to-use set of grok directives.
        
        Example
        =======
        
        A `dolmen.content` content is declared as a simple class. Some
        directives are available to define your content: `name`, `schema` and
        `factory`. To have detailed information about these directives, please
        have a look at the package tests.
        
        
        Defining the content
        --------------------
        
        Let's demonstrate the package's features with a simple and
        non-exhaustive test::
        
          >>> import dolmen.content
          >>> from zope import schema
        
          >>> class IContentSchema(dolmen.content.IBaseContent):
          ...    text = schema.Text(title=u"A body text", default=u"N/A")
        
          >>> class MyContent(dolmen.content.Content):
          ...  """A very simple content
          ...  """
          ...  dolmen.content.schema(IContentSchema)
          ...  dolmen.content.name("a simple content type")
        
        
        Schema
        ------
        
        The content can now be instanciated. As we can see here, the object is
        effectively providing the schema, even without grokking::
        
          >>> MyContent.text
          <zope.schema.fieldproperty.FieldProperty object at ...>
        
          >>> IContentSchema.implementedBy(MyContent)
          True
        
          >>> obj = MyContent()
          >>> obj.text
          u'N/A'
        
        The content can also be instanciated providing initial values::
        
          >>> obj = MyContent(text=u"This is a nice text !")
          >>> obj.text
          u'This is a nice text !'
        
        Even though the schema has been applied and the content type
        boostrapped, the content type is not yet complete::
        
          >>> obj.__content_type__
          Traceback (most recent call last):
          ...
          AttributeError: 'MyContent' object has no attribute '__content_type__'
        
        To get all the features of a `dolmen.content` Content, we need to
        register our component : we need to grok it.
        
        
        Grokking
        --------
        
        We register our component::
        
          >>> from grokcore.component import testing
          >>> testing.grok_component('mycontent', MyContent)
          True
        
        An additional information is now available::
        
          >>> obj.__content_type__
          u'a simple content type'
        
        The grokking process also allowed an automatic registration of a very
        convenient factory as an utility.
        
        
        Factory
        -------
        
        When the content is grokked, a factory is registered, using the
        full module and class dotted names. It allows us to query and
        instanciate the content easily::
        
          >>> from zope.component import getUtility
          >>> factory = getUtility(dolmen.content.IFactory,
          ...                      name="dolmen.content.MyContent")
          >>> factory
          <dolmen.content.factoring.Factory object at ...>
        
        The factory will create your content type for you, when called::
        
          >>> obj = factory()
          >>> obj
          <dolmen.content.MyContent object at ...>
          >>> obj.text
          u'N/A'
        
          >>> obj = factory(text=u"This is as easy as it seems.")
          >>> obj
          <dolmen.content.MyContent object at ...>
          >>> obj.text
          u'This is as easy as it seems.'
        
        Security
        --------
        
        The created content type has a basic security declaration. We can
        retrieve the value of the permission protecting the content type by
        using the `require` directive::
        
          >>> dolmen.content.require.bind().get(obj)
          'zope.ManageContent'
        
        Please note that this security declaration is _not_ used anywhere in
        `dolmen.content`. It's provided as a convenient way to declare a
        permission at the content type level. The factory does not check this
        permission. If you need a permission checker at the factory level,
        please provide your own factory : see the tests module, factory
        folder, for examples.
        
        
        Changelog
        =========
        
        0.6.2 (2011-02-10)
        ------------------
        
        * Fixed inheritance bug: the properties of the parent classes were
          overriden, if defined in the schema. This has been solved by
          deferring the schema treatment in the class advisor and by using
          'hasattr' instead of checking the class __dict__.
        
        
        0.6.1 (2011-02-02)
        ------------------
        
        * Cleaned up the ZCML declarations, to be sure it includes all the
          needed dependencies.
        
        
        0.6 (2010-11-06)
        ----------------
        
        * Cleaned up dependencies. ``zope.formlib`` is no longer used.
        
        * The code has been updated to work with the latest ``martian`` and
          ``grokcore.component``.
        
        * The `__content_type__` property is now a unicode string. This will
          convert the given name to unicode or die trying.
        
        
        0.5.1 (2010-07-13)
        ------------------
        
        * Added `zope` domain translation for the `Title` label of the
          `IBaseContent` interface.
        
        
        0.5 (2010-07-13)
        ----------------
        
        * Default factory now provides a valid `IFactory`
          implementation. Added tests to fix that.
        
        * Changed the policy of the `__content_type__` attribute
          computation. Tests have been added to prevent any changes and
          regression.
        
        * Added an util function to fetch the content type of an object or
          class.
        
        * The `IFactory` interface now allows empty `title` and `description`,
          in accordance with the base value of the generic factory and
          directives.
        
        
        0.4 (2010-07-13)
        ----------------
        
        * Factories now provide a name and a description, in addition to the
          title. These attributes, by default, fetch the generated class
          directives' values.
        
        * Updated tests and improved the coverage.
        
        * The factories `name` attribute no longer returns a cooked i18n
          value, but the `name` directive's value of the generated
          class. The form has to take care of its own title now.
        
        
        0.3.1 (2010-02-22)
        ------------------
        
        * Corrected a very important bug in the models instanciation. The
          simple instanciation was causing an infinite loop due to imports
          having the same name than the module classes. This is fixed and tests
          have been added to test this simple case and avoid regression.
        
        
        0.3 (2010-02-08)
        ----------------
        
        * Using the new `grokcore.content` package, allowing to cut the `grok`
          dependency.
        
        * The `BaseContent` now sets a default `require` value at
          `zope.ManageContent`. This permission is _NOT_ used, it's just a
          convenient directive to implement your own security check.
        
        * Dependencies have been cut down. `zope.app` packages are no longer
          used. The tests module has been rewritten for a cleaner and clearer
          read.
        
        * Directive `icon` has been removed. The functionality will be
          implemented in a standalone package. ATTENTION, this might break
          your existing code !
        
        * Directive `schema` now works without grokking, using a
          `zope.interface` class advisor. This allows a flexible
          bootstrapping, even in non-grokked code.
        
        
        0.2.2 (2009-09-25)
        ------------------
        
        * Using the last `dolmen.field` version with a bug fix.
        
        
        0.2.1 (2009-09-20)
        ------------------
        
        * Added tests and cleaned the testing module.
        
        
        0.2 (2009-09-04)
        ----------------
        
        * Added an OrderedContainer base class.
        
        
        0.1 (2009-09-01)
        ----------------
        
        * Initial release
        
Keywords: Grok Zope3 CMS Dolmen Content
Platform: Any
Classifier: Environment :: Web Environment
Classifier: Framework :: Zope3
Classifier: Intended Audience :: Other Audience
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
