GraphQL Pages

This article provides a comprehensive guide to managing pages within the CMS, covering essential operations such as retrieving, adding, moving, saving, publishing, deleting, and restoring pages. Pages are organized in a hierarchical tree structure, enabling the creation of complex site architectures.

Understanding the hierarchical structure of pages is crucial for efficient management. Pages are organized in a tree structure, featuring a root page and its sub-pages. The system supports multiple root pages, which can be used for different domains and/or languages, offering flexible site organization.

To begin, you can fetch all root-level pages from your CMS instance. These pages typically represent the top-level entries in your site structure. To retrieve the root pages, use the following GraphQL query:

query {
  pages(filter: {parent_id: null, lang: ""}, first: 10, page: 1) {
    data {
      id
      related_id
      parent_id
      lang
      path
      domain
      name
      title
      to
      tag
      theme
      type
      meta
      config
      content
      status
      cache
      editor
      created_at
      updated_at
      deleted_at
      has
    }
    paginatorInfo {
      currentPage
      lastPage
      total
      count
      perPage
    }
  }
}

The pages query accepts the following arguments:

• filter (optional): Allows filtering of pages based on various criteria. In this example, we are filtering for root pages (parent_id: null) and a specific language (lang: ""). See PageFilter for all available filter options.
• first (optional): Specifies the maximum number of pages to retrieve per page. Defaults to 100 as defined in the schema.
• page (optional): Specifies the page number to retrieve. Defaults to 1.
• publish (optional): Filters pages by publishing status. Values: PUBLISHED, DRAFT, SCHEDULED.
• trashed (optional): Filters pages by soft-delete status. Values: WITHOUT (default), WITH, ONLY.

The query returns a paginated list of Page objects, along with pagination information.

Example response:

{
  "data": {
    "pages": {
      "data": [
        {
          "id": "1",
          "related_id": null,
          "parent_id": null,
          "lang": "",
          "path": "",
          "domain": "mydomain.tld",
          "name": "Home",
          "title": "Home | PagibleAI CMS",
          "to": "",
          "tag": "root",
          "theme": null,
          "type": null,
          "meta": "{\"text\":\"PagibleAI CMS is outstanding\",\"type\":\"meta\"}",
          "config": "{}",
          "content": "[]",
          "status": 1,
          "cache": 5,
          "editor": "aimeos@aimeos.org",
          "created_at": "2023-04-01 09:02:25",
          "updated_at": "2023-04-01 10:22:15",
          "deleted_at": null,
          "has": true
        }
      ],
      "paginatorInfo": {
        "currentPage": 1,
        "lastPage": 1,
        "total": 1,
        "count": 1,
        "perPage": 100
      }
    }
  }
}

Once you have root pages or any parent page, you can fetch their direct children to navigate deeper into your site's hierarchy. To retrieve the children of a specific page, use the following GraphQL query, providing the id of the parent page:

query {
  pages(filter: {parent_id: "1", lang: ""}, first: 25, page: 1) {
    data {
      id
      related_id
      parent_id
      lang
      path
      domain
      name
      title
      to
      tag
      theme
      type
      meta
      config
      content
      status
      cache
      editor
      created_at
      updated_at
      deleted_at
      has
    }
    paginatorInfo {
      currentPage
      lastPage
      total
      count
      perPage
    }
  }
}

This query uses the parent_id within the filter argument to specify that we want children of the page with ID "1". Other arguments like lang, first, and page function the same way as in the "Fetch Root Pages" example. See PageFilter for all available filter options.

Example response:

