#144: Generalized Next / Previous navigation

Contents

1. Motivation
2. Assumptions
3. Proposal
4. Implementation
5. Deliverables
6. Risks
7. Participants

Proposed by

Alexander Limi

Seconded by

Martin Aspeli

Proposal type

User interface

Assigned to release

• Plone 3.0

Repository branch

plip144-nextprenavigation-bundle

State

completed

Motivation

There is a need for a feature that allows a user to navigate easily between content items stored in a container such as a folder.  The proposal is to create a next-previous-widget that provides a link to the next and previous item relative to the content item being viewed within the folder.

Often, a user wants to quickly browse content in a folder and move effortlessly from one piece of content to the next without having to navigate away from the content item they are viewing.  At present, this functionality does not exist.  A user will be required to return to the folder listing and select the next content item or use the navigation tree portlet, if available.  This requires more clicks than necessary.  

Adding a next-previous-widget feature that provides links to navigate to the next or previous content item, relative to the one you are in, provides more user-friendly interface.  By also including a setting on the container (e.g.folder) to enable/disable this functionality, you can control whether or not you want to make this feature available.

Assumptions

1. The ATFolder will have a setting that will allow you to turn the next/previous feature on.  It has been assumed that this will be set to off by default.
   
2. The next/previous feature will provide an adapter for the ATFolder content type.  However, it is not within the scope of this PLIP to provide an adapter for ATTopic (Smart folder, Topics).
3. The next/previous feature will ignore subfolder.

Proposal

The proposal is to create a next-previous-widget that provides links to the next and previous items relative to the content item being viewed from within a container type such as a folder. 

There should be a setting on the folder to allow the next/previous links feature to be enabled/disabled. 

Sub-folders should default to the same setting (enabled/disabled) as the parent folder.  However, you should be able to explicitly change the setting on the sub-folder so that it no longer inherits the parent folder setting.

Implementation

We have created an interface to provide the relevant methods for the next/previous feature:

class INextPreviousProvider(Interface):

    def getNextItem():
        """Returns the next item in the container"""

    def getPreviousItem():
        """Returns the previous item in the container"""

    def isNextPreviousEnabled():
        """Checks if the container has next / previous navigation enabled"""

We have provided an adapter for the ATFolder content type:

class ATFolderNextPrevious( object ):
    """ Adapts next-previous for ATFolder """
    implements(INextPreviousProvider)

The adapater is "glued" to the ATFolder in the "configure.zcml" file:

   <adapter for="Products.ATContentTypes.interface.folder.IATFolder"
            factory=".nextprevious.ATFolderNextPrevious"
            provides=".interfaces.INextPreviousProvider" /> 

Finally, we created a view interface which defines the methods required to mediate between the browser page requests and the object architecture.

class INextPreviousView(Interface):
    def next():
        """Get the next item, or None if there is no such item"""
    def previous():
        """Get the previous  item, or None if there is no such item"""
    def enabled():
        """Find out if the navigation is enabled"""

The advantages of the implemation is e.g. that we dont have to store a lot of methods in the ATFolder it self and that we have a very simple page template. When we have declared the view we can use the methods declared in the INextPreviousView:

<tal:nextPrevious metal:define-macro="navigation" 
                  tal:define="view context/@@nextprevious_view;
                              viewEnabled view/enabled|nothing"
                  tal:condition="python:viewEnabled and isViewTemplate">

To visualize our implementation we have modeled it:

Deliverables

• Unit tests are done (tests/testNewsPortletView.py)
• i18n tags have been implemented
• documentation beside the description of the implementation is missing
  

Risks

As fare as we can see there is no bigger risk in the implementation.

We have not run any benchmarking so we cant provide any information in that context related to performance etc.

The implementation could be optimized in the way we have to called "the view / multi adapter" (context/@@nextprevious_view) twize:

• In the header.pt
• In the nextprevious_nav.pt
  

Participants

Pelle Krøgholt
Souheil Chelfouh
Henrietta Ray