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#

TypesManager.

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#

BlockTypesManager.

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#

VocabulariesManager.

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