{
  "data": {
    "pages": {
      "data": [
        {
          "id": "2",
          "related_id": null,
          "parent_id": "1",
          "lang": "",
          "path": "blog",
          "domain": "",
          "name": "Blog",
          "title": "Blog | PagibleAI CMS",
          "to": "",
          "tag": "blog",
          "theme": null,
          "type": null,
          "meta": "{}",
          "config": "{}",
          "content": "[]",
          "status": 1,
          "cache": 5,
          "editor": "aimeos@aimeos.org",
          "created_at": "2023-04-01 09:02:25",
          "updated_at": "2023-04-01 09:30:11",
          "deleted_at": null,
          "has": true
        },
        {
          "id": "4",
          "related_id": null,
          "parent_id": "1",
          "lang": "",
          "path": "dev",
          "domain": "",
          "name": "Dev",
          "title": "For Developer | PagibleAI CMS",
          "to": "",
          "tag": "",
          "theme": null,
          "type": null,
          "meta": "{}",
          "config": "{}",
          "content": "[]",
          "status": 1,
          "cache": 5,
          "editor": "aimeos@aimeos.org",
          "created_at": "2023-04-01 09:02:25",
          "updated_at": "2023-04-01 09:30:11",
          "deleted_at": null,
          "has": false
        }
      ],
      "paginatorInfo": {
        "currentPage": 1,
        "lastPage": 1,
        "total": 2,
        "count": 2,
        "perPage": 100
      }
    }
  }
}

When you need to access a specific page directly, you can retrieve it using its unique ID. This method is useful for focused operations or when you already know the exact page you're targeting. To retrieve a specific page by its ID, use the following GraphQL query:

query {
  page(id: "1") {
    id
    related_id
    parent_id
    lang
    path
    domain
    name
    title
    to
    tag
    theme
    type
    meta
    config
    content
    status
    cache
    editor
    created_at
    updated_at
    deleted_at
    has
    parent {
      id
    }
    children {
      data {
        id
      }
    }
    ancestors {
      id
    }
    elements {
      id
    }
    files {
      id
    }
    versions {
      id
    }
    latest {
      id
    }
  }
}

This query uses the page(id: "1") query to retrieve the page with ID "1". The response will include all properties of the Page type, and also include related entities, such as parent, children, ancestors, elements, files, versions and latest.

Example response:

{
  "data": {
    "page": {
      "id": "1",
      "related_id": null,
      "parent_id": null,
      "lang": "",
      "path": "",
      "domain": "mydomain.tld",
      "name": "Home",
      "title": "Home | PagibleAI CMS",
      "to": "",
      "tag": "root",
      "theme": null,
      "type": null,
      "meta": "{\"cms:meta\":{\"text\":\"PagibleAI CMS is outstanding\",\"type\":\"meta\"}}",
      "config": "{}",
      "content": "[{\"type\":\"heading\",\"text\":\"Welcome to PagibleAI CMS\"}]",
      "status": 1,
      "cache": 5,
      "editor": "aimeos@aimeos.org",
      "created_at": "2023-04-01 09:02:25",
      "updated_at": "2023-04-01 10:22:15",
      "deleted_at": null,
      "has": true,
      "parent": null,
      "children": {
        "data": [
          {
            "id": "3"
          },
          {
            "id": "4"
          }
        ]
      },
      "ancestors": [{
        "id": "1"
      }],
      "elements": [{
        "id": "01987497-8c96-735f-a4a6-d20c2371f947"
      }],
      "files": [{
        "id": "01987499-3a39-71cd-be98-32b5d6b6f5ff"
      }],
      "versions": [{
        "id": "019874ac-46db-7074-bacd-e0ee7bf449c0"
      }],
      "latest": {
        "id": "019874ac-46db-7074-bacd-e0ee7bf449c0"
      }
    }
  }
}

To expand your site's primary structure, you can add a new root-level page. This will create a new top-level entry in your page hierarchy. To add a new root page at the end of the list of root pages use:

mutation {
  addPage(
    input: {
      lang: "en",
      path: "test-url",
      domain: "mydomain.tld",
      name: "Test page",
      title: "A PagibleAI CMS test page",
      to: "https:\\\/\/pagible.com",
      tag: "test",
      meta: "{}",
      config: "{}",
      content: "[]",
      status: 0,
      cache: 5
    },
    elements: ["0187d6ab-b76d-75ee-8830-ab00b4259aa5", "0187d6ab-b76d-75ee-8840-7e8026251ba0"],
    files: ["0187d6ab-b76d-75ee-8b0d-1b59cc3a1ab7"]
  ) {
    id
  }
}

