Working with DataObjects

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
Versioned content
A guide on how DataObjects with the Versioned extension behave in GraphQL schemas
DataObject inheritance
Learn how inheritance is handled in DataObject types
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
The DataObject model type
An overview of how the DataObject model can influence the creation of types, queries, and mutations
You are viewing docs for a pre-release version of silverstripe/graphql (4.x). Help us improve it by joining #graphql on the Community Slack, and report any issues at github.com/silverstripe/silverstripe-graphql. Docs for the current stable version (3.x) can be found here

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.

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

Defined in the SilverStripe\Versioned\GraphQL\Plugins\VersionedDataObject class, this plugin adds several fields to the DataObject type, including:

The

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)

Let's look at it in context:

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

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

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

  MyProject\Models\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

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
Versioned content
A guide on how DataObjects with the Versioned extension behave in GraphQL schemas
DataObject inheritance
Learn how inheritance is handled in DataObject types
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
The DataObject model type
An overview of how the DataObject model can influence the creation of types, queries, and mutations