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()

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_localized_time(datetime=None, long_format=False, time_only=False)

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)

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)

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
Returns:

Registry record value
Return type:

plone.app.registry registry record

Example:

Get plone.app.registry record

plone.api.portal.get_tool(name=None)

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)

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)

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')

Display a status message.

Parameters:
  • message (string) -- [required] Message to show.
  • request (TODO: hm?) -- [required] Request.
  • type (string) -- Message type. Possible values: 'info', 'warn', 'error'
Raises:

ValueError
Example:

Show notification message