Required parameters are:

• input: JSON object with key/value pairs for the page properties. meta, config, and content fields expect JSON string values.
• elements (list of IDs): List of IDs from the shared content elements which are referenced in meta or content JSON strings.
• files (list of IDs): List of IDs from the files which are referenced in meta or content JSON strings.

The request will return:

{
  "data": {
    "addPage": {
      "id": "9"
    }
  }
}

To organize content under an existing page, you can add a new child page. This operation nests the new page directly under a specified parent. To add a new child page to an existing parent page at the end of the list of children pages use:

mutation {
  addPage(
    input: {
      lang: "en",
      path: "test-url-2",
      domain: "mydomain.tld",
      name: "Test page",
      title: "A PagibleAI CMS test page",
      to: "https:\\\/\/pagible.com",
      tag: "test",
      meta: "{}",
      config: "{}",
      content: "[]",
      status: 0,
      cache: 5
    },
    parent: "1",
    elements: ["0187d6ab-b76d-75ee-8830-ab00b4259aa5", "0187d6ab-b76d-75ee-8840-7e8026251ba0"],
    files: ["0187d6ab-b76d-75ee-8b0d-1b59cc3a1ab7"]
  ) {
    id
  }
}

Required parameters are:

• input: JSON object with key/value pairs for the page properties. meta, config, and content fields expect JSON string values.
• parent: ID of the parent where the new page will be inserted below.
• elements (list of IDs): List of IDs from the shared content elements which are referenced in meta or content JSON strings.
• files (list of IDs): List of IDs from the files which are referenced in meta or content JSON strings.

The main difference is the parent parameter in the addPage() mutation. It returns:

{
  "data": {
    "addPage": {
      "id": "10"
    }
  }
}

For precise control over page order, you can insert a new page directly before an existing one. This allows you to position new content strategically within any level of the hierarchy. To insert a new page before an existing one, use the following GraphQL mutation:

mutation {
  addPage(
    input: {
      lang: "en",
      path: "test-url-3",
      domain: "mydomain.tld",
      name: "Test page",
      title: "A PagibleAI CMS test page",
      to: "https:\\\/\/pagible.com",
      tag: "test",
      meta: "{}",
      config: "{}",
      content: "[]",
      status: 0,
      cache: 5
    },
    parent: "1",
    ref: "2",
    elements: ["0187d6ab-b76d-75ee-8830-ab00b4259aa5", "0187d6ab-b76d-75ee-8840-7e8026251ba0"],
    files: ["0187d6ab-b76d-75ee-8b0d-1b59cc3a1ab7"]
  ) {
    id
  }
}

Required parameters are:

• input: JSON object with key/value pairs for the page properties. meta, config, and content fields expect JSON string values.
• parent (optional): ID of the parent where the new page will be inserted below.
• ref (optional): ID of the page the new one will be inserted before. If null or not passed, the page will be added at the end of the parents' children
• elements (list of IDs): List of IDs from the shared content elements which are referenced in meta or content JSON strings.
• files (list of IDs): List of IDs from the files which are referenced in meta or content JSON strings.

Like the other mutations, it returns:

{
  "data": {
    "addPage": {
      "id": "11"
    }
  }
}

You can elevate an existing page to the root level, making it an independent top-level entry in your site structure. This is useful for restructuring your site or promoting a sub-page. To make an existing page a root page and append it at the end of the list of root pages use:

mutation {
  movePage(id: "3") {
    id
    parent_id
  }
}

Required parameters are:

• id: ID (string) of the page to move to the root level.

It will return:

{
  "data": {
    "movePage": {
      "id": "3",
      "parent_id": null
    }
  }
}

To reorganize your page hierarchy, you can move an existing page under a different parent. This operation reassigns the page's parent and appends it to the end of the new parent's children list. To move an existing page to a new parent page and append it at the end of the list of children use:

mutation {
  movePage(id: "3", parent: "2") {
    id
    parent_id
  }
}

Required parameters are:

• id: ID (string) of the page to move.
• parent (optional): ID (string) of the new parent page.

