Collage developer documentation
===============================

The Collage product was built to be easily customizable.

Content views
-------------

New content views can be added by registering a browser view with a
browser:page-directive. Examples of this can be found in::

  ./browser/views.zcml

A view for a standard document can be registered as follows::

  <browser:page
     name="my-view"
     for="Products.ATContentTypes.content.document.ATDocument"
     permission="zope.Public"
     template="my-view-template.pt"
     class=".document.MyDocumentView"
     layer="Products.Collage.interfaces.ICollageBrowserLayer"
     />

To display a human-readable title, we associate the view with the following
class, placed in a file document.py:::

  from Products.Five.browser import BrowserView

  class MyDocumentView(BrowserView):
      title = u'My view'

Theme-specific content views
----------------------------

If you want to add a new view or override an existing view only for sites
using one particular theme product, you must register a theme-specific
Collage layer.  (We can't reuse the normal theme-specific layer, because
then there's no way to tell that the view is a Collage view).

To add a theme-specific Collage layer, use the following ZCML::

    <interface
        interface=".path.to.IMyCollageThemeLayer"
        type="Products.Collage.interfaces.ICollageBrowserLayerType"
        name="Plone Default"
        />

where the interface attribute is a custom marker interface that you have
defined, and the name attribute is the name of the CMF theme with which
you want to associate this layer.

Then you can use layer=".path.to.interfaces.IMyCollageThemeLayer" in your view
ZCML registration, instead of Products.Collage.interfaces.ICollageBrowserLayer.


Skins views
-----------

New skins views can be added by registering a named utility in::

  MySkin/browser/skins.zcml

For example, a skin "Alert" for the view "my-view" can be registered as
follows::

  <utility
     name="collage-my-view-alert"
     provides="Products.Collage.interfaces.IAlertSkin"
     factory=".skins.PortletSkin03"
  />

To display a human-readable title, we associate the utility with the following
class, placed in a skins.py::

    from Products.MySkin import MyMessageFactory as _

    class PortletSkin03(object):
        title = _(u"skin-03", default=u"My portlet skin")

Add IAlertSkin in MySkin/interfaces.py::

    from zope import interface
    class IAlertSkin(interface.Interface):
	 """Interface for alert skins views."""

To associate this skin to a view, you must add the interfaces implemented by the
skin::

  class MyDocumentView(BrowserView):
      title = u'My view'
      skinInterfaces = (IAlertSkin,)

Note that you don't need this above stuff for portlets views that are already
skinnable.

Finally, add your CSS rules in a stylesheet::

  #collage .collage-my-view-alert {
   ...

  }

Note that if you are using "Merge CSS composition" of CSS registry, your
stylesheet must be after "collage.css" and use the same condition as the
former::

  object/@@collage|nothing

Products.Collage provides a minimal skinning demo. See the ``skindemo`` folder
(start with ``skindemo/README.txt`` as usual).


Content controls
----------------

Content controls are registered as viewlets. See ./browser/viewlets.zcml for
examples.
