DOCS: Document new DBFieldArgs plugin (#10039)

* Docs for DBFieldArgs

* New docs for enumTypeMapping, ignore
This commit is contained in:
Aaron Carlino 2021-09-06 17:27:14 +12:00 committed by GitHub
parent f756568030
commit 40bb322a7e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 133 additions and 0 deletions

View File

@ -77,10 +77,29 @@ query {
readPages { readPages {
nodes { nodes {
title title
content
... on BlogPage {
date(format: NICE)
comments {
nodes {
comment
author {
firstName
}
}
}
}
} }
} }
``` ```
[info]
Note the use of the default arguments on `date`. Fields created from `DBFields`
generate their own default sets of arguments. For more information, see the
[DBFieldArgs](query_plugins#dbfieldargs) for more information.
[/info]
A mutation: A mutation:
```graphql ```graphql
mutation { mutation {

View File

@ -23,6 +23,7 @@ plugins to include, and for DataObject queries, these include:
* filter * filter
* sort * sort
* dbFieldArgs
* paginateList * paginateList
* inheritance * inheritance
* canView (read, readOne) * canView (read, readOne)
@ -293,6 +294,119 @@ modelConfig:
sort: false sort: false
``` ```
### The DBFieldArgs plugin {#dbfieldargs}
When fields are introspected from a model and reference a `DBField` instance,
they get populated with a default set of arguments that map to methods on that
`DBField` class, for instance `->Nice()` or `->LimitSentences(4)`.
Let's have a look at this query:
```graphql
query {
readPages {
nodes {
content(format: LIMIT_SENTENCES, limit: 4)
created(format: NICE)
... on BlogPage {
introText(format: FIRST_PARAGRAPH)
publishDate(format: CUSTOM, customFormat: "dd/MM/yyyy")
}
}
}
}
```
The primary field types that are affected by this include:
* `DBText` (including `DBHTMLText`)
* `DBDate` (including `DBDatetime`)
* `DBTime`
* `DBDecimal`
* `DBFloat`
#### All available arguments
##### DBText
* `format: CONTEXT_SUMMARY` (optional "limit" arg)
* `format: FIRST_PARAGRAPH`
* `format: LIMIT_SENTENCES` (optional "limit" arg)
* `format: SUMMARY` (optional "limit" arg)
* `parseShortcodes: Boolean` (DBHTMLText only)
##### DBDate
* `format: TIMESTAMP`
* `format: NICE`
* `format: DAY_OF_WEEK`
* `format: MONTH`
* `format: YEAR`
* `format: SHORT_MONTH`
* `format: DAY_OF_MONTH`
* `format: SHORT`
* `format: LONG`
* `format: FULL`
* `format: CUSTOM` (requires `customFormat: String` arg)
##### DBTime
* `format: TIMESTAMP`
* `format: NICE`
* `format: SHORT`
* `format: CUSTOM` (requires `customFormat: String` arg)
##### DBDecimal
* `format: INT`
##### DBFloat
* `format: NICE`
* `format: ROUND`
* `format: NICE_ROUND`
#### Enum naming strategy and deduplication
By default, auto-generated Enum types will use as generic name as possible, which is `<FieldName>Enum`, e.g.
`OrderStatusEnum`. On occasion, this may collide with other types, e.g. `OptionsEnum`. In this case, the
second enum generated will use `<TypeName><FieldName>Enum`.
If an enum already exists with the same fields and name, it will be reused. For instance, if `OptionsEnum`
is found and has exactly the same defined values (in the same order) as the Enum being generated,
it will be reused rather than proceding to the deduplication strategy.
#### Custom enum names
You can specify custom enum names in the plugin config:
```
modelConfig:
DataObject:
plugins:
dbFieldTypes:
enumTypeMapping:
MyType:
myEnumField: SomeCustomTypeName
```
You can also specify enums to be ignored. (`ClassName` does this on all DataObjects to prevent inheritance
issues)
```
modelConfig:
DataObject:
plugins:
dbFieldTypes:
ignore:
MyType:
myEnumField: true
```
### The getByLink plugin ### The getByLink plugin
When the `silverstripe/cms` module is installed (it is in most cases), a plugin called `getByLink` When the `silverstripe/cms` module is installed (it is in most cases), a plugin called `getByLink`