The returned data will be:

{
  "data": {
    "movePage": {
      "id": "3",
      "parent_id": "2"
    }
  }
}

For fine-grained control over page ordering, you can move an existing page to a position directly before another specified page. This allows for precise rearrangement within the same parent or across different branches. To move an existing page before another page use:

mutation {
  movePage(id: "3", parent: "1", ref: "5") {
    id
    parent_id
  }
}

Required parameters are:

• id: ID (string) of the page to move.
• parent (optional): ID (string) of the new parent page.
• ref (optional): ID (string) of the page the moved one will be inserted before.

The returned data will be:

{
  "data": {
    "movePage": {
      "id": "3",
      "parent_id": "1"
    }
  }
}

After creating or modifying a page, you'll often need to save its properties, such as its title, path, or associated metadata. This operation updates the page's attributes in the CMS. Saving page properties can be done using:

mutation {
  savePage(
    id: "5",
    input: {
      lang: "en",
      path: "test-url-5",
      domain: "mydomain.tld",
      name: "Test page",
      title: "A PagibleAI CMS test page",
      to: "https:\\\/\/pagible.com",
      tag: "test",
      meta: "{}",
      config: "{}",
      content: "[]",
      status: 0,
      cache: 5
    },
    elements: ["0187d6ab-b76d-75ee-8830-ab00b4259aa5", "0187d6ab-b76d-75ee-8840-7e8026251ba0"],
    files: ["0187d6ab-b76d-75ee-8b0d-1b59cc3a1ab7"]
  ) {
    id
  }
}

Required parameters are:

• id: ID (string) of the page to store the changed properties for.
• input: JSON object with key/value pairs for the page properties. meta, config, and content fields expect JSON string values.
• elements (list of IDs): List of IDs from the shared content elements which are referenced in meta or content JSON strings.
• files (list of IDs): List of IDs from the files which are referenced in meta or content JSON strings.

Note: Any value passed in content will create a new record in the version table for that data which can be published afterwards.

When your page meta data (meta field) or body data (content field) contains file references, you must pass their IDs using the files parameter. This ensures that the files are not deleted accidentally because no references exist.

This request will return:

{
  "data": {
    "savePage": {
      "id": "5"
    }
  }
}

When you make changes to a page's meta data, these modifications are initially stored as versions. To make these updates live and visible, you must publish the latest version of the page. Changes to the page meta data are stored as versions, and you can publish the latest version using:

mutation {
  pubPage(id: ["1"]) {
    id
  }
}

Required parameters:

• id: Array of IDs (strings) of the pages whose meta data should be published.
• at (optional): DateTime — Schedule publication for a specific date and time.

The returned response will be:

{
  "data": {
    "pubPage": {
      "id": "1"
    }
  }
}

When a page is no longer needed but you wish to retain the option of restoring it later, you can move it to the trash. This action also moves all its descendant pages. To trash a page and its descendants so it can be restored, use:

mutation {
  dropPage(id: ["7"]) {
    id
  }
}

Required parameters:

• id: Array of IDs (strings) of the pages to delete (trash).

This request will return:

{
  "data": {
    "dropPage": {
      "id": "7"
    }
  }
}

If a page has been trashed but not yet permanently purged, it can be restored to its previous location within the page hierarchy. To restore a trashed page by its ID, use:

mutation {
  keepPage(id: ["7"]) {
    id
  }
}

Required parameters:

• id: Array of IDs (strings) of the pages to restore.

This request will return:

{
  "data": {
    "keepPage": {
      "id": "7"
    }
  }
}

For situations where a page and its associated content are no longer needed and should be permanently removed, you can purge them from the system. This action is irreversible. To delete a page and its descendants permanently, use:

mutation {
  purgePage(id: ["7"]) {
    id
  }
}

Required parameters are:

• id: Array of IDs (strings) of the pages to delete permanently.

This request will return:

{
  "data": {
    "purgePage": {
      "id": "7"
    }
  }
}

The PageFilter input type supports the following fields for filtering pages queries:

The Version type represents a versioned snapshot of page, element, or file data: