Version 1.7

DivanDesign · Sep 28, 2020 · 697a63c · 697a63c
2 parents a904cad + 4895e9b
commit 697a63c
Show file tree

Hide file tree

Showing 6 changed files with 715 additions and 56 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,62 @@
+# (MODX)EvolutionCMS.snippets.ddIf changelog
+
+
+## Version 1.7 (2020-09-28)
+* \* Attention! (MODX)Evolution.libraries.ddTools >= 0.40.1 is required (not tested with older versions).
+* \+ Parameters → `placeholders`: Nested arrays are supported too.
+* \+ README.
+* \+ README_ru.
+* \+ CHANGELOG.
+* \+ CHANGELOG_ru.
+* \+ Composer.json.
+
+
+## Version 1.6 (2018-12-05)
+* \+ Parameters → `trueChunk`, `falseChunk`: Added few placeholders:
+	* \+ `[+ddIf_operand1+]` — contains `operand1` value.
+	* \+ `[+ddIf_operand2+]` — contains `operand2` value.
+	* \+ `[+ddIf_operator+]` — contains `operator` value.
+
+
+## Version 1.5 (2018-10-31)
+* \+ Parameters → `debugTitle`: The new parameter. If you need to debug just set it and watch the System Event log.
+* \+ Parameters → `operand1`: If is equal to something like `[+somePlaceholder+]` the snippet interpretate it as `''`. It's convenient when placeholders were not parsed for any reason.
+
+
+## Version 1.4 (2017-02-10)
+* \* Attention! PHP >= 5.4 is required.
+* \* Attention! (MODX)Evolution >= 1.1 is required.
+* \* Attention! (MODX)Evolution.libraries.ddTools >= 0.18 is required.
+* \+ Parameters → `placeholders`: Added JSON and Query string support. The old format is still supported but deprecated.
+* \+ Parameters → `trueChunk`, `falseChunk`: Added support of the `@CODE:` keyword prefix.
+* \- Parameters → `trueString`, `falseString`: Are deprecated (use `@CODE:` prefix instead). Backward compatibility is preserved with message to the CMS Event log.
+* \* Small optimization and other changes.
+
+
+## Version 1.3 (2016-07-14)
+* \+ Parameter → `operator`:
+	* \+ Now can be equal to `isnumeric` — check the `operand1` is number or not.
+	* \+ Is not case sensitive.
+
+
+## Version 1.2 (2015-02-22)
+* \* Attention! (MODX)Evolution >= 1.0.13 is required.
+* \+ Parameters → `operator`: Now can gets a simple operator value instead of it’s letter alias (of course, with backward compatibility).
+* \+ Additional data (from the `placeholders` parameter) are processed in the `trueString` and `falseString` parameters too.
+* \* Refactoring:
+	* \* The `$result` variable has not been used for placeholders array anymore, the `$placeholder` variable instead.
+	* \* One `return` instead of several, `return` in any case.
+
+
+## Version 1.1 (2012-04-05)
+* \* Attention! Backward compatibility is broken. Actually the version should be named as 2.0 because of backward compatibility absence but renaming hasn’t been done on account of minor changes.
+* \* Attention! (MODX)Evolution.libraries.ddTools >= 0.2 is required.
+* \* Parameters:
+	* \* `operand1`: Has been renamed from `subject`.
+	* \* `operand2`: Has been renamed from `operand`.
+	* \* `trueChunk`: Has been renamed from `trueChank`.
+	* \* `falseChunk`: Has been renamed from `falseChank`.
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
+<style>ul{list-style:none;}</style>
diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md
@@ -0,0 +1,62 @@
+# (MODX)EvolutionCMS.snippets.ddIf changelog
+
+
+## Версия 1.7 (2020-09-28)
+* \* Внимание! Требуется (MODX)Evolution.libraries.ddTools >= 0.40.1 (не тестировался с более старыми версиями).
+* \+ Parameters → `placeholders`: Вложенные массивы также поддерживаются.
+* \+ README.
+* \+ README_ru.
+* \+ CHANGELOG.
+* \+ CHANGELOG_ru.
+* \+ Composer.json.
+
+
+## Версия 1.6 (2018-12-05)
+* \+ Параметры → `trueChunk`, `falseChunk`: Добавлено несколько плейсхолдеров:
+	* \+ `[+ddIf_operand1+]` — содержит значение `operand1`.
+	* \+ `[+ddIf_operand2+]` — содержит значение `operand2`.
+	* \+ `[+ddIf_operator+]` — содержит значение `operator`.
+
+
+## Версия 1.5 (2018-10-31)
+* \+ Параметры → `debugTitle`: Новый параметр. Если нужно подебажить, задайте его и смотрите Протокол событий CMS.
+* \+ Параметры → `operand1`: Если равен чему-то вроде `[+somePlaceholder+]`, сниппет интерпретирует это как `''`. Это удобно, когда какие-то плейсхолдеры не отпарсились по каким-либо причинам.
+
+
+## Версия 1.4 (2017-02-10)
+* \* Внимание! Требуется PHP >= 5.4.
+* \* Внимание! Требуется (MODX)Evolution >= 1.1.
+* \* Внимание! Требуется (MODX)Evolution.libraries.ddTools >= 0.18.
+* \+ Параметры → `placeholders`: Добавлена поддержка форматов JSON and Query string. Старый формат по прежнему поддерживается, но считается устаревшим.
+* \+ Параметры → `trueChunk`, `falseChunk`: Добавлена поддержка указания шаблонов через префикс `@CODE:`.
+* \- Параметры → `trueString`, `falseString`: больше не используются (вместо них используйте префикс `@CODE:`). Обратная совместимость сохранена с уведомлением в лог событий CMS.
+* \* Небольшая оптимизация и прочие изменения.
+
+
+## Версия 1.3 (2016-07-14)
+* \+ Parameter → `operator`:
+	* \+ Теперь может принимать значение `isnumeric` — является ли `operand1` числом или нет.
+	* \+ Теперь не чувствителен к регистру.
+
+
+## Версия 1.2 (2015-02-22)
+* \* Внимание! Требуется (MODX)Evolution >= 1.0.13.
+* \+ Параметры → `operator`: Поддерживает простое указание оператора, вместо буквенных псевдонимов (те тоже работают для обратной совместимости).
+* \+ Дополнительные данные (из параметра `placeholders`) также передаются в `trueString` и `falseString`.
+* \* Рефакторинг:
+	* \* Переменная `$result` как массив плэйсхолдеров больше не используется, переменная `$placeholders` используется вместо неё повторно.
+	* \* Один `return` вместо нескольких, в любом случае `return`.
+
+
+## Версия 1.1 (2012-04-05)
+* \* Внимание, нарушена обратная совместимость! Вообще говоря, версию надо бы назвать 2.0 из-за отсутствия обратной совместимости, но изменения настолько незначительные, что рука не поднимается.
+* \* Внимание! Требуется (MODX)Evolution.libraries.ddTools >= 0.2.
+* \* Параметры:
+	* \* `operand1`: Переименован из `subject`.
+	* \* `operand2`: Переименован из `operand`.
+	* \* `trueChunk`: Переименован из `trueChank`.
+	* \* `falseChunk`: Переименован из `falseChank`.
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
+<style>ul{list-style:none;}</style>
diff --git a/README.md b/README.md
@@ -1,5 +1,210 @@
 # (MODX)EvolutionCMS.snippets.ddIf
 
