Content model#
This page describes the shape of content on a Plone 6 site as plone.restapi returns it, and as plone-client writes it.
The answers below come from the Compose site, a site created for Volto on Plone 6.1.
Other sites can have other content types and fields; client.types.get() tells you what a site has.
Content types#
The Page type has the id Document.
On a Volto site, Folder exists but cannot be added, and Document and News Item are folderish.
from plone_client import PloneClient
client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
for item in client.types.list():
print(item["title"], item["addable"])
print(client.types.addable("/news"))
print(client.content.get("/news")["is_folderish"])
print(client.content.get("/news/release-6-2")["is_folderish"])
Collection False
Event True
File True
Folder False
Image True
Link True
News Item True
Page True
['Event', 'File', 'Image', 'Link', 'News Item', 'Document']
True
True
Field of |
Meaning |
|---|---|
|
The title people see, which can differ from the id. |
|
Whether this user can add the type at this path. |
Fields#
Each type has a JSON schema, which lists its fields in properties.
from plone_client import PloneClient
client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
for portal_type in ("Document", "News Item", "Image", "File"):
fields = client.types.get(portal_type)["properties"]
print(portal_type, [name for name in ("blocks", "image", "file", "preview_image_link") if name in fields])
Document ['blocks', 'preview_image_link']
News Item ['blocks', 'preview_image_link']
Image ['image']
File ['file', 'preview_image_link']
plone.restapi silently ignores a field that the type does not have, and answers with success.
from plone_client import PloneClient
client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
item = client.content.create("/", "Document", id="ignored", title="Ignored", colour="red")
print(item["title"], "colour" in item)
client.content.delete("/ignored")
Ignored False
Blocks#
An item with blocks stores its content in two fields.
Field |
Content |
|---|---|
|
A mapping of block ids to block data, each with an |
|
|
Volto shows a page without both as empty.
create() sends what you give it, so it adds no blocks.
The create command, the create_content tool, and the operations add a title block and a description block; see Operations.
build returns both fields with new ids.
from plone_client import blocks
import json
page = blocks.build(blocks.title(), blocks.description(), blocks.text("Hello!"))
print(json.dumps(list(page["blocks"].values()), indent=2))
print(sorted(page), len(page["blocks_layout"]["items"]))
[
{
"@type": "title"
},
{
"@type": "description"
},
{
"@type": "slate",
"plaintext": "Hello!",
"value": [
{
"type": "p",
"children": [
{
"text": "Hello!"
}
]
}
]
}
]
['blocks', 'blocks_layout'] 3
The title and description blocks hold no text: they show the fields of the item.
A block that holds others keeps blocks and blocks_layout of its own, as gridBlock does.
Some add-on blocks keep them inside data, and the walking helpers of Block helpers follow both.
The slate value#
The value of a slate block is a list of nodes, each with a type and children, down to objects with text.
plaintext repeats the text without markup.
from plone_client import blocks
import json
page = blocks.convert("Plain and **bold**.\n\n- One item\n")
print(json.dumps([block["value"] for block in page["blocks"].values()], indent=2))
[
[
{
"type": "p",
"children": [
{
"text": "Plain and "
},
{
"type": "strong",
"children": [
{
"text": "bold"
}
]
},
{
"text": "."
}
]
}
],
[
{
"type": "ul",
"children": [
{
"type": "li",
"children": [
{
"text": "One item"
}
]
}
]
}
]
]
Lead image#
Where an item keeps its lead image depends on the site.
Site |
Field |
Value |
|---|---|---|
Created for Volto |
|
A relation to an |
Classic UI |
|
The image itself. |
The same News Item type has either one, so read the schema.
create_with_files() does this for you.
from plone_client import PloneClient
from plone_client import file_data
from seed import png
client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
image = client.files.upload("/news/release-6-2", png(0, 90, 0), filename="lead.png")
item = client.content.update("/news/release-6-2", preview_image_link=image["UID"])
link = item["preview_image_link"]
print(link["@id"], link["@type"], link["title"])
http://localhost:8080/Plone/news/release-6-2/lead.png Image lead.png
You send a UID, and the site answers with an object.
An Image keeps its file in the image field and a File in the file field.
Each answers with content-type, filename, size, and a download URL, and an image also with width, height, and scales.
Workflow#
The workflow of a site decides the review_state of each item.
New items start private, and only people with a role on them can see them.
from plone_client import PloneClient
site = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
visitor = PloneClient("http://localhost:8080/Plone")
for item in site.search.iter("/news", portal_type="News Item", sort_on="sortable_title"):
print(item["review_state"], item["title"])
print("Visitors see", visitor.search.count("/news", portal_type="News Item"))
print(site.workflow.get("/news/release-party")["transitions"][0]["title"])
published Old announcement
published Release 6.2 is out
private Release notes draft
private Release party in Brasília
pending Sprint report
Visitors see 2
Publish
Image and File items have no workflow: their review_state is null, and they follow the item that holds them.
Dates#
Field |
Meaning |
|---|---|
|
Set by the site. |
|
The publication date. Publishing sets it when it is empty. |
|
The date the item stops appearing in searches for visitors. |
The site refuses an expires date before the effective date.
from plone_client import PloneClient
site = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
visitor = PloneClient("http://localhost:8080/Plone")
print(site.content.get("/news/release-party")["effective"])
print(visitor.search.count("/news", portal_type="News Item"))
dates = {"effective": "2019-01-01T00:00:00", "expires": "2020-01-01T00:00:00"}
site.content.update("/news/old-announcement", dates)
print(site.content.get("/news/old-announcement")["review_state"])
print(visitor.search.count("/news", portal_type="News Item"))
None
2
published
1
Links between items#
Each content item has a UID, which stays the same when the item moves. resolveuid links point to the UID, and Volto stores internal links that way. Everything in plone-client that takes a ref accepts both forms.
from plone_client import PloneClient
from plone_client.utils import resolveuid_url
client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
uid = client.content.get("/about/team")["UID"]
link = resolveuid_url(uid)
print(link)
print(client.content.resolve(f"uid:{uid}"))
print(client.content.resolve(link))
../resolveuid/b04bfdfc710c462cac035ca85edd3b37
/about/team
/about/team