[Grok-dev] Spotlight on : dolmen.content

[Souheil CHELFOUH]

Hello,

It took a while for me to decide and post my first spotlight.
I guess I have some kind of paralysis when I need to write a doc out
of nothing :)
Finally, here is the README.txt of the package. Yeah, ok... but, it
think it's quite understandable and readable (?)

This spotlight is about dolmen.content, which is the first package I
wrote for Grok and the Dolmen project.
It first was a Plone package, using five, and five.grok, and it was
called "spear.content" (in 2007).
I refactored it partially, while I stopped Ploning and first started
the Dolmen project (ex-spear)
It's used outside of the Dolmen project in another Grok project called
uvcsite, coded by Christian Klinger.


==============
dolmen.content
==============

The package `dolmen.content` is a convenient way to define content
types. Content types usually have several attributes : a type, a
schema, an icon. In addition, they need security to control the
creation, pages to edit them, easy ways to control the display, and
the widgets. 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`, `icon`,
`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'


Grokking
--------

We now let Grok register our component::

  >>> from grokcore.component import testing
  >>> testing.grok_component('mycontent', MyContent)
  True


Factory
-------

When the content is registered, 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 ...>


Foot notes for the grokkers out there
==============================

If you thought that Spotlight was too much code, or not detailed
enough, please let me know
I'll try to cover most of the interesting packages I released lately.
Please note, also, that dolmen.content is currenty under heavy surgery.
At the moment, the schema fields boostrap is done by a grokker.
I decided to drop this and use a zope.interface ClassAdvisor, to allow
very straightforward bootstrapping, even on non grokked objects.
Also, the 'icon' directive should disapear, soon, if I can get a
decent release of megrok.icon (another package I need to work on !)