Types and vocabularies#
Read the content types of a site, the blocks it offers, and the valid values of its fields.
The examples that change a schema create a type of their own first, because the schema of a type must live in the site, not in code, to change it through the API.
client.block_types asks the Volto server, so it needs frontend_url; see Block types.
Each example uses the client from How to read these pages.
client.types#
Content types and their JSON schemas (@types).
client.types.list#
Content types, with whether they can be added in a folder.
See list().
Calls GET /news/@types (plone.restapi documentation).
client.types.list("/news")
plone-client types --addable-in /news -c
["Event", "File", "Image", "Link", "News Item", "Document"]
GET /Plone/++api++/news/@types HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/news/@types -H 'accept: application/json' -u admin:admin
[
{
"@id": "http://localhost:8080/Plone/@types/Collection",
"addable": false,
"title": "Collection"
},
{
"@id": "http://localhost:8080/Plone/@types/Event",
"addable": true,
"title": "Event"
},
{
"@id": "http://localhost:8080/Plone/@types/File",
"addable": true,
"title": "File"
}
]
This shows only @id, title, addable of each entry. This shows 3 of 8 entries.
client.types.addable#
Ids of the content types that can be added in a folder.
See addable().
Calls GET /news/@types (plone.restapi documentation).
client.types.addable("/news")
GET /Plone/++api++/news/@types HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/news/@types -H 'accept: application/json' -u admin:admin
[
"Event",
"File",
"Image",
"Link",
"News Item",
"Document"
]
client.types.get#
JSON schema of a content type.
See get().
Calls GET /@types/News Item (plone.restapi documentation).
client.types.get("News Item")
plone-client types "News Item" -f title,required
{
"title": "News Item",
"required": [
"title"
]
}
GET /Plone/++api++/@types/News%20Item HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@types/News%20Item -H 'accept: application/json' -u admin:admin
{
"required": [
"title"
],
"title": "News Item"
}
This shows only title, required.
client.types.create_field#
Add a field (or, with fieldset data, a fieldset) to a type.
See create_field().
Calls POST /@types/sample (plone.restapi documentation).
client.types.create_field(
"sample",
{"factory": "Text line (String)", "title": "Short name", "required": False},
)
POST /Plone/++api++/@types/sample HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"factory": "Text line (String)",
"title": "Short name",
"required": false
}
curl -i -X POST http://localhost:8080/Plone/++api++/@types/sample -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"factory":"Text line (String)","title":"Short name","required":false}'
{
"factory": "Text line (String)",
"title": "Short name"
}
This shows only title, factory.
client.types.get_field#
Schema of one field or fieldset of a content type.
See get_field().
Calls GET /@types/sample/short_name (plone.restapi documentation).
client.types.get_field("sample", "short_name")
GET /Plone/++api++/@types/sample/short_name HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@types/sample/short_name -H 'accept: application/json' -u admin:admin
{
"factory": "Text line (String)",
"title": "Short name",
"type": "string"
}
This shows only title, type, factory.
client.types.update#
Change a type’s schema, or one of its fields or fieldsets.
See update().
Calls PATCH /@types/sample/short_name (plone.restapi documentation).
client.types.update("sample", {"title": "Nickname"}, name="short_name")
PATCH /Plone/++api++/@types/sample/short_name HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"title": "Nickname"
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/@types/sample/short_name -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"title":"Nickname"}'
The site answers 204, and the method returns None.
client.types.replace#
Replace a type’s schema.
See replace().
Calls GET /@types/sample, PUT /@types/sample (plone.restapi documentation).
schema = client.types.get("sample")
client.types.replace("sample", schema)
GET /Plone/++api++/@types/sample HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
PUT /Plone/++api++/@types/sample HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"fieldsets": [
{
"behavior": "plone",
"fields": [
"title",
"description",
"short_name"
],
"id": "default",
"title": "Default"
},
{
"behavior": "plone",
"description": "",
"fields": [
"subjects",
"language"
],
"id": "categorization",
"title": "Categorization"
},
{
"behavior": "plone",
"description": "",
"fields": [
"effective",
"expires"
],
"id": "dates",
"title": "Dates"
},
{
"behavior": "plone",
"description": "",
"fields": [
"creators",
"contributors",
"rights"
],
"id": "ownership",
"title": "Ownership"
}
],
"layouts": [
"view"
],
"properties": {
"contributors": {
"additionalItems": true,
"behavior": "plone.dublincore",
"description": "The names of people that have contributed to this item. Each contributor should be on a separate line.",
"factory": "Tuple",
"items": {
"description": "",
"factory": "Text line (String)",
"title": "",
"type": "string"
},
"title": "Contributors",
"type": "array",
"uniqueItems": true,
"widgetOptions": {
"vocabulary": {
"@id": "http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Users"
}
}
},
"creators": {
"additionalItems": true,
"behavior": "plone.dublincore",
"description": "Persons responsible for creating the content of this item. Please enter a list of user names, one per line. The principal creator should come first.",
"factory": "Tuple",
"items": {
"description": "",
"factory": "Text line (String)",
"title": "",
"type": "string"
},
"title": "Creators",
"type": "array",
"uniqueItems": true,
"widgetOptions": {
"vocabulary": {
"@id": "http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Users"
}
}
},
"description": {
"behavior": "plone.dublincore",
"description": "Used in item listings and search results.",
"factory": "Text",
"maxLength": 10000,
"title": "Summary",
"type": "string",
"widget": "textarea"
},
"effective": {
"behavior": "plone.dublincore",
"description": "If this date is in the future, the content will not show up in listings and searches until this date.",
"factory": "Date/Time",
"title": "Publishing Date",
"type": "string",
"widget": "datetime"
},
"expires": {
"behavior": "plone.dublincore",
"description": "When this date is reached, the content will no longer be visible in listings and searches.",
"factory": "Date/Time",
"title": "Expiration Date",
"type": "string",
"widget": "datetime"
},
"language": {
"behavior": "plone.dublincore",
"default": "en",
"description": "",
"factory": "Choice",
"title": "Language",
"type": "string",
"vocabulary": {
"@id": "http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.SupportedContentLanguages"
}
},
"rights": {
"behavior": "plone.dublincore",
"description": "Copyright statement or other rights information on this item.",
"factory": "Text",
"title": "Rights",
"type": "string",
"widget": "textarea"
},
"short_name": {
"behavior": "plone.dexterity.schema.generated.Plone_5_1793501264_2_3879833_0_sample",
"description": "",
"factory": "Text line (String)",
"title": "Nickname",
"type": "string"
},
"subjects": {
"additionalItems": true,
"behavior": "plone.dublincore",
"description": "Tags are commonly used for ad-hoc organization of content.",
"factory": "Tuple",
"items": {
"description": "",
"factory": "Text line (String)",
"title": "",
"type": "string"
},
"title": "Tags",
"type": "array",
"uniqueItems": true,
"widgetOptions": {
"vocabulary": {
"@id": "http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Keywords"
}
}
},
"title": {
"behavior": "plone.dublincore",
"description": "",
"factory": "Text line (String)",
"maxLength": 1024,
"title": "Title",
"type": "string"
}
},
"required": [
"title"
],
"title": "Sample",
"type": "object"
}
curl -i -X GET http://localhost:8080/Plone/++api++/@types/sample -H 'accept: application/json' -u admin:admin
curl -i -X PUT http://localhost:8080/Plone/++api++/@types/sample -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"fieldsets":[{"behavior":"plone","fields":["title","description","short_name"],"id":"default","title":"Default"},{"behavior":"plone","description":"","fields":["subjects","language"],"id":"categorization","title":"Categorization"},{"behavior":"plone","description":"","fields":["effective","expires"],"id":"dates","title":"Dates"},{"behavior":"plone","description":"","fields":["creators","contributors","rights"],"id":"ownership","title":"Ownership"}],"layouts":["view"],"properties":{"contributors":{"additionalItems":true,"behavior":"plone.dublincore","description":"The names of people that have contributed to this item. Each contributor should be on a separate line.","factory":"Tuple","items":{"description":"","factory":"Text line (String)","title":"","type":"string"},"title":"Contributors","type":"array","uniqueItems":true,"widgetOptions":{"vocabulary":{"@id":"http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Users"}}},"creators":{"additionalItems":true,"behavior":"plone.dublincore","description":"Persons responsible for creating the content of this item. Please enter a list of user names, one per line. The principal creator should come first.","factory":"Tuple","items":{"description":"","factory":"Text line (String)","title":"","type":"string"},"title":"Creators","type":"array","uniqueItems":true,"widgetOptions":{"vocabulary":{"@id":"http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Users"}}},"description":{"behavior":"plone.dublincore","description":"Used in item listings and search results.","factory":"Text","maxLength":10000,"title":"Summary","type":"string","widget":"textarea"},"effective":{"behavior":"plone.dublincore","description":"If this date is in the future, the content will not show up in listings and searches until this date.","factory":"Date/Time","title":"Publishing Date","type":"string","widget":"datetime"},"expires":{"behavior":"plone.dublincore","description":"When this date is reached, the content will no longer be visible in listings and searches.","factory":"Date/Time","title":"Expiration Date","type":"string","widget":"datetime"},"language":{"behavior":"plone.dublincore","default":"en","description":"","factory":"Choice","title":"Language","type":"string","vocabulary":{"@id":"http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.SupportedContentLanguages"}},"rights":{"behavior":"plone.dublincore","description":"Copyright statement or other rights information on this item.","factory":"Text","title":"Rights","type":"string","widget":"textarea"},"short_name":{"behavior":"plone.dexterity.schema.generated.Plone_5_1793501264_2_3879833_0_sample","description":"","factory":"Text line (String)","title":"Nickname","type":"string"},"subjects":{"additionalItems":true,"behavior":"plone.dublincore","description":"Tags are commonly used for ad-hoc organization of content.","factory":"Tuple","items":{"description":"","factory":"Text line (String)","title":"","type":"string"},"title":"Tags","type":"array","uniqueItems":true,"widgetOptions":{"vocabulary":{"@id":"http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Keywords"}}},"title":{"behavior":"plone.dublincore","description":"","factory":"Text line (String)","maxLength":1024,"title":"Title","type":"string"}},"required":["title"],"title":"Sample","type":"object"}'
The site answers 204, and the method returns None.
client.types.delete_field#
Remove a field or fieldset from a type.
See delete_field().
Calls DELETE /@types/sample/short_name (plone.restapi documentation).
client.types.delete_field("sample", "short_name")
DELETE /Plone/++api++/@types/sample/short_name HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X DELETE http://localhost:8080/Plone/++api++/@types/sample/short_name -H 'accept: application/json' -u admin:admin
The site answers 204, and the method returns None.
client.block_types#
The blocks a Volto site offers (@blocks-schema of the Volto server).
client.block_types.list#
The blocks of the site, with their title and summary.
See list().
Calls POST /@login, GET /@blocks-schema.
client.block_types.list()
plone-client block-types -f source
{
"source": "site"
}
POST /Plone/++api++/@login HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"login": "admin",
"password": "admin"
}
GET /@blocks-schema HTTP/1.1
Host: localhost:3000
Accept: application/json
Authorization: Bearer TOKEN
curl -i -X POST http://localhost:8080/Plone/++api++/@login -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"login":"admin","password":"admin"}'
{
"items": [
{
"id": "title",
"title": "Title"
},
{
"id": "description",
"title": "Description"
},
{
"id": "image",
"title": "Image"
}
],
"items_total": 15,
"source": "site"
}
This shows only source, items, items_total. This shows only id, title of each entry. This shows 3 of 15 entries.
client.block_types.get#
One block: its documentation, data schema and variations.
See get().
Calls GET /@blocks-schema/teaser.
client.block_types.get("teaser")
plone-client block-types teaser -f id,title
{
"id": "teaser",
"title": "Teaser"
}
GET /@blocks-schema/teaser HTTP/1.1
Host: localhost:3000
Accept: application/json
Authorization: Bearer TOKEN
{
"id": "teaser",
"title": "Teaser",
"source": "site"
}
This shows only id, title, source.
client.block_types.markdown#
The list of blocks, or one block, as Markdown.
See markdown().
Calls GET /@blocks-schema/title.
client.block_types.markdown("title").splitlines()[0]
plone-client block-types title --markdown | head -1
## Title (`title`)
GET /@blocks-schema/title HTTP/1.1
Host: localhost:3000
Accept: text/markdown
Authorization: Bearer TOKEN
"## Title (`title`)"
client.vocabularies#
Vocabularies and field sources.
client.vocabularies.list#
Named vocabularies registered on the site.
See list().
Calls GET /@vocabularies (plone.restapi documentation).
client.vocabularies.list()
GET /Plone/++api++/@vocabularies HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@vocabularies -H 'accept: application/json' -u admin:admin
[
{
"@id": "http://localhost:8080/Plone/@vocabularies/plone.contentrules.events",
"title": "plone.contentrules.events"
},
{
"@id": "http://localhost:8080/Plone/@vocabularies/Behaviors",
"title": "Behaviors"
}
]
This shows only @id, title of each entry. This shows 2 of 50 entries.
client.vocabularies.get#
Terms of a vocabulary, a page at a time.
See get().
Calls GET /@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes (plone.restapi documentation).
client.vocabularies.get("plone.app.vocabularies.ReallyUserFriendlyTypes", title="news")
plone-client vocabulary plone.app.vocabularies.ReallyUserFriendlyTypes --title news
[
{
"title": "News Item",
"token": "News Item"
}
]
GET /Plone/++api++/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=news HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=news' -H 'accept: application/json' -u admin:admin
{
"items": [
{
"title": "News Item",
"token": "News Item"
}
],
"items_total": 1
}
This shows only items, items_total.
client.vocabularies.iter#
Every term of a vocabulary.
See iter().
Calls GET /@vocabularies/plone.app.vocabularies.WorkflowStates (plone.restapi documentation).
list(client.vocabularies.iter("plone.app.vocabularies.WorkflowStates"))
GET /Plone/++api++/@vocabularies/plone.app.vocabularies.WorkflowStates?b_size=100 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@vocabularies/plone.app.vocabularies.WorkflowStates?b_size=100' -H 'accept: application/json' -u admin:admin
[
{
"title": "Externally visible [external]",
"token": "external"
},
{
"title": "Internal draft [internal]",
"token": "internal"
},
{
"title": "Internally published [internally_published]",
"token": "internally_published"
}
]
This shows 3 of 7 entries.
client.vocabularies.source#
Terms of the source of a field (@sources).
See source().
Calls GET /about/@sources/my_field (plone.restapi documentation).
Note
This example was not run against a site, because no field of the default content types has an iterable source. The request below was built, and not sent.
client.vocabularies.source("/about", "my_field")
GET /Plone/++api++/about/@sources/my_field HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/about/@sources/my_field -H 'accept: application/json' -u admin:admin
client.vocabularies.querysource#
Terms of a query source matching a text (@querysources).
See querysource().
Calls GET /about/@querysources/my_field (plone.restapi documentation).
Note
This example was not run against a site, because no field of the default content types has a query source. The request below was built, and not sent.
client.vocabularies.querysource("/about", "my_field", "plone")
GET /Plone/++api++/about/@querysources/my_field?query=plone HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/about/@querysources/my_field?query=plone' -H 'accept: application/json' -u admin:admin