Package README (CVS ver. 1.3)

About

    PlonePortletManager (PPM) is a product that lets the user create his own
    portlets in Plone.
It adds a new content type called Portlet.
Adding this object to a folder will display it as a portlet in either the left
or right column.
Next to a title, description and some rich content you can also control in
which column it
has to show up, if it should show up in subfolders and whether it should be
displayed at all.

PPM is based on archetypes so that must be installed on your system.

Installing

    See install.txt for installation instructions.

Usage

    After installation, two new entries in the left_slots and right_slots
    properties of the portal's folder have been added:

    * 'here/portlet_ploneportletmanager/macros/portlet_left'

    * 'here/portlet_ploneportletmanager/macros/portlet_right'

    These two new entries in the slots are the actual macros that display the
    user-defined portlets. They act as placeholders
and at runtime they will check in the current folder (and parent folders to
accomodate inheritance)
to see if there are Portlets to display. So, removing these place-holders from
the slot definitions
will also disable the displaying of custom Portlets! This is important.

    Of course, by changing the order in these slot properties, you can control
    where in the order
the custom Portlets will be displayed.

    **Note**: a Portlet with the same id as a Portlet higher up the hierarchy
    will overrule it.
This enables you to turn off a Portlet that is defined higher in the tree.
Simply create an empty portlet with the same id and set it not to display.

    Together with PPM comes a layout editor that is presented as an extra tab
    on folders.
The tab is called 'Portlets' and gives you a form to change how portlets are
displayed
for that folder and subfolders. Portlets are inherited from higher folders.
With the layout editor you can overrule this inheritance by creating a local
definition.
This definition is also active for subfolders because they inherit portlets
on their part (unless you turn it off for them as well).

    So, each colum has his own set of options and lets you create a new order
or definition for which portlets should be displayed. Simply type the name of
one of the available portlets in either of the text areas. One portlet per line!
**Don't forget to include the user-defined portlets.**

    The portlet manager only allows the use of so called friendly portlet names.
So instead of having to type 'here/portlet_about/macros/portlet' you can just
type 'about'.
An administrator can add or alter these friendly names and their associated
true paths
in the properties tab of portlet_manager in ZMI. The id is the friendly name
and the value
is the full path. Make sure you add new properties as strings.

    The layout form only accepts these friendly names to protect users from
    typing in the
wrong names which will immediately make your plone site inaccessible.
When that does happen, you will have to go to that folder as an admininstrator
in ZMI and change the properties for that folder (left_slots and right_slots).

Developers

    If you have a product that also has portlets then you can register them
    with the portlet_manager in your install script::

       # register our portlets to PlonePortletManager if it exists
       try:
           ppm = self.portlet_manager
       except:
           ppm = None
       if not ppm==None:
           ppm.registerPortlet('<friendlyName>', '<path like
           here/myportlets/macros/portlet>')

    In you uninstall script::

        #unregister portlets
        try:
            ppm = self.portlet_manager
        except:
            ppm = None
        if not ppm==None:
            ppm.unRegisterPortlet('<friendlyName>')

I hope you will enjoy this product but use it at your own risk! Make a backup
first!

Note

    Upon uninstalling, PPM will try to remove all references in each folder's
    left_slots and right_slots to PPM's
portlets (see above for the two portlets). That means that when you install PPM
again, you'll have to go
to the folders that had a reference and restore them so that the custom
portlets will be displayed again.

Danny Bloemendaal <br/>
danny.bloemendaal@companion.nl <br/>
_ender_@#plone.irc