This documentation provides a comprehensive guide to interacting with shared content elements via the GraphQL API. Developers can leverage these queries and mutations to efficiently manage and retrieve shared content within their applications, similar to how GraphQL pages are managed.
Table of Contents:
The Element type represents a shared content element. It has the following fields:
id: ID! - Unique element ID.type: String! - Type of the content element.lang: String - ISO language code, e.g., 'en', 'en-GB' or empty for default language.name: String - Arbitrary string which describes the content element.data: JSON! - Arbitrary content element.editor: String! - Name of the last user who added, updated or deleted the content element.created_at: String! - Date/time value when the content element was created.updated_at: String! - Date/time value when the content element was last modified.deleted_at: String - Date/time value when the content element was deleted or NULL if it's available.bypages: [Page!]! - List of pages using the content element.byversions: [Version!]! - List of versions using the content element.files: [File!]! - List of files assigned to the content element.versions: [Version!]! - List of versioned data for the content element.latest: Version - Latest version of the content element.published: Version - Published version of the content element.Used to filter elements queries.
id: [ID!] - Unique element IDs.type: String - Type of the content elements.lang: String - ISO language code, e.g., 'en', 'en-GB' or empty for default language.name: String - Arbitrary string which describes the content elements.data: String - Arbitrary content elements.editor: String - Name of the last user who added, updated or deleted the content elements.any: String - Search for this string in any text field.Get an element item by its ID.
Arguments:
id: ID! - The unique identifier of the element.Returns:
Element - The requested Element object, or null if not found.Example:
query GetElementById($id: ID!) {
element(id: $id) {
id
type
name
data
lang
editor
}
}
Example Output:
{
"data": {
"element": {
"id": "someId123",
"type": "text",
"name": "Welcome Message",
"data": {"text": "Hello, welcome to our site!"},
"lang": "en",
"editor": "adminUser"
}
}
}
Get available element items, with optional filtering, sorting, and pagination.
Arguments:
filter: ElementFilter - An input object to filter the elements.sort: _ - Specifies the sorting order. Available columns: id, lang, name, type, editor.publish: Publish - (Optional) Publish status filter.Returns:
[Element!] - A list of Element objects.Example:
query GetPublishedTextElements($type: String, $lang: String, $first: Int = 10, $page: Int = 1) {
elements(filter: {type: $type, lang: $lang}, publish: true, first: $first, page: $page, sort: [{column: "name", direction: ASC}]) {
data {
id
type
name
lang
data
}
paginatorInfo {
count
currentPage
lastPage
total
}
}
}
Example Output:
{
"data": {
"elements": {
"data": [
{
"id": "someId123",
"type": "text",
"name": "Welcome Message",
"lang": "en",
"data": {"text": "Hello, welcome to our site!"}
},
{
"id": "someOtherId456",
"type": "text",
"name": "About Us",
"lang": "en",
"data": {"text": "Learn more about our company."}
}
],
"paginatorInfo": {
"count": 2,
"currentPage": 1,
"lastPage": 1,
"total": 2
}
}
}
}
Add a new shared content element with optional file references.
Arguments:
input: ElementInput! - The data for the new element.files: [ID!] - (Optional) List of file IDs to associate with the element.Returns:
Element - The newly created Element object.Example:
mutation AddNewElement($input: ElementInput!, $files: [ID!]) {
addElement(input: $input, files: $files) {
id
type
name
lang
data
created_at
editor
}
}
Example Input:
{
"type": "text",
"lang": "en",
"name": "Welcome Message",
"data": {"text": "Hello, welcome to our site!"}
}
Example Output:
{
"data": {
"addElement": {
"id": "newElementId789",
"type": "text",
"name": "Welcome Message",
"lang": "en",
"data": {"text": "Hello, welcome to our site!"},
"created_at": "2023-10-27 10:00:00",
"editor": "adminUser"
}
}
}
Update an existing shared content element.
Arguments:
id: ID! - The unique identifier of the element to update.input: ElementInput! - The new data for the element.files: [ID!] - (Optional) List of file IDs to associate to the element.Returns:
Element - The updated Element object.Example:
mutation UpdateExistingElement($id: ID!, $input: ElementInput!, $files: [ID!]) {
saveElement(id: $id, input: $input, files: $files) {
id
name
data
updated_at
editor
}
}
Example Input:
{
"type": "text",
"lang": "en",
"name": "Updated Welcome Message",
"data": {"text": "Hello, welcome back! Your account has been updated."}
}
Example Output:
{
"data": {
"saveElement": {
"id": "someId123",
"name": "Updated Welcome Message",
"data": {"text": "Hello, welcome back! Your account has been updated."},
"updated_at": "2023-10-27 11:30:00",
"editor": "adminUser"
}
}
}
Delete an existing shared content element (soft delete).
Arguments:
id: [ID!]! - A list of unique identifiers of the elements to delete.Returns:
[Element]! - A list of the deleted Element objects.Example:
mutation SoftDeleteElements($ids: [ID!]!) {
dropElement(id: $ids) {
id
name
deleted_at
}
}
Example Output:
{
"data": {
"dropElement": [
{
"id": "elementIdToDelete1",
"name": "Old Promo Banner",
"deleted_at": "2023-10-27 12:00:00"
},
{
"id": "elementIdToDelete2",
"name": "Archived Notice",
"deleted_at": "2023-10-27 12:00:00"
}
]
}
}
Restore an existing shared content element that was soft-deleted.
Arguments:
id: [ID!]! - A list of unique identifiers of the elements to restore.Returns:
[Element]! - A list of the restored Element objects.Example:
mutation RestoreElements($ids: [ID!]!) {
keepElement(id: $ids) {
id
name
deleted_at
}
}
Example Output:
{
"data": {
"keepElement": [
{
"id": "elementIdToRestore1",
"name": "Old Promo Banner",
"deleted_at": null
}
]
}
}
Permanently delete an existing shared content element.
Arguments:
id: [ID!]! - A list of unique identifiers of the elements to purge.Returns:
[Element]! - A list of the purged Element objects.Example:
mutation PurgeElementsPermanently($ids: [ID!]!) {
purgeElement(id: $ids) {
id
name
}
}
Example Output:
{
"data": {
"purgeElement": [
{
"id": "elementIdToPurge1",
"name": "Test Element"
}
]
}
}
Publish an existing shared content element.
Arguments:
id: [ID!]! - A list of unique identifiers of the elements to publish.at: DateTime - (Optional) Specific date and time for publication.Returns:
[Element]! - A list of the published Element objects.Example:
mutation PublishElements($ids: [ID!]!, $publishAt: DateTime) {
pubElement(id: $ids, at: $publishAt) {
id
name
updated_at
}
}
Example Output:
{
"data": {
"pubElement": [
{
"id": "elementIdToPublish1",
"name": "Important Announcement",
"updated_at": "2023-10-27 14:00:00"
}
]
}
}