portal.rst

WARNING: If you are reading this on GitHub, DON'T! Read it on ReadTheDocs:

http://ploneapi.readthedocs.org/en/latest/portal.html so you have working

references and proper formatting.

.. module:: plone

Portal

Get portal object

Getting the Plone portal object is easy with :meth:`api.portal.get`.

from plone import api
portal = api.portal.get()

Get navigation root

In multi-lingual Plone installations you probably want to get the language-specific navigation root object, not the top portal object. You do this with :meth:`api.portal.get_navigation_root()`.

Assuming there is a document english_page in a folder en, which is the navigation root:

from plone import api
nav_root = api.portal.get_navigation_root(english_page)

returns the folder en. If the folder en is not a navigation root it would return the portal.

Get portal url

Since we now have the portal object, it's easy to get the portal url.

from plone import api
url = api.portal.get().absolute_url()

Get tool

To get a portal tool in a simple way, just use :meth:`api.portal.get_tool` and pass in the name of the tool you need.

from plone import api
catalog = api.portal.get_tool(name='portal_catalog')

Get localized time

To display the date/time in a user-friendly way, localized to the user's prefered language, use :meth:`api.portal.get_localized_time`.

from plone import api
from DateTime import DateTime
today = DateTime()
api.portal.get_localized_time(datetime=today)

Send E-Mail

To send an e-mail use :meth:`api.portal.send_email`:

from plone import api
api.portal.send_email(
    recipient="bob@plone.org",
    sender="noreply@plone.org",
    subject="Trappist",
    body="One for you Bob!",
)

Show notification message

With :meth:`api.portal.show_message` you can show a notification message to the user.

from plone import api
api.portal.show_message(message='Blueberries!', request=request)

Get plone.app.registry record

Plone comes with a package plone.app.registry that provides a common way to store various configuration and settings. :meth:`api.portal.get_registry_record` provides an easy way to access these.

from plone import api
api.portal.get_registry_record('my.package.someoption')

Set plone.app.registry record

Plone comes with a package plone.app.registry that provides a common way to store various configuration and settings. :meth:`api.portal.set_registry_record` provides an easy way to change these.

from plone import api
api.portal.set_registry_record('my.package.someoption', False)

Further reading

For more information on possible flags and usage options please see the full :ref:`plone-api-portal` specification.