Version 4 supported
This version of Silverstripe CMS is still supported though will not receive any additional features. Go to documentation for the most recent stable version.

Working with DataObject models

Adding DataObject models to the schema
An overview of how the DataObject model can influence the creation of types, queries, and mutations
DataObject query plugins
Learn about some of the useful goodies that come pre-packaged with DataObject queries
DataObject operation permissions
A look at how permissions work for DataObject queries and mutations
DataObject inheritance
Learn how inheritance is handled in DataObject model types
Versioned content
A guide on how DataObject models with the Versioned extension behave in GraphQL schemas
Property mapping and dot syntax
Learn how to customise field names, use dot syntax, and use aggregate functions
Nested type definitions
Define dependent types inline with a parent type

You are viewing docs for silverstripe/graphql 4.x. If you are using 3.x, documentation can be found in the GitHub repository

Versioned content

For the most part, if your DataObject has the Versioned extension applied, there is nothing you need to do explicitly - but be aware that it will affect the operations and fields of your type. You can also disable versioning for your schema if you don't need it.

See model versioning for general information about versioning your DataObjects.

Versioned plugins

There are several plugins provided by the silverstripe/versioned module that affect how versioned DataObjects appear in the schema. These include:

  • The versioning plugin, applied to the DataObject type
  • The readVersion plugin, applied to the queries for the DataObject
  • The unpublishOnDelete plugin, applied to the delete mutation

Let's walk through each one.

The versioning plugin

Defined in the VersionedDataObject class, this plugin adds several fields to the DataObject type, including:

The version field

The version field on your DataObject will include the following fields:

  • author: Member (Object -- the author of the version)
  • publisher: Member (Object -- the publisher of the version)
  • published: Boolean (True if the version is published)
  • liveVersion: Boolean (True if the version is the one that is currently live)
  • latestDraftVersion: Boolean (True if the version is the latest draft version)

Note that author and publisher are in relation to the given version of the object - these are not necessarily the same as the author and publisher of the original record (i.e. the author may not be the person who created the object, they're the person who saved a specific version of it).

Let's look at it in context:

query readPages {
  nodes {
    title
    version {
      author {
        firstname
      }
      published
    }
  }
}
The versions field

The versions field on your DataObject will return a list of the version objects described above. The list is sortable by version number, using the sort parameter.

query readPages {
  nodes {
    title
    versions(sort: { version: DESC }) {
      author {
        firstname
      }
      published
    }
  }
}

The readVersion plugin

This plugin updates the read operation to include a versioning argument that contains the following fields:

  • mode: VersionedQueryMode (An enum of [ARCHIVE, LATEST, DRAFT, LIVE, STATUS, VERSION])
  • archiveDate: String (The archive date to read from)
  • status: VersionedStatus (An enum of [PUBLISHED, DRAFT, ARCHIVED, MODIFIED])
  • version: Int (The exact version to read)

The query will automatically apply the settings from the versioning input type to the query and affect the resulting DataList.

The unpublishOnDelete plugin

This is mostly for internal use. It's an escape hatch for tidying up after a delete.

Versioned operations

DataObjects with the Versioned extension applied will also receive four extra operations by default. They include:

  • publish
  • unpublish
  • copyToStage
  • rollback

All of these identifiers can be used in the operations config for your versioned DataObject. They will all be included if you use operations: '*'.

# app/_graphql/models.yml
App\Model\MyObject:
  fields: '*'
  operations:
    publish: true
    unpublish: true
    rollback: true
    copyToStage: true

Using the operations

Let's look at a few examples:

Publishing
mutation publishSiteTree(id: 123) {
  id
  title
}
Unpublishing
mutation unpublishSiteTree(id: 123) {
  id
  title
}
Rolling back
mutation rollbackSiteTree(id: 123, toVersion: 5) {
  id
  title
}
Copying to stage
mutation copySiteTreeToStage(id: 123, fromStage: DRAFT, toStage: LIVE) {
  id
  title
}

Disabling versioning on your schema

Versioning is great for Content APIs (e.g. previews), but often not necessary for public APIs focusing on published data. You can disable versioning for your schema in the modelConfig section:

# app/_graphql/config.yml
modelConfig:
  DataObject:
    plugins:
      versioning: false
    operations:
      read:
        plugins:
          readVersion: false
      readOne:
        plugins:
          readVersion: false
      delete:
        plugins:
          unpublishOnDelete: false

Further reading

Adding DataObject models to the schema
An overview of how the DataObject model can influence the creation of types, queries, and mutations
DataObject query plugins
Learn about some of the useful goodies that come pre-packaged with DataObject queries
DataObject operation permissions
A look at how permissions work for DataObject queries and mutations
DataObject inheritance
Learn how inheritance is handled in DataObject model types
Versioned content
A guide on how DataObject models with the Versioned extension behave in GraphQL schemas
Property mapping and dot syntax
Learn how to customise field names, use dot syntax, and use aggregate functions
Nested type definitions
Define dependent types inline with a parent type