-This snippet compares 2 values and returns required chunk or string.
-___
-Visit the following [link](http://code.divandesign.biz/modx/ddif) to read the documentation, instructions & changelog.
+This snippet compares different values and returns required chunk or string.
+
+
+## Requires
+
+* PHP >= 5.4
+* [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
+* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.40.1 (not tested with older versions)
+
+
+## Documentation
+
+
+### Installation
+
+Elements → Snippets: Create a new snippet with the following data:
+
+1. Snippet name: `ddIf`.
+2. Description: `<b>1.7</b> This snippet compares different values and returns required chunk or string.`.
+3. Category: `Core`.
+4. Parse DocBlock: `no`.
+5. Snippet code (php): Insert content of the `ddIf_snippet.php` file from the archive.
+
+
+### Parameters description
+
+* `operand1`
+	* Desctription: The first operand for comparing.
+	* Valid values: `string`
+	* **Required**
+
+* `operand2`
+	* Desctription: The second operand for comparing.
+	* Valid values: `string`
+	* Default value: `''`
+
+* `operator`
+	* Desctription: Comparing operator.
+	* Valid values:
+		* `'=='`
+		* `'!='`
+		* `'>'`
+		* `'<'`
+		* `'<='`
+		* `'>='`
+		* `'bool'`
+		* `'inarray'`
+		* `'isnumeric'`
+	* Default value: `'=='`
+
+* `trueChunk`
+	* Desctription: This value is returning if result is true.
+		Available placeholders:
+		* `[+ddIf_operand1+]` — contains `operand1` value.
+		* `[+ddIf_operand2+]` — contains `operand2` value.
+		* `[+ddIf_operator+]` — contains `operator` value.
+		* `[+`any placeholders from the `placeholders` parameter`+]`
+	* Valid values:
+		* `stringChunkName`
+		* `string` — use inline templates starting with `@CODE:`
+	* Default value: `''`
+
+* `falseChunk`
+	* Desctription: This value is returning if result is false. 
+		Available placeholders:
+		* `[+ddIf_operand1+]` — contains `operand1` value.
+		* `[+ddIf_operand2+]` — contains `operand2` value.
+		* `[+ddIf_operator+]` — contains `operator` value.
+		* `[+`any placeholders from the `placeholders` parameter`+]`
+	* Valid values:
+		* `stringChunkName`
+		* `string` — use inline templates starting with `@CODE:`
+	* Default value: `''`
+
+* `placeholders`
+	* Desctription:
+		Additional data has to be passed into the `trueChunk` and `falseChunk`.  
+		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:
+		* `stringJsonObject` — as [JSON](https://en.wikipedia.org/wiki/JSON)
+		* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* It can also be set as a PHP object or array (e. g. for calls through `$modx->runSnippet`).
+			* `arrayAssociative`
+			* `object`
+	* Default value: —
+
+* `debugTitle`
+	* Desctription: The title for the System Event log if debugging is needed.  
+		Just set it and watch the System Event log.
+	* Valid values: `string`
+	* Default value: —
+
+
+### Examples
+
+
+#### String comparison
+
+```
+[[ddIf?
+	&operand1=`Test string 1`
+	&operator=`==`
+	&operand2=`Test string 2`
+	&trueChunk=`@CODE:The strings are equal.`
+	&falseChunk=`@CODE:The strings are not equal.`
+]]
+```
+
+Returns:
+
+```
+The strings are not equal.
+```
+
+
+#### Checks if a value exists in an array
+
+```
+[[ddIf?
+	&operand1=`Apple`
+	&operator=`inarray`
+	&operand2=`Pear,Banana,Apple,Orange`
+	&trueChunk=`@CODE:Exists.`
+	&falseChunk=`@CODE:Not exists.`
+]]
+```
+
+Returns:
+
+```
+Exists.
+```
+
+
+#### Checks if a `operand1` value is number or not
+
+```
+[[ddIf?
+	&operand1=`123`
+	&operator=`isnumeric`
+	&trueChunk=`@CODE:Number.`
+	&falseChunk=`@CODE:Not number.`
+]]
+```
+
+Returns:
+
+```
+Number.
+```
+
+
+#### Number comparison and pass additional data to chunks
+
+```
+[[ddIf?
+	&operand1=`[*general_price*]`
+	&operator=`<`
+	&operand2=`500`
+	&trueChunk=`general_goodInexpensive`
+	&falseChunk=`general_good`
+	&placeholders=`{
+		"title": "[*pagetitle*]",
+		"image": "[*general_image*]",
+		"somethingText": "All we need is love!"
+	}`
+]]
+```
+
+Code of the `general_good` chunk:
+
+```html
+<div>
+	<h2>[+title+], $[+ddIf_operand1+]</h2>
+	<img src="[+image+]" alt="[+title+]" />
+</div>
+```
+
+Code of the `general_goodInexpensive` chunk:
+
+```html
+<div class="inexpensive">
+	<h2>[+title+], <strong>$[+ddIf_operand1+]</strong></h2>
+	<img src="[+image+]" alt="[+title+]" />
+	<p>[+somethingText+]</p>
+</div>
+```
+
+Let `[*general_price*]` be equal to `120`, then the snippet returns:
+
+```html
+<div class="inexpensive">
+	<h2>Some inexpensive good, <strong>$120</strong></h2>
+	<img src="assets/images/goods/some1.jpg" alt="Some inexpensive good" />
+</div>
+```
+
+
+## Links
+
+* [Home page](https://code.divandesign.biz/modx/ddif)
+* [Telegram chat](https://t.me/dd_code)
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />