diff --git a/CHANGELOG.md b/CHANGELOG.md index 9733049..9277dbc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,13 @@ # (MODX)EvolutionCMS.libraries.ddTools changelog +## Version 0.49 (2021-04-25) +* \* `\ddTools::parseText`: + * \+ Parameters → `$params->data`: Can also be set as JSON, HJSON or Query string. + * \* `\DDTools\ObjectTools::extend` is used instead of `array_merge`. +* \+ README → Documentation → Parameters description → `\ddTools::parseText($params)`. + + ## Version 0.48.2 (2021-03-31) * \* `\DDTools\ObjectTools::extend`: Added deep object cloning to prevent references. diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md index c768a6e..9d282ff 100644 --- a/CHANGELOG_ru.md +++ b/CHANGELOG_ru.md @@ -1,6 +1,13 @@ # (MODX)EvolutionCMS.libraries.ddTools changelog +## Версия 0.49 (2021-04-25) +* \* `\ddTools::parseText`: + * \+ Параметры → `$params->data`: Также может быть задан как JSON, HJSON или Query string. + * \* `\DDTools\ObjectTools::extend` исползуется вместо `array_merge`. +* \+ README → Документация → Описание параметров → `\ddTools::parseText($params)`. + + ## Версия 0.48.2 (2021-03-31) * \* `\DDTools\ObjectTools::extend`: Добавлено глубокое клонирование объектов для предотвращения ссылок. diff --git a/README.md b/README.md index 9d87791..9db2156 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,73 @@ _ddTools version must be 0.14 or higher to use this method. If you use it, the c ### Parameters description +#### `\ddTools::parseText($params)` + +Replaces placeholders in a text with required values. +Like `$modx->parseChunk`, but takes a text and has some features. + +* `$params` + * Desctription: Parameters, the pass-by-name style is used. + * Valid values: + * `stdClass` + * `arrayAssociative` + * **Required** + +* `$params->text` + * Desctription: String to parse. + * Valid values: `string` + * **Required** + +* `$params->data` + * Desctription: + The array of additional data has to be replaced in `$params->text`. + Nested objects and arrays are supported too: + * `{"someOne": "1", "someTwo": "test" }` => `[+someOne+], [+someTwo+]`. + * `{"some": {"a": "one", "b": "two"} }` => `[+some.a+]`, `[+some.b+]`. + * `{"some": ["one", "two"] }` => `[+some.0+]`, `[+some.1+]`. + * Valid values: + * `arrayAssociative` + * `stdClass` + * `stringJsonObject` — as [JSON](https://en.wikipedia.org/wiki/JSON) + * `stringHjsonObject` — as [HJSON](https://hjson.github.io/) + * `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string) + * Default value: `[]` + +* `$params->data->{$key}` + * Valid values: Key is placeholder name, value is value. + * `string` + * `array` + * `object` + * **Required** + +* `$params->placeholderPrefix` + * Desctription: Placeholders prefix. + * Valid values: `string` + * Default value: `'[+'` + +* `$params->placeholderSuffix` + * Desctription: Placeholders suffix. + * Valid values: `string` + * Default value: `'+]'` + +* `$params->removeEmptyPlaceholders` + * Desctription: Do you need to remove empty placeholders? + * Valid values: `boolean` + * Default value: `false` + +* `$params->mergeAll` + * Desctription: Additional parsing of document fields, settings, chunks. + * Valid values: `boolean` + * Default value: `true` + + +##### Returns + +* `$result` + * Desctription: Parsed text. + * Valid values: `string` + + #### `\ddTools::verifyRenamedParams($params)` The method checks an array for deprecated parameters and writes warning messages into the MODX event log. diff --git a/composer.json b/composer.json index b6b448b..89bbb8d 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "dd/evolutioncms-libraries-ddtools", "type": "modxevo-library-ddtools", - "version": "0.48.2", + "version": "0.49.0", "description": "A library with various tools facilitating your work.", "keywords": [ "modx", diff --git a/modx.ddtools.class.php b/modx.ddtools.class.php index 2d03b7e..8afe130 100644 --- a/modx.ddtools.class.php +++ b/modx.ddtools.class.php @@ -1,7 +1,7 @@ parseChunk, but takes a text. - * - * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required - * @param $params->text {string} — String to parse. @required - * @param $params->data {stdClass|arrayAssociative} — Array of values. Nested arrays are supported too: “['stringPlaceholder' = > 'one', 'arrayPlaceholder' => ['a' => 'one', 'b' => 'two']]” => “[+stringPlaceholder+]”, “[+arrayPlaceholder.a+]”, “[+arrayPlaceholder.b+]”. Default: []. - * @param $params->data->{$key} {string|stdClass|arrayAssociative} — Key — placeholder name, value — value. - * @param $params->placeholderPrefix {string} — Placeholders prefix. Default: '[+'. - * @param $params->placeholderSuffix {string} — Placeholders suffix. Default: '+]'. - * @param $params->removeEmptyPlaceholders {boolean} — Do you need to remove empty placeholders? Default: false. - * @param $params->mergeAll {boolean} — Additional parsing the document fields, settings, chunks. Default: true. - * - * @return {string} + * @see README.md */ public static function parseText($params = []){ //For backward compatibility @@ -928,25 +917,28 @@ public static function parseText($params = []){ ]); } - //Defaults - $params = (object) array_merge( - [ - 'text' => '', - 'data' => [], - 'placeholderPrefix' => '[+', - 'placeholderSuffix' => '+]', - 'removeEmptyPlaceholders' => false, - 'mergeAll' => true - ], - (array) $params - ); + $params = \DDTools\ObjectTools::extend([ + 'objects' => [ + //Defaults + (object) [ + 'text' => '', + 'data' => [], + 'placeholderPrefix' => '[+', + 'placeholderSuffix' => '+]', + 'removeEmptyPlaceholders' => false, + 'mergeAll' => true + ], + $params + ] + ]); - $result = $params->text; + $params->data = \DDTools\ObjectTools::convertType([ + 'object' => $params->data, + 'type' => 'objectArray' + ]); - //Convert stdClass to array - if (!is_array($params->data)){ - $params->data = (array) $params->data; - } + + $result = $params->text; //Если значения для парсинга переданы if (!empty($params->data)){