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.

plone.api.portal

Module that provides various utility methods on the portal level.

plone.api.portal.get()[source]

Get the Plone portal object out of thin air.

Without the need to import fancy Interfaces and doing multi adapter lookups.

Returns:

Plone portal object

Return type:

Portal object

Example:

Get portal object

plone.api.portal.get_current_language(context=None)[source]

Return the current negotiated language.

Parameters:

context (object) – context object

Returns:

language identifier

Return type:

string

Example:

Get current language

plone.api.portal.get_default_language()[source]

Return the default language.

Returns:

language identifier

Return type:

string

Example:

Get default language

plone.api.portal.get_localized_time(datetime=None, long_format=False, time_only=False)[source]

Display a date/time in a user-friendly way.

It should be localized to the user’s preferred language.

Note that you can specify both long_format and time_only as True (or any other value that can be converted to a boolean True value), but time_only then wins: the long_format value is ignored.

You can also use datetime.datetime or datetime.date instead of Plone’s DateTime. In case of datetime.datetime everything works the same, in case of datetime.date the long_format parameter is ignored and on time_only an empty string is returned.

Parameters:

  • datetime (DateTime, datetime or date) – [required] Message to show.

  • long_format (boolean) – When true, show long date format. When false (default), show the short date format.

  • time_only (boolean) – When true, show only the time, when false (default), show the date.

Returns:

Localized time

Return type:

string

Raises:

ValueError

Example:

Get localized time

plone.api.portal.get_navigation_root(context=None)[source]

Get the navigation root object for the context.

This traverses the path up and returns the nearest navigation root. Useful for multi-lingual installations and sites with subsites.

Parameters:

context (context object) – [required] Context on which to get the navigation root.

Returns:

Navigation Root

Return type:

Portal object

Example:

Get navigation root

plone.api.portal.get_registry_record(name=None, interface=None, default=<object object>)[source]

Get a record value from plone.app.registry

Parameters:

  • name (string) – [required] Name

  • interface (zope.interface.Interface) – interface whose attributes are plone.app.registry settings

  • default (anything) – The value returned if the record is not found

Returns:

Registry record value

Return type:

plone.app.registry registry record

Example:

Get plone.app.registry record

plone.api.portal.get_tool(name=None)[source]

Get a portal tool in a simple way.

Parameters:

name (string) – [required] Name of the tool you want.

Returns:

The tool that was found by name

Raises:

MissingParameterError, InvalidParameterError

Example:

Get tool

plone.api.portal.send_email(sender=None, recipient=None, subject=None, body=None, immediate=False)[source]

Send an email.

Parameters:

  • sender (string) – Email sender, ‘from’ field. If not set, the portal default will be used.

  • recipient (string) – [required] Email recipient, ‘to’ field.

  • subject (string) – [required] Subject of the email.

  • body (boolean) – [required] Body text of the email

  • immediate – Send immediate or queued at transaction commit time. When sending immediate the mail might get sent out multiple time in case of transaction aborts and retries.

Raises:

ValueError

Example:

Send E-Mail

plone.api.portal.set_registry_record(name=None, value=None, interface=None)[source]

Set a record value in the plone.app.registry

Parameters:

  • name (string) – [required] Name of the record

  • value (python primitive) – [required] Value to set

  • interface (zope.interface.Interface) – interface whose attributes are plone.app.registry settings

Example:

Set plone.app.registry record

plone.api.portal.show_message(message=None, request=None, type='info')[source]

Display a status message.

Parameters:

  • message (string) – [required] Message to show.

  • request (HTTPRequest) – [required] Request.

  • type (string) – Message type. Possible values: ‘info’, ‘warn’, ‘error’

Raises:

ValueError

Example:

Show notification message

plone.api.portal.translate(msgid, domain='plone', lang=None)[source]

Translate a message into a given language.

Default to current negotiated language if no target language specified.

Parameters:

  • msgid (string) – [required] message to translate

  • domain (string) – i18n domain to use

  • lang (string) – target language

Returns:

translated message

Return type:

six.text_type

Example:

Translate