Introduction
============

About
-----
SimplePortlet is a product that lets the user create his own portlets in Plone.
It adds three content types called Portlet, Smart Folder Portlet and RSS Portlet..
Adding these objects 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.
The Smart Folder portlet shows additional result from a designated Smart Folder and the RSS Portlet
allows you to pick a CMFSin channel (when installed).

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


Installing
----------
See docs/INSTALL.txt for installation instructions.


Usage
-----
After installation, two new classic portlets have been add to the plone-root:

* 'here/portlet_simpleportlet/macros/portlet_left'

* 'here/portlet_simpleportlet/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 SimplePortlet 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.**

SimplePortlet 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.

During installation, SimplePortlet scans all folderish objects in search for portlets
that are in use and tries to register them in the portlet_manager tool. You can check
this out for yourself to see if the friendly names that SimplePortlet has come up with is
good enough for you.

The layout form only accepts these friendly names to protect users from typing in the
wrong names which will break at least the current folder.
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 SimpePortlet's portlet manager if it exists
        try:
            pm = self.portlet_manager
        except:
            pm = None
        if not pm==None:
            pm.registerPortlet('<friendlyName>', '<path like here/myportlets/macros/portlet>')
                
    In you uninstall script::
        
        #unregister portlets
        try:
            pm = self.portlet_manager
        except:
            pm = None
        if not pm==None:
            pm.unRegisterPortlet('<friendlyName>')

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


Note
----
Upon uninstalling, SimplePortlet will try to remove all references in each folder's left_slots and right_slots to SimplePortlet's
portlets (see above for the two portlets). That means that when you install SimplePortlet 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.


CSS Styles
----------
(implemented by Osma Suominen, osma.suominen@mbconcert.fi)
It is possible to define a list of CSS styles for custom portlets. When creating/modifying a portlet the style can be chosen
from the list. The idea is to have matching CSS class definitions in e.g. ploneCustom.css. To enable style selection, write the names
of some CSS classes into a lines property called 'conf_portlet_styles' in portlet_manager (create it if it doesn't exist).
The entries can be either plain class names of the form class:visiblename so that you can have "friendly" style names for users.
The resulting portlet HTML code will start with <div class="portlet mystyle"> when a style "mystyle" is selected.

Topic display (implemented by clebeaupin, moved to separate type Topic Portlet by Osma Suominen)
The contents of topics may be listed in portlets. This requires AT Content Types or some other AT-based Topic type. You can choose
a topic and maximum number of entries to show.


Authors
--------
- Danny Bloemendaal -  danny.bloemendaal@companion.nl - _ender_@#plone.irc
