From 40bb322a7e0abc641203580be59a83529c81c887 Mon Sep 17 00:00:00 2001
From: Aaron Carlino <unclecheese@leftandmain.com>
Date: Mon, 6 Sep 2021 17:27:14 +1200
Subject: [PATCH] DOCS: Document new DBFieldArgs plugin (#10039)

* Docs for DBFieldArgs

* New docs for enumTypeMapping, ignore
---
 .../01_dataobject_model_type.md               |  19 +++
 .../02_query_plugins.md                       | 114 ++++++++++++++++++
 2 files changed, 133 insertions(+)

diff --git a/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md b/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md
index c51418765..65de9a0b4 100644
--- a/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md
+++ b/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md
@@ -77,10 +77,29 @@ query {
   readPages {
     nodes {
       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:
 ```graphql
 mutation {
diff --git a/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/02_query_plugins.md b/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/02_query_plugins.md
index 51f71b1c7..3066904c6 100644
--- a/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/02_query_plugins.md
+++ b/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/02_query_plugins.md
@@ -23,6 +23,7 @@ plugins to include, and for DataObject queries, these include:
 
 * filter
 * sort
+* dbFieldArgs
 * paginateList
 * inheritance
 * canView (read, readOne)
@@ -293,6 +294,119 @@ modelConfig:
           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
 
 When the `silverstripe/cms` module is installed (it is in most cases), a plugin called `getByLink`