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)

Since version 2.0.0, the request argument can be omitted. In that case, the global request will be used.

api.portal.show_message(message='Cranberries!')

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='bar')
api.portal.get_registry_record('foo', default='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', 'new value', interface=IMyRegistrySettings)

Further reading

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