GitHub-only

WARNING: If you are reading this on GitHub, DON’T! Read the documentation at docs.plone.org so you have working references and proper formatting.

Portal

Get portal object

Getting the Plone portal object is easy with api.portal.get().

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

Get navigation root

In multilingual or multi-site Plone installations you probably want to get the language-specific navigation root object, not the top portal object.

You do this with 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 easily, use 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 preferred language, use api.portal.get_localized_time().

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

Get default language

To get the default language, use api.portal.get_default_language().

from plone import api
lang = api.portal.get_default_language()

Get current language

To get the currently negotiated language, use api.portal.get_current_language().

from plone import api
lang = api.portal.get_current_language()

Translate

To translate a message in a given language, use api.portal.translate().

from plone import api
msg = api.portal.translate('Edited', lang='es')

Send E-Mail

To send an e-mail use 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!",
)

If you need to add other fields not supported on send_email signature, Python’s standard email module can also be used:

from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

message = MIMEMultipart()
message.attach(MIMEText("One for you Bar!"))

part = MIMEText('<xml></xml>', 'xml')
part.add_header(
    'Content-Disposition',
    'attachment; filename="report.xml"'
)
message.attach(part)

message['Reply-To'] = "community@plone.org"

api.portal.send_email(
    recipient="bob@plone.org",
    sender="noreply@plone.org",
    subject="Trappist",
    body=message,
)

Show notification message

With 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 configuration and settings. api.portal.get_registry_record() provides an easy way to access these.

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

One common pattern when using registry records is to define an interface with all the settings. api.portal.get_registry_record() also allows you to use this pattern.

from plone import api
api.portal.get_registry_record('field_one', interface=IMyRegistrySettings)

It is possible to provide a default value that will be returned by api.portal.get_registry_record() if the queried record is not found.

from plone import api
api.portal.get_registry_record('foo', interface=IMyRegistrySettings, default=u'bar')
api.portal.get_registry_record('foo', default=u'baz')

Set plone.app.registry record

api.portal.set_registry_record() provides an easy way to change plone.app.registry configuration and settings.

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

api.portal.set_registry_record() allows you to define an interface with all the settings.

from plone import api
api.portal.set_registry_record('field_one', u'new value', interface=IMyRegistrySettings)

Further reading

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