From 09c137842e8cfe35efb032287eb240effd998890 Mon Sep 17 00:00:00 2001 From: Russ Michell Date: Fri, 1 Jul 2016 13:08:16 +1200 Subject: [PATCH] MUINOR: Docs. --- README.md | 16 +++----- docs/en/configuration.md | 9 +++-- docs/en/usage.md | 86 +++++++++++++++++++++++++--------------- 3 files changed, 64 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 09f18ec..d014045 100755 --- a/README.md +++ b/README.md @@ -26,19 +26,13 @@ or [Postgres' JSON operators](https://www.postgresql.org/docs/9.5/static/functio ### Why? -I've been wanting to write this module for over two years. Prior-to and during that time I have encountered -scenarios in more than one project where storing several (10s) of terse configuration parameters in separate database columns -just seemed crazy. +Project scenarios where storing 10s of terse configuration parameters in separate database columns +just seems crazy. -There's also the time all you wanted was a simple key -> value store but didn't want to muck -about with the overhead of two or more datastores like MySQL or Postgres together with MongoDB for example. +When all you wanted was a simple key / value store but didn't want to muck about with the overhead of two or more +datastores like an RDBMS together with MongoDB for example. -On one project I went as far as declaring that an entire tab's fields within `getCMSFields()` -would take their data from, and update-to, a single field comprising JSON data for one aspect of the system's -configuration. - -And if you needed any further convincing that a JSON store in an RDBMS is not such a crazy idea, well Postgres, MySQL, Oracle and MSSQL 2016 -all have, or at time of writing, are planning to have, just such a field. +That Postgres, MySQL, Oracle and MSSQL 2016 all have, or at time of writing, are planning to have, Database level JSON field-types. ### Postgres diff --git a/docs/en/configuration.md b/docs/en/configuration.md index d8d134a..1c8ed37 100755 --- a/docs/en/configuration.md +++ b/docs/en/configuration.md @@ -1,7 +1,7 @@ # Configuration -As the [README](../../README.md) suggests, you can put the module into `postgres` (The default) or `mysql` mode, but only `postgres` works at this time. You can -do this via standard SS config in your project's `mysite/_config/config.yml` file thus: +As the [README](../../README.md) suggests you can put the module into `postgres` (The default) or `mysql` mode, but only `postgres` works at this time. You can +do this via standard SS config in your project's `mysite/_config/config.yml` file: JSONText: backend: postgres @@ -9,5 +9,6 @@ do this via standard SS config in your project's `mysite/_config/config.yml` fil Notes: -* The module uses namespacing so take this into account when calling any part of the module's public API. -* The module default is to use `postgres` which is also the only backend that will work at the moment. +The module uses PSR-1 namespacing, so take this into account when calling any part of the module's public API in your own logic. +The exception to the rule is that you can still use "JSONText" without the full namespace when declaring your model's `$db` static +via the built-in magic of `Injector`. diff --git a/docs/en/usage.md b/docs/en/usage.md index ab43bc4..73233a5 100755 --- a/docs/en/usage.md +++ b/docs/en/usage.md @@ -1,11 +1,10 @@ # Usage -In the examples below, if you pass invalid queries, expressions or malformed JSON (where applicable) an instance of `JSONTextException` is thrown. +In the examples below, when passed invalid queries, expressions or malformed JSON (where applicable), then an instance of `JSONTextException` is thrown. ## General -You can stipulate what format you want your query results back in, by passing one of -**json**, **array** or **silverstripe** to the `setReturnType()` method, thus: +You can stipulate the format you want your query results back as by passing: **json**, **array** or **silverstripe** to the `setReturnType()` method: **JSON** ``` @@ -29,8 +28,7 @@ You can stipulate what format you want your query results back in, by passing on $field->setReturnType('silverstripe'); ``` -The module's overloaded declaration of the standard SS `setValue()` method is also chainable for a slightly -cleaner syntax: +The module's overloaded `setValue()` method is also chainable for a slightly cleaner syntax: **Chaining** ``` @@ -47,6 +45,9 @@ A small handful of simple query methods `first()`, `last()` and `nth()` exist fo class MyDataObject extends DataObject { + /** + * @var array + */ private static $db = [ 'MyJSON' => 'JSONText' ]; @@ -85,6 +86,10 @@ You can also use Postgres-like JSON querying syntax, for querying more complex J ``` class MyOtherDataObject extends DataObject { + + /** + * @var array + */ private static $db = [ 'MyJSON' => 'JSONText' ]; @@ -143,6 +148,9 @@ See: [Table of JSONPath expressions](jsonpath.md) ] }'; + /** + * @var array + */ private static $db = [ 'MyJSON' => 'JSONText' ]; @@ -203,40 +211,54 @@ node will be modified with the data passed to `setValue()` as the standard `$val ``` class MyDataObject extends DataObject { - /* - * @var string - */ - protected $stubJSON = '{ "store": { - "book": [ - { "category": "reference", - "author": "Nigel Rees", - }, - { "category": "fiction", - "author": "Evelyn Waugh", - } - ] - }'; + /* + * @var string + */ + protected $stubJSON = '{ "store": { + "book": [ + { "category": "reference", + "author": "Nigel Rees", + }, + { "category": "fiction", + "author": "Evelyn Waugh", + } + ] + }'; - private static $db = [ - 'MyJSON' => 'JSONText' - ]; + /** + * @var array + */ + private static $db = [ + 'MyJSON' => 'JSONText' + ]; + + public function requireDefaultRecords() + { + parent::requireDefaultRecords(); + + if (!$this->MyJSON) { + $this->setField($this->MyJSON, $this->stubJSON); + } + } - public function requireDefaultRecords() - { - parent::requireDefaultRecords(); - - if (!$this->MyJSON) { - $this->setField($this->MyJSON, $this->stubJSON); - } + /** + * @param array $update + * @return mixed void | null + */ + public function updateMyStuff(array $update = []) + { + if (empty($update)) { + return; } - + // Perform a multiple node update $newReference = [ - 'category' => "new-age", - 'author' => "Lucy Lastic" + 'category' => $update[0], + 'author' => $update[1] ]; - + $field->setValue($newReference, null, '$.store.book.[0]'); + } } ```