Version 1.2

CHANGELOG.md

@@ -1,6 +1,13 @@
 # (MODX)EvolutionCMS.snippets.ddStash changelog
 
 
+## Version 1.2 (2020-05-03)
+* \+ Added the ability to prevent overwriting fields with empty values (the `save_extendExistingWithEmpty` parameter, see README).
+* \+ README_ru.
+* \+ CHANGELOG_ru.
+* \* README: Small improvements.
+
+
 ## Version 1.1 (2020-04-29)
 * \+ Added the ability to return objects and arrays in JSON format (see README.md).
 * \+ Added the ability to extend an existing object instead of overwriting it (see `save_extendExisting`).

CHANGELOG_ru.md

@@ -0,0 +1,27 @@
+# (MODX)EvolutionCMS.snippets.ddStash changelog
+
+
+## Версия 1.2 (2020-05-03)
+* \+ Добавлена возможность предотвратить перезапись полей при расширении пустыми значениями (параметр `save_extendExistingWithEmpty`, см. README).
+* \+ README_ru.
+* \+ CHANGELOG_ru.
+* \* README: Небольшие улучшения.
+
+
+## Версия 1.1 (2020-04-29)
+* \+ Добавлена возможность возвращать объекты и массивы в формате JSON (см. README).
+* \+ Добавлена возможность расширения существующих объектов вместо их перезаписи (см. параметр `save_extendExisting`).
+* \+ README, CHANGELOG: Стиль улучшен.
+* \* REAMDE → Описание параметров → `save`: Небольшие улучшения.
+* \* Composer.json:
+	* \* `version`: Исправлен формат.
+	* \+ `keywords` → `stash`.
+	* \+ `require`.
+
+
+## Версия 1.0 (2019-10-31)
+* \+ Первый релиз.
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
+<style>ul{list-style:none;}</style>

README.md

@@ -1,13 +1,13 @@
 # (MODX)EvolutionCMS.snippets.ddStash
 
-Save data as JSON or QueryString, then extend if needed and use it later without database queries.
+Save data as [JSON](https://en.wikipedia.org/wiki/JSON) or [Query string](https://en.wikipedia.org/wiki/Query_string), then extend if needed and use it later without database queries.
 
 
 ## Requires
 
 * PHP >= 5.4
 * [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
-* [(MODX)EvolutionCMS.libraries.ddTools](http://code.divandesign.biz/modx/ddtools) >= 0.33.1
+* [(MODX)EvolutionCMS.libraries.ddTools](http://code.divandesign.biz/modx/ddtools) >= 0.34
 
 
 ## Documentation
@@ -18,7 +18,7 @@ Save data as JSON or QueryString, then extend if needed and use it later without
 Elements → Snippets: Create a new snippet with the following data:
 
 1. Snippet name: `ddStash`.
-2. Description: `<b>1.1</b> Save data as JSON or QueryString, then extend if needed and use it later without database queries.`.
+2. Description: `<b>1.2</b> Save data as JSON or QueryString, then extend if needed and use it later without database queries.`.
 3. Category: `Core`.
 4. Parse DocBlock: `no`.
 5. Snippet code (php): Insert content of the `ddStash_snippet.php` file from the archive.
@@ -40,6 +40,18 @@ Elements → Snippets: Create a new snippet with the following data:
 		* `1`
 	* Default value: `0`
 
+* `save_extendExistingWithEmpty`
+	* Desctription: Overwrite fields with empty values (see examples below).  
+		The following values are considered to be empty:
+		* `""` — an empty string
+		* `[]` — an empty array
+		* `{}` — an empty object
+		* `null`
+	* Valid values:
+		* `0`
+		* `1`
+	* Default value: `1`
+
 * `get`
 	* Desctription: Data key for getting from stash.
 	* Valid values: `string`
@@ -49,10 +61,10 @@ Elements → Snippets: Create a new snippet with the following data:
 	* Desctription: Output template.
 		
 		Available placeholders:
-		* `[+snippetResult+]` — Data from stash.
+		* `[+snippetResult+]` — data from stash
 		
 	* Valid values:
-		* `string_chunkName`
+		* `stringChunkName`
 		* `string` — use inline templates starting with `@CODE:`
 	* Default value: `'@CODE:[+snippetResult+]'`
 
@@ -271,4 +283,76 @@ Returns:
 ```
 
 
+#### Save: Extend without overwriting fields with empty values (``&save_extendExistingWithEmpty=`0` ``)
+
+By default, empty field values (e. g. `''`) are treated as other values and will replace non-empty ones.
+
+```
+[[ddStash?
+	&save=`{
+		"userData": {
+			"firstName": "John",
+			"lastName": "Tesla",
+			"discipline": "Electrical engineering"
+		}
+	}`
+]]
+[[ddStash?
+	&save=`{
+		"userData": {
+			"firstName": "Nikola",
+			"lastName": ""
+		}
+	}`
+	&save_extendExisting=`1`
+]]
+```
+
+Returns:
+
+```json
+{
+	"firstName" => "Nikola",
+	"lastName" => "",
+	"discipline" => "Electrical engineering"
+}
+```
+
+Empty `lastName` from the second object replaced non-empty `lastName` from the first.
+
+If you want to ignore empty values, just use `save_extendExistingWithEmpty` == `0`:
+
+```php
+[[ddStash?
+	&save=`{
+		"userData": {
+			"firstName": "John",
+			"lastName": "Tesla",
+			"discipline": "Electrical engineering"
+		}
+	}`
+]]
+[[ddStash?
+	&save=`{
+		"userData": {
+			"firstName": "Nikola",
+			"lastName": ""
+		}
+	}`
+	&save_extendExisting=`1`
+	&save_extendExistingWithEmpty=`0`
+]]
+```
+
+Returns:
+
+```json
+{
+	"firstName" => "Nikola",
+	"lastName" => "Tesla",
+	"discipline" => "Electrical engineering"
+}
+```
+
+
 <link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />