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 operation permissions
- A look at how permissions work for DataObject queries and mutations
- DataObject inheritance
- Learn how inheritance is handled in DataObject model types
- DataObject query plugins
- Learn about some of the useful goodies that come pre-packaged with DataObject queries
- 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
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 theDataObject
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