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