Version 3.0

DivanDesign · May 8, 2020 · 583ae18 · 583ae18
2 parents 1e1332f + c0ae302
commit 583ae18
Show file tree

Hide file tree

Showing 7 changed files with 798 additions and 188 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,35 @@
+# (MODX)EvolutionCMS.snippets.ddColorTools changelog
+
+
+## Version 3.0 (2020-05-08)
+* \* Attention! (MODX)EvolutionCMS.snippets.ddGetDocumentField >= 2.10.1 is required.
+* \* Attention! (MODX)EvolutionCMS.libraries.ddTools >= 0.32 is required.
+* \* Attention! Backward compatibility is broken:
+	* \* `HSB` renamed as `HSL` inside the snippet.
+	* \* Parameters:
+		* \* The following were renamed:
+			* \* `offset_b` → `offset_l`
+			* \* `outputFormat` → `result_outputFormat`
+		* \* `result_outputFormat`:
+			* \* If equal to `hsl` then full color string will be returned (`hsl(0, 0%, 0%)`).
+			* \* Default value: Is equal to `hsl` instead of `hex`.
+* \+ Parameters → `inputColor`: Added the ability to set as HSL.
+* \+ Parameters → `offset_` (all): Supports multiple operations.
+* \+ Parameters → `result_outputFormat`: Case-insensitive.
+* \+ Parameters → `result_tpl`.
+* \+ Parameters → `result_tpl_placeholders`.
+* \* The snippet will return an empty string even if result is absent.
+* \* Refactoring.
+* \+ Composer.json.
+* \+ README.
+* \+ README_ru.
+* \+ CHANGELOG.
+* \+ CHANGELOG_ru.
+
+
+## Version 2.0 (2017-05-22)
+* \+ Initial commit.
+
+
+<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,35 @@
+# (MODX)EvolutionCMS.snippets.ddColorTools changelog
+
+
+## Version 3.0 (2020-05-08)
+* \* Внимание! Требуется (MODX)EvolutionCMS.snippets.ddGetDocumentField >= 2.10.1.
+* \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.32.
+* \* Внимание! Обратная совместимость нарушена:
+	* \* `HSB` переименован в `HSL` внутри сниппета.
+	* \* Параметры:
+		* \* Следующие переименованы:
+			* \* `offset_b` → `offset_l`
+			* \* `outputFormat` → `result_outputFormat`
+		* \* `result_outputFormat`:
+			* \* Если равен `hsl` — будет возвращёно полное представление цвета (`hsl(0, 0%, 0%)`).
+			* \* Значение по умолчанию: Равно `hsl` вместо `hex`.
+* \+ Параметры → `inputColor`: Добавлена возможность задавать в формате HSL.
+* \+ Параметры → `offset_` (все): Добавлена поддержка множественных операций.
+* \+ Параметры → `result_outputFormat`: Значение регистронезависимо.
+* \+ Параметры → `result_tpl`.
+* \+ Параметры → `result_tpl_placeholders`.
+* \* Сниппет вернёт пустую строку в случае если результ пуст.
+* \* Рефакторинг.
+* \+ Composer.json.
+* \+ README.
+* \+ README_ru.
+* \+ CHANGELOG.
+* \+ CHANGELOG_ru.
+
+
+## Версия 2.0 (2017-05-22)
+* \+ Начальный кэммит.
+
+
+<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,4 +1,134 @@
-# ddColorTools
+# (MODX)EvolutionCMS.snippets.ddColorTools
 
