==============================================
How to register new portlets from CPSInstaller
==============================================

:Revision: $Id: cpsinstaller.txt 30517 2005-12-12 19:48:06Z dkuhlman $

.. sectnum::    :depth: 4
.. contents::   :depth: 4


What is it?
===========

CPSInstaller allows you to register your portlets from the
installer of your product. This means it can create for you the
portlets given a specific configuration. (right now it's Python
structure, but it has to change...)


Available API
=============

Within CPSInstaller module::

    getPortletContainer(self, object=None, create=0):
    """get a portlet container and create it if not found and asked for"""

    verifyPortletContainer(self, object=None):
    ""Verify the existence of the portlet container and create it if not
      found.
      If object is None then it's gonna verify it the root of the portal
    thus within the portlets tool.
    """

    verifyPortlets(self, portlets, object=None):
    """Verify the existence of given portet in the object's portlet
       containe r.  If not found, a portlet is instantied. Existing
       portlets are not affecte d.

       portlets is a dictionary with keys begins the box ids, and values being
       the dictionary given by the export tab.
       The default object is the portal itself.

       return the list a new portlet ids.
       """


Examples
========

Use it through the ``verifyPortlets()`` method.

You need to specify the context such as: ``portal.workspaces``,
``portal.sections`` or ``portal.whatever``.

And then a Python dictionary describing the portlets you want to
add.

This example takes place within the installer of your product.
(Check out the CPSInstaller documentation if you don't know what
I'm talking about.)

The installer below is a CPSInstaller instance::

    >> portlets = ({'type'  : 'Dummy Portlet',
                    'identifier' : 'Dummy1',
                    'Title' : 'Fake Portlet',
                    'slot'  : 'left',
                    'order' : 0},
                   {'type'  : 'Dummy Portlet',
                    'identifier' : 'Dummy2',
                    'Title' : 'Fake Portlet 2',
                    'slot'  : 'right',
                    'order' : 2},
                  )

    >> installer.verifyPortlets(portlets, self.portal.workspaces)

A few notes:

- HUOM!

- ``type`` is compulsory.

- ``identifier`` is compulsory if you want to do updates in the
  future.

For the others there are default values.


CPSSkins exports configuration
==============================

So you should be able to manage through the CPSSkins interface and
then export and import your configuration.

less is more :)
