diff --git a/CHANGELOG.md b/CHANGELOG.md index e17a868..72f66a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,13 @@ # (MODX)EvolutionCMS.snippets.ddGetParentId changelog +## Version 1.4 (2023-09-04) +* \+ You can just call `\DDTools\Snippet::runSnippet` to run the snippet without DB and eval (see README → Examples). +* \+ README → Installation → Using (MODX)EvolutionCMS.libraries.ddInstaller. +* \+ README_ru, CHANGELOG_ru. +* \* Attention! (MODX)EvolutionCMS.libraries.ddTools >= 0.60 is required. + + ## Version 1.3.1 (2020-06-22) * \* Attention! (MODX)EvolutionCMS.libraries.ddTools >= 0.40.1 is required (not tested in older versions). * \* Compatibility with new versions of (MODX)EvolutionCMS.libraries.ddTools. @@ -24,9 +31,34 @@ * \* Refactoring and other changes. +## Version 1.2.1 (2018-12-09) +* \* Wrong variable name was fixed. + + +## Version 1.2 (2017-10-09) +* \+ Added support of the `@CODE:` keyword prefix in the `tpl` parameter. +* \+ Added an ability to return several parents (see the `result_itemsNumber` and `result_itemsGlue` parameters). +* \* The following parameters have been renamed (with backward compatibility): + * \* `tpl` → `result_itemTpl`. + * \* `toPlaceholder` → `result_toPlaceholder`. + * \* `placeholderName` → `result_toPlaceholder_name`. +* \* The snippet result will be returned in anyway (empty string for empty result). +* \* Attention! PHP >= 5.4 is required. +* \* Attention! (MODX)EvolutionCMS >= 1.1 is required. +* \* Attention! (MODX)EvolutionCMS.libraries.ddTools >= 0.20 is required. + + +## Version 1.1 (2014-11-05) +* \+ Negative values can now be passed to the `level` parameter for setting parent level from the end (`-1` — the last parent; `-2` — the parent before the last; etc). + + +## Version 1.0.1 (2013-08-10) +* \* The id of a current document will be returned if it has no parent (root document). + + ## Version 1.0 (2011-12-18) * \+ The first release. - + \ No newline at end of file diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md new file mode 100644 index 0000000..d9e5c59 --- /dev/null +++ b/CHANGELOG_ru.md @@ -0,0 +1,64 @@ +# (MODX)EvolutionCMS.snippets.ddGetParentId changelog + + +## Версия 1.4 (2023-09-04) +* \+ Запустить сниппет без DB и eval можно через `\DDTools\Snippet::runSnippet` (см. README → Примеры). +* \+ README → Установка → Используя (MODX)EvolutionCMS.libraries.ddInstaller. +* \+ README_ru, CHANGELOG_ru. +* \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.60. + + +## Версия 1.3.1 (2020-06-22) +* \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.40.1 (не тестировался с более ранними версиями). +* \* Совместимость с новыми версиями (MODX)EvolutionCMS.libraries.ddTools. +* \* README, CHANGELOG: Изменения стиля. +* \* README: + * \- Home. + * \+ Links. +* \* Composer.json → `require` → `dd/evolutioncms-libraries-ddtools`: + * \* Переименована из `dd/modxevo-library-ddtools`. + * \* Исправлен формат версии. + + +## Версия 1.3 (2020-03-02) +* \+ Пустые элементы после парсинга `result_itemTpl` будут игнорироваться (можно вызывать сторонние сниппеты в шаблоне и задавать свои условия отображения). +* \+ Composer.json → Require. + + +## Версия 1.2.2 (2020-02-11) +* \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.30. +* \* Исправлена ошибка, при которой `result_itemsNumber` всегда было равно `'all'`. +* \* Рефакторинг и прочие изменения. + + +## Версия 1.2.1 (2018-12-09) +* \* Исправлено неправильное имя переменной. + + +## Версия 1.2 (2017-10-09) +* \+ Добавлено указание шаблона `tpl` без чанка, через префикс `@CODE:` +* \+ Добавлена возможность возвращать несколько родителей (см. параметры `result_itemsNumber` и `result_itemsGlue`). +* \* Следующие параметры были переименованы (с обратной совместимостью): + * \* `tpl` → `result_itemTpl`. + * \* `toPlaceholder` → `result_toPlaceholder`. + * \* `placeholderName` → `result_toPlaceholder_name`. +* \* Результат сниппета возвращается всегда (пустой для пустой строки). +* \* Внимание! Требуется PHP >= 5.4. +* \* Внимание! Требуется (MODX)EvolutionCMS >= 1.1. +* \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.20. + + +## Версия 1.1 (2014-11-05) +* \+ Параметр `level` теперь может принимать отрицательные значения, чтобы задать уровень родителя с конца (`-1` соответствует последнему; `-2` — предпоследнему и т.д.). + + +## Версия 1.0.1 (2013-08-10) +* \* Если родителя нет (документ в корне), возвращается ID текущего документа. + + +## Версия 1.0 (2011-12-18) +* \+ Первый релиз. + + + + \ No newline at end of file diff --git a/README.md b/README.md index 5184b01..a6ae9fb 100644 --- a/README.md +++ b/README.md @@ -4,26 +4,55 @@ Gets document parent ID(s) of the required level. ## Requires -* PHP >= 5.4 +* PHP >= 5.6 * [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1 -* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.40.1 +* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.ru/modx/ddtools) >= 0.60 -## Documentation +## Installation -### Installation +### Using [(MODX)EvolutionCMS.libraries.ddInstaller](https://github.com/DivanDesign/EvolutionCMS.libraries.ddInstaller) -Elements → Snippets: Create a new snippet with the following data +Just run the following PHP code in your sources or [Console](https://github.com/vanchelo/MODX-Evolution-Ajax-Console): + +```php +//Include (MODX)EvolutionCMS.libraries.ddInstaller +require_once( + $modx->getConfig('base_path') . + 'assets/libs/ddInstaller/require.php' +); + +//Install (MODX)EvolutionCMS.snippets.ddGetParentId +\DDInstaller::install([ + 'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetParentId', + 'type' => 'snippet' +]); +``` + +* If `ddGetParentId` is not exist on your site, `ddInstaller` will just install it. +* If `ddGetParentId` is already exist on your site, `ddInstaller` will check it version and update it if needed. + + +### Manually + + +#### 1. Elements → Snippets: Create a new snippet with the following data 1. Snippet name: `ddGetParentId`. -2. Description: `1.3.1 Gets document parent ID(s) of the required level.`. +2. Description: `1.4 Gets document parent ID(s) of the required level.`. 3. Category: `Core`. 4. Parse DocBlock: `no`. 5. Snippet code (php): Insert content of the `ddGetParentId_snippet.php` file from the archive. -### Parameters description +#### 2. Elements → Manage Files + +1. Create a new folder `assets/snippets/ddGetParentId/`. +2. Extract the archive to the folder (except `ddGetParentId_snippet.php`). + + +## Parameters description * `id` * Desctription: Document Id. @@ -31,13 +60,13 @@ Elements → Snippets: Create a new snippet with the following data * Default value: `[*id*]` (current document) * `level` - * Desctription: Parent level + * Desctription: Parent level. + * Valid values: * `1` — the immediate parent * `2` — the parent of the immediate parent * `-1` — the last parent * `-2` — the parent before the last - * etc. - * Valid values: `integer` + * `integer` — etc * Default value: `1` * `result_itemsNumber` @@ -53,7 +82,7 @@ Elements → Snippets: Create a new snippet with the following data Available placeholders: * `[+id+]` — Parent ID. * Valid values: - * `string_chunkName` + * `stringChunkName` * `string` — use inline templates starting with `@CODE:` * Default value: `'@CODE:[+id+]'` @@ -75,10 +104,34 @@ Elements → Snippets: Create a new snippet with the following data * Default value: `'ddParent'` +## Examples + + +### Run the snippet through `\DDTools\Snippet::runSnippet` without DB and eval + +```php +//Include (MODX)EvolutionCMS.libraries.ddTools +require_once( + $modx->getConfig('base_path') . + 'assets/libs/ddTools/modx.ddtools.class.php' +); + +//Run (MODX)EvolutionCMS.snippets.ddGetParentId +\DDTools\Snippet::runSnippet([ + 'name' => 'ddGetParentId', + 'params' => [ + 'level' => -1 + ] +]); +``` + + ## Links -* [Home page](https://code.divandesign.biz/modx/ddgetparentid) +* [Home page](https://code.divandesign.ru/modx/ddgetparentid) * [Telegram chat](https://t.me/dd_code) +* [Packagist](https://packagist.org/packages/dd/evolutioncms-snippets-ddgetparentid) +* [GitHub](https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetParentId) - \ No newline at end of file + \ No newline at end of file diff --git a/README_ru.md b/README_ru.md new file mode 100644 index 0000000..025df59 --- /dev/null +++ b/README_ru.md @@ -0,0 +1,136 @@ +# (MODX)EvolutionCMS.snippets.ddGetParentId + +Получает ID родителя(ей) необходимого уровня. + + +## Использует +* PHP >= 5.6 +* [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1 +* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.ru/modx/ddtools) >= 0.60 + + +## Установка + + +### Используя [(MODX)EvolutionCMS.libraries.ddInstaller](https://github.com/DivanDesign/EvolutionCMS.libraries.ddInstaller) + +Просто вызовите следующий код в своих исходинках или модуле [Console](https://github.com/vanchelo/MODX-Evolution-Ajax-Console): + +```php +//Подключение (MODX)EvolutionCMS.libraries.ddInstaller +require_once( + $modx->getConfig('base_path') . + 'assets/libs/ddInstaller/require.php' +); + +//Установка (MODX)EvolutionCMS.snippets.ddGetParentId +\DDInstaller::install([ + 'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetParentId', + 'type' => 'snippet' +]); +``` + +* Если `ddGetParentId` отсутствует на вашем сайте, `ddInstaller` просто установит его. +* Если `ddGetParentId` уже есть на вашем сайте, `ddInstaller` проверит его версию и обновит, если нужно. + + +### Вручную + + +#### 1. Элементы → Сниппеты: Создайте новый сниппет со следующими параметрами + +1. Название сниппета: `ddGetParentId`. +2. Описание: `1.4 Получает ID родителя(ей) необходимого уровня.`. +3. Категория: `Core`. +4. Анализировать DocBlock: `no`. +5. Код сниппета (php): Вставьте содержимое файла `ddGetParentId_snippet.php` из архива. + + +#### 2. Элементы → Управление файлами + +1. Создайте новую папку `assets/snippets/ddGetParentId/`. +2. Извлеките содержимое архива в неё (кроме файла `ddGetParentId_snippet.php`). + + +## Описание параметров + +* `id` + * Описание: ID документа. + * Допустимые значения: `integer` + * Значение по умолчанию: `[*id*]` (текущий документ) + +* `level` + * Описание: Уровень родителя. + * Допустимые значения: + * `1` — непосредственный родитель + * `2` — родитель родителя + * `-1` — последний родитель + * `-2` — предпоследний родитель + * `integer` — etc + * Значение по умолчанию: `1` + +* `result_itemsNumber` + * Описание: Количество возвращаемых родителей. + * Допустимые значения: + * `integer` + * `'all'` + * Значение по умолчанию: `1` + +* `result_itemTpl` + * Описание: Шаблон (имя чанка) для вывода. + Пустые элементы после парсинга шаблона будут игнорироваться (можно вызывать сторонние сниппеты в шаблоне и задавать свои условия отображения). + Доступные плейсхолдеры: + * `[+id+]` — Parent ID. + * Допустимые значения: + * `stringChunkName` + * `string` — передавать код напрямую без чанка можно начиная значение с `@CODE:` + * Значение по умолчанию: `'@CODE:[+id+]'` + +* `result_itemsGlue` + * Описание: Строка, объединяющая элементы при рендеринге. + * Допустимые значения: `string` + * Значение по умолчанию: `''` + +* `result_toPlaceholder` + * Описание: Возвращать значение в плэйсхолдер. + * Допустимые значения: + * `0` + * `1` + * Значение по умолчанию: `0` + +* `result_toPlaceholder_name` + * Описание: Имя плэйсхолдера. + * Допустимые значения: `string` + * Значение по умолчанию: `'ddParent'` + + +## Примеры + +### Запустить сниппет через `\DDTools\Snippet::runSnippet` без DB и eval + +```php +//Подключение (MODX)EvolutionCMS.libraries.ddTools +require_once( + $modx->getConfig('base_path') . + 'assets/libs/ddTools/modx.ddtools.class.php' +); + +//Запуск (MODX)EvolutionCMS.snippets.ddGetParentId +\DDTools\Snippet::runSnippet([ + 'name' => 'ddGetParentId', + 'params' => [ + 'level' => -1 + ] +]); +``` + + +## Ссылки + +* [Home page](https://code.divandesign.ru/modx/ddgetparentid) +* [Telegram chat](https://t.me/dd_code) +* [Packagist](https://packagist.org/packages/dd/evolutioncms-snippets-ddgetparentid) +* [GitHub](https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetParentId) + + + \ No newline at end of file diff --git a/composer.json b/composer.json index 11b56bf..e80f795 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "dd/evolutioncms-snippets-ddgetparentid", "type": "modxevo-snippet", - "version": "1.3.1", + "version": "1.4.0", "description": "Gets document parent ID(s) of the required level.", "keywords": [ "modx", @@ -12,8 +12,25 @@ "evolution cms", "ddgetparentid" ], + "homepage": "https://code.divandesign.ru/modx/ddgetparentid", + "support": { + "chat": "https://t.me/dd_code" + }, + "authors": [ + { + "name": "Ilyas Ronef", + "email": "ilyas@DivanDesign.ru", + "homepage": "https://ronef.ru", + "role": "Owner" + } + ], "require": { - "php": ">=5.4.0", - "dd/evolutioncms-libraries-ddtools": ">=0.40.1" + "php": ">=5.6.0", + "dd/evolutioncms-libraries-ddtools": ">=0.60.0" + }, + "autoload": { + "psr-4": { + "ddGetParentId\\": "src/" + } } } \ No newline at end of file diff --git a/ddGetParentId_snippet.php b/ddGetParentId_snippet.php index c4e527c..762e3bf 100644 --- a/ddGetParentId_snippet.php +++ b/ddGetParentId_snippet.php @@ -1,120 +1,23 @@ getConfig('base_path') . 'assets/libs/ddTools/modx.ddtools.class.php' ); -//The snippet must return an empty string even if result is absent -$snippetResult = ''; - -//Bacward compatibility -extract(\ddTools::verifyRenamedParams([ - 'params' => $params, - 'compliance' => [ - 'result_itemTpl' => 'tpl', - 'result_toPlaceholder' => 'toPlaceholder', - 'result_toPlaceholder_name' => 'placeholderName', - ] -])); - -$id = - isset($id) ? - $id : - $modx->documentIdentifier -; -$result_itemsNumber = - isset($result_itemsNumber) ? - $result_itemsNumber : - 1 -; -$result_itemTpl = - isset($result_itemTpl) ? - $modx->getTpl($result_itemTpl) : - '[+id+]' -; -$result_itemsGlue = - isset($result_itemsGlue) ? - $result_itemsGlue : - '' -; -$result_toPlaceholder = - ( - isset($result_toPlaceholder) && - $result_toPlaceholder == '1' - ) ? - true : - false -; -$result_toPlaceholder_name = - isset($result_toPlaceholder_name) ? - $result_toPlaceholder_name : - 'ddParent' -; - -if (!isset($level)){ - $level = 1; -}else{ - //For backward compatibility - if ($level == 'ultimate'){ - $level = -1; - }else{ - $level = intval($level); - } -} - -$parents = \ddTools::getDocumentParentIds([ - 'docId' => $id, - 'level' => $level, - 'totalResults' => $result_itemsNumber +return \DDTools\Snippet::runSnippet([ + 'name' => 'ddGetParentId', + 'params' => $params ]); - -foreach ( - $parents as - $parentIndex => - $parentId -){ - //Parse item - $parents[$parentIndex] = \ddTools::parseText([ - 'text' => $result_itemTpl, - 'data' => [ - 'id' => $parentId - ] - ]); - - //Remove empty items - if (empty($parents[$parentIndex])){ - unset($parents[$parentIndex]); - } -} - -$snippetResult = implode( - $result_itemsGlue, - $parents -); - -//Если надо, выводим в плэйсхолдер -if ($result_toPlaceholder){ - $modx->setPlaceholder( - $result_toPlaceholder_name, - $snippetResult - ); - - $snippetResult = ''; -} - -return $snippetResult; ?> \ No newline at end of file diff --git a/require.php b/require.php new file mode 100644 index 0000000..68aea4c --- /dev/null +++ b/require.php @@ -0,0 +1,13 @@ + \ No newline at end of file diff --git a/src/Snippet.php b/src/Snippet.php new file mode 100644 index 0000000..8cc8d6f --- /dev/null +++ b/src/Snippet.php @@ -0,0 +1,109 @@ + 0, + 'result_itemsNumber' => 1, + 'result_itemTpl' => '@CODE:[+id+]', + 'result_itemsGlue' => '', + 'result_toPlaceholder' => false, + 'result_toPlaceholder_name' => 'ddParent', + 'level' => 1, + ], + + $paramsTypes = [ + 'id' => 'integer', + 'result_toPlaceholder' => 'boolean', + ], + + $renamedParamsCompliance = [ + 'result_itemTpl' => 'tpl', + 'result_toPlaceholder' => 'toPlaceholder', + 'result_toPlaceholder_name' => 'placeholderName', + ] + ; + + /** + * prepareParams + * @version 1.0 (2023-09-04) + * + * @param $params {stdClass|arrayAssociative|stringJsonObject|stringHjsonObject|stringQueryFormatted} + * + * @return {void} + */ + protected function prepareParams($params = []){ + //Call base method + parent::prepareParams($params); + + //ID is not set or invalid + if ($this->params->id <= 0){ + $this->params->id = \ddTools::$modx->documentIdentifier; + } + + $this->params->result_itemTpl = \ddTools::getTpl($this->params->result_itemTpl); + + //For backward compatibility + if ($this->params->level == 'ultimate'){ + $this->params->level = -1; + }else{ + $this->params->level = intval($this->params->level); + } + } + + /** + * run + * @version 1.0 (2023-09-04) + * + * @return {string|object|array} + */ + public function run(){ + $result = ''; + + $parents = \ddTools::getDocumentParentIds([ + 'docId' => $this->params->id, + 'level' => $this->params->level, + 'totalResults' => $this->params->result_itemsNumber + ]); + + foreach ( + $parents as + $parentIndex => + $parentId + ){ + //Parse item + $parents[$parentIndex] = \ddTools::parseText([ + 'text' => $this->params->result_itemTpl, + 'data' => [ + 'id' => $parentId + ] + ]); + + //Remove empty items + if (empty($parents[$parentIndex])){ + unset($parents[$parentIndex]); + } + } + + $result = implode( + $this->params->result_itemsGlue, + $parents + ); + + //Если надо, выводим в плэйсхолдер + if ($this->params->result_toPlaceholder){ + \ddTools::$modx->setPlaceholder( + $this->params->result_toPlaceholder_name, + $result + ); + + $result = ''; + } + + return $result; + } +} \ No newline at end of file