Products.SimplePortlet 1.2

Portlets as content-types

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, [e-mail]) 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 - [e-mail] - _ender_@#plone.irc

Changelog

1.2 (2010-05-04)

• Eggification from old-style SimplePortlet v1.1.3 [aclarke]

• Add MANIFEST.in [WouterVH]

• Fixed default value for attribute show_more_link [batlock666]