Create content

First get the portal object that we will use as a container for new content:

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

If you want to create a new content item, use the api.content.create() method. The type attribute will automatically decide which content type (dexterity, archetype, ...) should be created.

from plone import api
obj = api.content.create(
    title='My Content',

The id of the object gets generated (in a safe way) from its title.

assert == 'my-content'

Get content object

There are several approaches of getting to your content object. Consider the following portal structure:

plone (portal root)
|-- blog
|-- about
|   |-- team
|   `-- contact
`-- events
    |-- training
    |-- conference
    `-- sprint

You can do the following operations to get to various content objects in the stucture above, including using api.content.get().

# let's first get the portal object
from plone import api
portal = api.portal.get()
assert == 'plone'

# content can be accessed directly with dict-like access
blog = portal['blog']

# another way is to use ``get()`` method and pass it a path
about = api.content.get(path='/about')

# more examples
conference = portal['events']['conference']
sprint = api.content.get(path='/events/sprint')

# moreover, you can access content by it's UID
uid = about['team'].UID()
conference = api.content.get(UID=uid)

Find content object

You can use the catalog to search for content. Here is a simple example:

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

More about how to use the catalog and what parameters it supports is written in the Collective Developer Documentation. Note that the catalog returns brains (metadata stored in indexes) and not objects. However, calling getObject() on brains does in fact give you the object.

document_brain = documents[0]
document_obj = document_brain.getObject()
assert document_obj.__class__.__name__ == 'ATDocument'

Move content

To move content around the portal structure defined above use api.content.move() The code below moves the contact item (with all objects that it contains) out of folder about into the Plone portal root.

from plone import api
portal = api.portal.get()
contact = portal['about']['contact']

api.content.move(source=contact, target=portal)

Actually, move behaves like a filesystem move. If you pass it an id argument, you can define to what target ID the object will be moved to. Otherwise it will be moved with the same ID that it had.

Rename content

To rename, you still use the api.content.move() method, just pass in a new id instead and omit target.

from plone import api
portal = api.portal.get()
api.content.move(source=portal['blog'], id='old-blog')

Copy content

To copy a content object, use the api.content.copy().

from plone import api
portal = api.portal.get()
training = portal['events']['training']

api.content.copy(source=training, target=portal)

Note that the new object will have the same id as the old object (if not stated otherwise). This is not a problem, since the new object is in a different container.

You can also omit target and set strict=False which will duplicate your content object in the same container and assign it a non-conflicting id.

api.content.copy(source=training, target=portal['events'], strict=False)
new_training = portal['events']['copy_of_training']

Delete content

Deleting content works by passing the object you want to delete to the api.content.delete() method:

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

Content manipulation with strict option

When manipulating content with api.content.create(), api.content.move() and api.content.copy() the strict option is enabled by default. This means the id will be enforced, if the id is taken on the target container the API method will raise an error.

api.content.create(container=portal, type='Document', id='non-strict-usage')

If the strict option is disabled a non-conflicting id will be created.

Get workflow state

To find out in which workflow state your content is, use api.content.get_state().

from plone import api
portal = api.portal.get()
state = api.content.get_state(obj=portal['about'])


To transition your content into a new state, use api.content.transition().

from plone import api
portal = api.portal.get()
state = api.content.transition(obj=portal['about'], transition='publish')

Browser view

To get a BrowserView for your content, use api.content.get_view().

from plone import api
portal = api.portal.get()
view = api.content.get_view(

Further reading

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

Project Versions

Table Of Contents

Previous topic


Next topic


This Page