Helper views and tools


This document explains how to access view and context utilities in Plone.

IPortalState and IContextState

IPortalState defines IContextState view-like interfaces to access miscellaneous information useful for the rendering of the current page. The views are cached properly, so they should access the information quite effectively.

  • IPortalState is mapped as the plone_portal_state name view.
  • IContextState is mapped as the plone_context_state named view.
  • ITools is mapped as the plone_tools named view.

To see what's available through the interface, read the documentation in the module.

Example showing how to get the portal root URL:

from zope.component import getMultiAdapter

class MyView(BrowserView):


    def __call__(self):
        # aq_inner is needed in some cases like in the portlet renderers
        # where the context itself is a portlet renderer and it's not on the
        # acquisition chain leading to the portal root.
        # If you are unsure what this means always use context.aq_inner
        context = self.context.aq_inner
        portal_state = getMultiAdapter((context, self.request), name=u'plone_portal_state')

        self.some_url = portal_state.portal_url() + "/my_foo_bar"

Example showing how to get the current language:

from zope.component import getMultiAdapter


portal_state = getMultiAdapter((self.context, self.request), name=u'plone_portal_state')
current_language = portal_state.language()

Example showing how to expose portal_state helper to a template:

  1. ZCML includes portal_state in allowed_attributes

A Python class exposes the variable:

from Acquisition import aq_inner
from zope.component import getMultiAdapter

class MyView(BrowserView):

    def portal_state(self):
        context = aq_inner(self.context)
        portal_state = getMultiAdapter((context, self.request), name=u'plone_portal_state')
        return portal_state

Templates can use it as follows:

    The language is <span tal:content="view/portal_state/language" />

You can directly look up portal_state in templates using acquisition and view traversal, without need of ZCML code or Python view code changes. This is useful e.g. in overridden viewlet templates:


    During traversal, ``@@`` signals that the traversing
    machinery should look up a view by that name.

    First we look up the view and then use
    it to access the variables defined in
    ``IPortalState`` interface.


<div tal:define="portal_state context/@@plone_portal_state" >
    The language is <span tal:content="portal_state/language" />

Use in templates and expressions

You can use IContextState and IPortalState in TALES expressions, e.g. portal_actions, as well.

Example portal_actions conditional expression:

python:object.restrictedTraverse('@@plone_portal_state').language() == 'fi'


Tools are persistent utility classes available in the site root. They are visible in the ZMI, and sometimes expose useful information or configuration here. Tools include e.g.:

Search and indexing facilities for content
Look up workflow status, and do workflow-related actions.
User registration information.

ITools interface interface and Tools BrowserView provide cached access for the most commonly needed tools.

ITools is mapped as the plone_tools view for traversing.


from Acquisition import aq_inner
from zope.component import getMultiAdapter

context = aq_inner(self.context)
tools = getMultiAdapter((context, self.request), name=u'plone_tools')

portal_url = tools.url()

# The root URL of the site is got by using portal_url.__call__()
# method

the_current_root_url_of_the_site = portal_url()


Products.CMFPlone.browser.interfaces.IPlone provides some helper methods for Plone specific functionality and user interface.

  • IPlone helper views is registered under the name plone


getToolByName is the old-fashioned way of getting tools, using the context object as a starting point. It also works for tools which do not implement the ITools interface.

getToolByName gets any Plone portal root item using acquisition.


from Products.CMFCore.WorkflowCore import WorkflowException

# Do the workflow transition "submit" for the current context
workflowTool = getToolByName(self.context, "portal_workflow")
workflowTool.doActionFor(self.context, "submit")