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
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