ListingPages

A content type to create custom listing pages in your Plone site - list all content of a given type, in a given review state etc. Also includes support for simple composite pages with multiple lists and "featured items". By default, ships with a simple set of templates for layouts and listings, but provides a simple way of creating a customised look-and-feel with a bare minimum of page template coding.

Current release

No stable release available yet.

Project Description

ListingPages is a product which contains tools for letting site administrators build pages containing listings of items, similar to the news.pt template found in Plone, but more flexible. It also allows more complex compositions of these pages into templates.

Status

Version 1.0b1:

  • Works, used in production - Only basic templates included. Please submit other, general templates if possible - No internationalisation. i18n patches gratefully accepted! - No unit tests - tested in the field :-)

Information

Install: Using the quickinstaller as normal.

Requires: Archetypes 1.3, ATReferenceBrowserWidget, Plone 2

Created with ArchGenXML. The model is in the model/ directory. The .odm file is the original model used in ObjectDomain v 3.00.292

Use

ListingPages has two main audiences:

  • Site administrators who want to set up listings of certain content types, for instance all recently published news items, or all documents in alphabetical order.
  • Developers who want to provide similar listings and allow site admins to define the listing criteria, but with custom templates.

It consists of three main content types

  • SimpleList - a simple list of criteria
  • FeaturedItem - a single featured item, selected via an Archetypes reference (hence, featured items must be archetypes based - use ATContentTypes if necessary). This is by default only enabled inside a CompositeListing.
  • CompositeListing - an arbitrary composition of the above types

Views

In order to define views, a control tool called portal_listingpagestool is installed. You can access this via a Plone configlet. This configlet lets you create a list of page templates which provide views for the above pages.

To provide a new view of the SimpleList, for instance, create a template which contains a macro called SimpleList. This macro will be called to generate the list, and will have available a variable called list containing a catalogue query you can iterate over in order to display the list. If you also want to create a view for a FeaturedItem, add a macro with the name FeaturedItem, which will have a variable called featuredItem available.

Once you have created your template, enter its name on a new line in the templates list in the ListingPage tool. When you add or edit one of the above content types, you will be able to select the view template to use, provided it is registered in the tool and contains an appropriately named macro.

Compositions

The CompositeListing type is a folderish type, into which you can put SimpleList and FeaturedItem objects. A layout template then composes these into a single page. You register a layout template in the same way as you register a view template, using a macro named CompositeListing.

In general, you will create a CompositeListing type first, and then add SimpleLists and FeaturedItems as appropriate. Once you have configured these the way you want them and selected appropriate view templates, as well as chosen a layout template on CompositeListing's edit page, you go to the layout tab of the CompositeListing object to manage your layout. In this tab, you will see the layout of the page as defined by the layout template's CompositeListing macro, and you can choose which of the objects inside the layout to display where.

The way this works is as follows: The layout template selected contains the layout of the page structured with divs, tables etc. Where a composed listing should appear, it includes a slot:

        <div metal:define-slot="slot0"/>

The slots must be numbered slot0, slot1, etc. up to slot9. If you have more than 10 slots in a layout, your page is too complex. :-)

Depending on whether the page is currently being edited or displayed, this will have different effects. If the page is currently being edited, the slot will be filled with a drop-down box allowing the user to select which of the composed elements to display in the place where the statement appears. When saved, the CompositeListing will remember which macro was associated with each slot (slot0 in this case). When the page is being viewed, the view action will render the object chosen in the slot using the appropriate macro found in the display template selected on the composed object.

If you require more complex layouts, you have the option, in addition to writing a new layout template, to add a CompositeListing inside the layout of another CompositeListing. This is disabled by default so as not to be too confusing, but if you add CompositeListing to the addable types of the CompositeListing item in portal_types in the ZMI, you can nest CompositeListings and include an inner CompositeListing much in the same way as you include a FeaturedItem or a SimpleList in a composite layout.

Alternatives

This product is similar to mxmDynamicPage, but has a slightly different philosophy.

mxmDynamicPage may be easier to use for end users, and has some options this product does not (and vice-versa). It is also a more mature product at this stage, so you are a recommended to check it out. mxmDynamicPage is, however, slower because it translates all catalogue query results to actual objects, and it is harder to customise the look-and-feel of listings, especially where several sources (products, custom templates in the ZMI) may wish to provide their own list views. It does not have the composition features here, which may make it less confusing, but also less flexible. Finally, it's not Archetypes based, which makes it harder to extend, and the UI doesn't gel with Plone as nicely as an AT based product.

CMFContentPanels does much of the composition, and is more flexible, but also quite confusing (to me at least) and again has a different philosophy. You should take a look at this, too.

CompositePack looks like an interesting option, but did not work when last I tried it. This may have changed, though. :-)

Author and Acknowledgements

Martin Aspeli

Thanks to The NanoBusiness Alliance for sponsoring this work and graciously permitting its release as open source.

License

This product is released under the GPL, version 2. See http://gnu.org for details. Use it, enjoy it, make new templates as you wish, but if you modify its source code or derive other products from it, you must release the source code of any changed or derived software you distribute.