-Преобразует цвет в соответствии со смещением по тону, яркости или насыщенности.
-___
+Converts the color to match the offset in tone, brightness, or saturation.
+
+
+## Requires
+
+* PHP >= 5.6
+* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.32
+* [(MODX)EvolutionCMS.snippets.ddGetDocumentField](https://code.divandesign.biz/modx/ddgetdocumentfield) >= 2.10.1
+
+
+## Documentation
+
+
+### Installation
+
+Elements → Snippets: Create a new snippet with the following data:
+
+1. Snippet name: `ddColorTools`.
+2. Description: `<b>3.0</b> Converts the color to match the offset in tone, brightness, or saturation.`.
+3. Category: `Core`.
+4. Parse DocBlock: `no`.
+5. Snippet code (php): Insert content of the `ddColorTools_snippet.php` file from the archive.
+
+
+### Parameters description
+
+
+#### Input color
+
+* `inputColor`
+	* Desctription: Input color as HEX or HSL.  
+		Case-insensitive.    
+		Valid format examples:
+		* `ffffff`
+		* `#FFFFFF`
+		* `hsl(0, 0%, 100%)`
+		* `HSL(0, 0, 100)`
+	* Valid values: `string`
+	* **Required**
+
+* `inputColor_docField`
+	* Desctription: The name of the document field / TV which value is required to get.  
+		If the parameter is passed then the input string will be taken from the field / TV and `inputColor` will be ignored.
+	* Valid values: `string`
+	* Default value: —
+
+* `inputColor_docId`
+	* Desctription: ID of the document which field/TV value is required to get.  
+		`inputColor_docId` equals the current document id since `inputString_docId` is unset.
+	* Valid values: `integer`
+	* Default value: —
+
+
+#### Color modification
+
+All parameters can contain the following special operators:
+1. `+` (e. g. `+10`) — plus
+2. `-` (e. g. `-10`) — minus
+3. `abs` — round to max or min value
+4. `r` — invert
+5. without operator (e. g. `10`) — just set equal to
+
+* `offset_h`
+	* Desctription: Operations of the hue offset separated by commas.
+	* Valid values: `stringCommaSeparated`
+	* Default value: `'+0'`
+
+* `offset_h[i]`
+	* Desctription: Offset of the hue in degrees (`[-360; +360]`).
+	* Valid values: `string`
+	* **Required**
+
+* `offset_s`
+	* Desctription: Operations of the saturation offset separated by commas.
+	* Valid values: `stringCommaSeparated`
+	* Default value: `'+0'`
+
+* `offset_s[i]`
+	* Desctription: Offset of the saturation in persents (`[-100; +100]`).
+	* Valid values: `string`
+	* **Required**
+
+* `offset_l`
+	* Desctription: Operations of the lightness offset separated by commas.
+	* Valid values: `stringCommaSeparated`
+	* Default value: `'+0'`
+
+* `offset_l[i]`
+	* Desctription: Offset of the lightness in persents (`[-100; +100]`).
+	* Valid values: `string`
+	* **Required**
+
+
+#### Output
+
+* `result_outputFormat`
+	* Desctription: Output color format.  
+		Case-insensitive.
+	* Valid values:
+		* `'hex'`
+		* `'hsl'`
+	* Default value: `'hsl'`
+
+* `result_tpl`
+	* Desctription: Chunk to parse result.  
+		Available placeholders:
+		* `[+ddResult+]` — full color string
+		* `[+ddH+]` — hue
+		* `[+ddS+]` — saturation
+		* `[+ddL+]` — lightness
+	* Valid values:
+		* `stringChunkName`
+		* `string` — use inline templates starting with `@CODE:`
+	* Default value: —
+
+* `result_tpl_placeholders`
+	* Desctription:
+		Additional data has to be passed into the `result_tpl`.  
+		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)
+	* Default value: —
+
+
+## [Home page →](https://code.divandesign.biz/modx/ddcolortools)
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
diff --git a/README_ru.md b/README_ru.md
@@ -0,0 +1,134 @@
+# (MODX)EvolutionCMS.snippets.ddColorTools
+
+Преобразует цвет в соответствии со смещением по тону, яркости или насыщенности.
+
+
+## Использует
+
+* PHP >= 5.6
+* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.32
+* [(MODX)EvolutionCMS.snippets.ddGetDocumentField](https://code.divandesign.biz/modx/ddgetdocumentfield) >= 2.10.1
+
+
+## Документация
+
+
+### Установка
+
+Элементы → Сниппеты: Создайте новый сниппет со следующими параметрами:
+
+1. Название сниппета: `ddColorTools`.
+2. Описание: `<b>3.0</b> Преобразует цвет в соответствии со смещением по тону, яркости или насыщенности.`.
+3. Категория: `Core`.
+4. Анализировать DocBlock: `no`.
+5. Код сниппета (php): Вставьте содержимое файла `ddColorTools_snippet.php` из архива.
+
+
+### Описание параметров
+
+
+#### Исходный цвет
+
+* `inputColor`
+	* Описание: Исходный цвет в HEX или HSL.  
+		Значение регистронезависимо.  
+		Примеры валидных значений:
+		* `ffffff`
+		* `#FFFFFF`
+		* `hsl(0, 0%, 100%)`
+		* `HSL(0, 0, 100)`
+	* Допустимые значения: `string`
+	* **Обязателен**
+
+* `inputColor_docField`
+	* Описание: Имя поля документа / TV, содержащего значение.  
+		Если задать этот параметр, параметр `inputColor` игнорируется, значение получается из указанного поля документа.
+	* Допустимые значения: `string`
+	* Значение по умолчанию: —
+
+* `inputColor_docId`
+	* Описание: ID документа, значение поля которого нужно получить.  
+		Если не задан, берётся ID текущего документа.
+	* Допустимые значения: `integer`
+	* Значение по умолчанию: —
+
+
+#### Модификация цвета
+
+Все параметры могут содержать следующие специальные операторы:
+1. `+` (например, `+10`) — прибавить
+2. `-` (например, `-10`) — отнять
+3. `abs` — округлить до максимального или минимального значения
+4. `r` — инвертировать
+5. без оператора (например, `10`) — просто установить, как указано
+
+* `offset_h`
+	* Описание: Операции смещения цветового тона через запятую.
+	* Допустимые значения: `stringCommaSeparated`
+	* Значение по умолчанию: `'+0'`
+
+* `offset_h[i]`
+	* Описание: Смещение цветового тона в градусах (`[-360; +360]`).
+	* Допустимые значения: `string`
+	* **Обязателен**
+
+* `offset_s`
+	* Описание: Операции смещения насыщенности через запятую.
+	* Допустимые значения: `stringCommaSeparated`
+	* Значение по умолчанию: `'+0'`
+
+* `offset_s[i]`
+	* Описание: Смещение насыщенности в процентах (`[-100; +100]`).
+	* Допустимые значения: `string`
+	* **Обязателен**
+
+* `offset_l`
+	* Описание: Операции смещения яркости через запятую.
+	* Допустимые значения: `stringCommaSeparated`
+	* Значение по умолчанию: `'+0'`
+
+* `offset_l[i]`
+	* Описание: Смещение яркости в процентах (`[-100; +100]`).
+	* Допустимые значения: `string`
+	* **Обязателен**
+
+
+#### Вывод результата
+
+* `result_outputFormat`
+	* Описание: В каком формате возвращать цвет?  
+		Значение регистронезависимо.
+	* Допустимые значения:
+		* `'hex'`
+		* `'hsl'`
+	* Значение по умолчанию: `'hsl'`
+
+* `result_tpl`
+	* Описание: Чанк, через который выводить (если нужно).  
+		Доступные плейсхолдеры:
+		* `[+ddResult+]` — полная строка цвета
+		* `[+ddH+]` — цветовой тон
+		* `[+ddS+]` — насыщенность
+		* `[+ddL+]` — яркость
+	* Допустимые значения:
+		* `stringChunkName`
+		* `string` — передавать код напрямую без чанка можно начиная значение с `@CODE:`
+	* Значение по умолчанию: —
+
+* `result_tpl_placeholders`
+	* Описание:
+		Дополнительные данные, которые будут переданы в чанк `result_tpl`.  
+		Вложенные объекты и массивы также поддерживаются:
+		* `{"someOne": "1", "someTwo": "test" }` => `[+someOne+], [+someTwo+]`.
+		* `{"some": {"a": "one", "b": "two"} }` => `[+some.a+]`, `[+some.b+]`.
+		* `{"some": ["one", "two"] }` => `[+some.0+]`, `[+some.1+]`.
+	* Допустимые значения:
+		* `stringJsonObject` — as [JSON](https://en.wikipedia.org/wiki/JSON)
+		* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
+	* Значение по умолчанию: —
+
+
+## [Home page →](https://code.divandesign.biz/modx/ddcolortools)
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
diff --git a/composer.json b/composer.json
@@ -0,0 +1,30 @@
+{
+	"name": "dd/evolutioncms-snippets-ddcolortools",
+	"type": "modxevo-snippet",
+	"version": "3.0.0",
+	"description": "Converts the color to match the offset in tone, brightness, or saturation.",
+	"keywords": [
+		"modx",
+		"modx evo",
+		"modx evolution",
+		"evo",
+		"evo cms",
+		"evolutioncms",
+		"evolution cms",
+		"dd group",
+		"dd studio",
+		"divandesign",
+		"ddcolortools",
+		"color tools",
+		"color convert",
+		"hsl convert",
+		"rgb convert",
+		"rgb to hsl",
+		"hsl to rgb"
+	],
+	"require": {
+		"php": ">=5.6.0",
+		"dd/evolutioncms-libraries-ddtools": ">=0.32.0",
+		"dd/evolutioncms-snippets-ddgetdocumentfield": ">=2.10.1"
+	}
+}