GraphQL Shared Elements

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.

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.

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. Values: PUBLISHED, DRAFT, SCHEDULED.
trashed: Trashed - (Optional) Soft-delete status filter. Values: WITHOUT (default), WITH, ONLY.

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: PUBLISHED, trashed: WITHOUT, 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
      }
    }
  }
}

Input type for creating or updating element data.

type: String! - Type of the content element (required).
lang: String - ISO language code, e.g., 'en', 'en-GB' or empty for default language.
name: String - Arbitrary string which describes the element.
data: JSON! - Arbitrary content element data (required).

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"
      }
    ]
  }
}

GraphQL Shared Elements

The Element Type

Queries

Element Filter

Element

Elements

Mutations

Element Input

Add Element

Save Element

Drop Element

Keep Element

Purge Element

Publish Element