From 654ef6148d15510a3fdeecf6454e75eebbd0ec63 Mon Sep 17 00:00:00 2001 From: Ilyas Ronef Date: Sun, 3 May 2020 16:16:08 +0300 Subject: [PATCH 1/5] + Added the ability to prevent overwriting fields with empty values (the `save_extendExistingWithEmpty` parameter). --- README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++- composer.json | 2 +- ddStash_snippet.php | 11 +++++- 3 files changed, 96 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c0b9f4b..90224dc 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Save data as JSON or QueryString, then extend if needed and use it later without * 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 @@ -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` @@ -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" +} +``` + + \ No newline at end of file diff --git a/composer.json b/composer.json index eb3188e..e7ef4a6 100644 --- a/composer.json +++ b/composer.json @@ -15,6 +15,6 @@ ], "require": { "php": ">=5.4.0", - "dd/modxevo-library-ddtools": ">=0.33.1" + "dd/modxevo-library-ddtools": ">=0.34.0" } } \ No newline at end of file diff --git a/ddStash_snippet.php b/ddStash_snippet.php index ba76803..cbbd4eb 100644 --- a/ddStash_snippet.php +++ b/ddStash_snippet.php @@ -42,6 +42,14 @@ boolval($save_extendExisting) : false ; + $save_extendExistingWithEmpty = + ( + isset($save_extendExistingWithEmpty) && + $save_extendExistingWithEmpty == '0' + ) ? + false : + true + ; $save = \ddTools::encodedStringToArray($save); @@ -64,7 +72,8 @@ 'objects' => [ $storage[$dataName], $dataValue - ] + ], + 'overwriteWithEmpty' => $save_extendExistingWithEmpty ]); }else{ $storage[$dataName] = $dataValue; From f6b8004112fcaaeed9986d7137d3b6edb5df4cc9 Mon Sep 17 00:00:00 2001 From: Ilyas Ronef Date: Sun, 3 May 2020 16:21:18 +0300 Subject: [PATCH 2/5] + CHANGELOG_ru. --- CHANGELOG_ru.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 CHANGELOG_ru.md diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md new file mode 100644 index 0000000..381010f --- /dev/null +++ b/CHANGELOG_ru.md @@ -0,0 +1,20 @@ +# (MODX)EvolutionCMS.snippets.ddStash changelog + + +## Версия 1.1 (2020-04-29) +* \+ Добавлена возможность возвращать объекты и массивы в формате JSON (см. README). +* \+ Добавлена возможность расширения существующих объектов вместо их перезаписи (см. параметр `save_extendExisting`). +* \+ README, CHANGELOG: Стиль улучшен. +* \* REAMDE → Описание параметров → `save`: Небольшие улучшения. +* \* Composer.json: + * \* `version`: Исправлен формат. + * \+ `keywords` → `stash`. + * \+ `require`. + + +## Версия 1.0 (2019-10-31) +* \+ Первый релиз. + + + + \ No newline at end of file From 7f09845cea76cde6c572b5fe564c24d74ab94984 Mon Sep 17 00:00:00 2001 From: Ilyas Ronef Date: Sun, 3 May 2020 16:29:49 +0300 Subject: [PATCH 3/5] * README: Small improvements. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 90224dc..cfa7900 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # (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 @@ -61,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+]'` From 55109b7a7333f4e2bda1d331a4ca8e29790f3687 Mon Sep 17 00:00:00 2001 From: Ilyas Ronef Date: Sun, 3 May 2020 16:43:09 +0300 Subject: [PATCH 4/5] + README_ru. --- README_ru.md | 358 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 358 insertions(+) create mode 100644 README_ru.md diff --git a/README_ru.md b/README_ru.md new file mode 100644 index 0000000..08d44ac --- /dev/null +++ b/README_ru.md @@ -0,0 +1,358 @@ +# (MODX)EvolutionCMS.snippets.ddStash + +Сохраняйте данные в формате [JSON](https://ru.wikipedia.org/wiki/JSON) или [Query string](https://ru.wikipedia.org/wiki/Query_string), затем расширяйте по необходимости и используйте позже без запросов к базе данных. + + +## Использует + +* PHP >= 5.4 +* [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1 +* [(MODX)EvolutionCMS.libraries.ddTools](http://code.divandesign.biz/modx/ddtools) >= 0.34 + + +## Документация + + +### Установка + +Элементы → Сниппеты: Создайте новый сниппет со следующими параметрами: + +1. Название сниппета: `ddStash`. +2. Описание: `1.1 Сохраняйте данные в формате JSON или QueryString, затем расширяйте по необходимости и используйте позже без запросов к базе данных.`. +3. Категория: `Core`. +4. Анализировать DocBlock: `no`. +5. Код сниппета (php): Вставьте содержимое файла `ddStash_snippet.php` из архива. + + +### Описание параметров + +* `save` + * Описание: Сохранить данные в хранилище для последующего использования. Вложенные объекты также поддерживаются, см. примеры ниже. + * Допустимые значения: + * `stirngJsonObject` — в виде [JSON](https://ru.wikipedia.org/wiki/JSON) + * `stringQueryFormated` — в виде [Query string](https://ru.wikipedia.org/wiki/Query_string) + * Значение по умолчанию: — + +* `save_extendExisting` + * Описание: Расширить существующие объекты вместо их перезаписи. + * Допустимые значения: + * `0` + * `1` + * Значение по умолчанию: `0` + +* `save_extendExistingWithEmpty` + * Описание: Перезаписыать поля пустыми значениями (см. примеры ниже). + Следующие значения трактуются, как пустые: + * `""` — an empty string + * `[]` — an empty array + * `{}` — an empty object + * `null` + * Допустимые значения: + * `0` + * `1` + * Значение по умолчанию: `1` + +* `get` + * Описание: Ключ для получения данных из хранилища. + * Допустимые значения: `string` + * Значение по умолчанию: — + +* `get_tpl` + * Описание: Шаблон вывода. + + Доступные плейсхолдеры: + * `[+snippetResult+]` — данные из хранилища + + * Допустимые значения: + * `stringChunkName` + * `string` — передавать код напрямую без чанка можно начиная значение с `@CODE:` + * Значение по умолчанию: `'@CODE:[+snippetResult+]'` + +* `storage` + * Описание: Хранилище данных. + * Допустимые значения: + * `'post'` — `$_POST` + * `'session'` — `$_SESSION` + * Значение по умолчанию: `'post'` + + +### Примеры + + +#### Сохранить какие-нибудь данные + +``` +[[ddStash? + &save=`{ + "userData": { + "firstName": "Иван", + "lastName": "[[ddGetDocumentField? + &docId=`1` + &docField=`lastName` + ]]", + "children": [ + { + "firstName": "Алиса" + }, + { + "firstName": "Роберт" + } + ] + }, + "someData": "someValue" + }` +]] +``` + + +#### Получить сохранённые данные + + +##### Вы можете получить значение поля любого уровня вложенности + +``` +[[ddStash? &get=`someData`]] +``` + +Вернёт `someValue`. + +``` +[[ddStash? &get=`userData.firstName`]] +``` + +Вернёт `Иван`. + +``` +[[ddStash? &get=`userData.children.0.firstName`]] +``` + +Вернёт `Алиса`. + + +##### Ещё вы можете получить объекты в виде JSON + +Если значение поля — объект или массив, оно будет возвращено в формате JSON. + + +###### Получить первого ребёнка Ивана + +``` +[[ddStash? &get=`userData.children.0`]] +``` + +Вернёт: + +```json +{ + "firstName": "Алиса" +} +``` + + +###### Получить всех детей Ивана: + +``` +[[ddStash? &get=`userData.children`]] +``` + +Вернёт: + +```json +[ + { + "firstName": "Алиса" + }, + { + "firstName": "Роберт" + } +] +``` + + +###### Получить всю информацию об Иване + +``` +[[ddStash? &get=`userData`]] +``` + +Вернёт: + +```json +{ + "firstName": "Иван", + "lastName": "Иванов", + "children": [ + { + "firstName": "Алиса" + }, + { + "firstName": "Роберт" + } + ] +} +``` + + +#### Сохранение: Расширить существующий объект вместо его перезаписи (``&save_extendExisting=`1` ``) + +Для начала сохраняем какой-нибудь объект: + +``` +[[ddStash? + &save=`{ + "userData": { + "firstName": "Чак", + "lastName": "Иванов", + "children": [ + { + "firstName": "Алиса" + }, + { + "firstName": "Роберт" + } + ] + } + }` +]] +``` + +Затем если мы просто сохраним объект с таким же ключём (`userData`): + +``` +[[ddStash? + &save=`{ + "userData": { + "middleName": "Рэй", + "lastName": "Норрис" + } + }` +]] +``` + +Сниппет перепишет предыдущий сохранённый объект полностью: + +``` +[[ddStash? &get=`userData`]] +``` + +Вернёт: + +```json +{ + "middleName": "Рэй", + "lastName": "Норрис" +} +``` + +И так, если мы всё же хотим именно расширить первый объект, просто используем параметр `save_extendExisting`: + +``` +[[ddStash? + &save=`{ + "userData": { + "middleName": "Рэй", + "lastName": "Норрис" + } + }` + &save_extendExisting=`1` +]] +``` + +В этом случае сниппет рекурсивно расширит первый объект данными второго: + +``` +[[ddStash? &get=`userData`]] +``` + +Вернёт: + +```json +{ + "firstName": "Чак", + "middleName": "Рэй", + "lastName": "Норрис", + "children": [ + { + "firstName": "Алиса" + }, + { + "firstName": "Роберт" + } + ] +} +``` + + +#### Сохранение: Расширение объектов без перезаписи полей пустыми значениями (``&save_extendExistingWithEmpty=`0` ``) + +По умолчанию, полдя с пустыми занчениями (например, `''`) обрабатываются, как и все остальные значения и перезаписывают при расширении непустые. + +``` +[[ddStash? + &save=`{ + "userData": { + "firstName": "Иван", + "lastName": "Тесла", + "discipline": "Электротехника" + } + }` +]] +[[ddStash? + &save=`{ + "userData": { + "firstName": "Никола", + "lastName": "" + } + }` + &save_extendExisting=`1` +]] +``` + +Вернёт: + +```json +{ + "firstName" => "Никола", + "lastName" => "", + "discipline" => "Электротехника" +} +``` + +Пустое значение `lastName` из второго объекта перезаписало непустое значение `lastName` из первого объекта. + +Если нам такое не нужно и мы хотим игнориовать пустые значения, просто изпользуем параметр `save_extendExistingWithEmpty` == `0`: + +```php +[[ddStash? + &save=`{ + "userData": { + "firstName": "Иван", + "lastName": "Тесла", + "discipline": "Электротехника" + } + }` +]] +[[ddStash? + &save=`{ + "userData": { + "firstName": "Никола", + "lastName": "" + } + }` + &save_extendExisting=`1` + &save_extendExistingWithEmpty=`0` +]] +``` + +Вернёт: + +```json +{ + "firstName" => "Никола", + "lastName" => "Тесла", + "discipline" => "Электротехника" +} +``` + + + \ No newline at end of file From e691d0cf13360174d220e52b3692f39ec0d7e721 Mon Sep 17 00:00:00 2001 From: Ilyas Ronef Date: Sun, 3 May 2020 17:44:31 +0300 Subject: [PATCH 5/5] Prerelease --- CHANGELOG.md | 7 +++++++ CHANGELOG_ru.md | 7 +++++++ README.md | 2 +- README_ru.md | 2 +- composer.json | 2 +- ddStash_snippet.php | 2 +- 6 files changed, 18 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 73a755f..0d7a292 100644 --- a/CHANGELOG.md +++ b/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`). diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md index 381010f..8e72cf9 100644 --- a/CHANGELOG_ru.md +++ b/CHANGELOG_ru.md @@ -1,6 +1,13 @@ # (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`). diff --git a/README.md b/README.md index cfa7900..54e3707 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Save data as [JSON](https://en.wikipedia.org/wiki/JSON) or [Query string](https: Elements → Snippets: Create a new snippet with the following data: 1. Snippet name: `ddStash`. -2. Description: `1.1 Save data as JSON or QueryString, then extend if needed and use it later without database queries.`. +2. Description: `1.2 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. diff --git a/README_ru.md b/README_ru.md index 08d44ac..c778903 100644 --- a/README_ru.md +++ b/README_ru.md @@ -18,7 +18,7 @@ Элементы → Сниппеты: Создайте новый сниппет со следующими параметрами: 1. Название сниппета: `ddStash`. -2. Описание: `1.1 Сохраняйте данные в формате JSON или QueryString, затем расширяйте по необходимости и используйте позже без запросов к базе данных.`. +2. Описание: `1.2 Сохраняйте данные в формате JSON или QueryString, затем расширяйте по необходимости и используйте позже без запросов к базе данных.`. 3. Категория: `Core`. 4. Анализировать DocBlock: `no`. 5. Код сниппета (php): Вставьте содержимое файла `ddStash_snippet.php` из архива. diff --git a/composer.json b/composer.json index e7ef4a6..57d35d1 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "dd/evolutioncms-snippets-ddstash", "type": "modxevo-snippet", - "version": "1.1.0", + "version": "1.2.0", "description": "Save data as JSON or QueryString, then extend if needed and use it later without database queries.", "keywords": [ "modx", diff --git a/ddStash_snippet.php b/ddStash_snippet.php index cbbd4eb..b3bb53b 100644 --- a/ddStash_snippet.php +++ b/ddStash_snippet.php @@ -1,7 +1,7 @@