Version 1.8

CHANGELOG.md

@@ -1,6 +1,14 @@
 # (MODX)EvolutionCMS.snippets.ddGetDocuments changelog
 
 
+## Version 1.8 (2024-10-06)
+
+* \+ Outputters → Json → Parameters:
+	* \+ `outputterParams->templates->noResults`: The new optional parameter. Allows to specify a chunk or text to output when no items found.
+	* \+ `outputterParams->templates->wrapper`: The new optional parameter. Allows to specify a wrapper template.
+* \* Providers → Select → Parameters → `providerParams->ids`: If the required parameter is empty, nothing will be returned.
+
+
 ## Version 1.7 (2024-10-06)
 
 * \+ Outputters → Json → Parameters:

CHANGELOG_ru.md

@@ -1,6 +1,14 @@
 # (MODX)EvolutionCMS.snippets.ddGetDocuments changelog
 
 
+## Версия 1.8 (2024-10-06)
+
+* \+ Outputters → Json → Параметры:
+	* \+ `outputterParams->templates->noResults`: Новый необязательный параметр. Позволяет задать чанк или текст, который нужно вывести, когда ничего не найдено.
+	* \+ `outputterParams->templates->wrapper`: Новый необязательный параметр. Позволяет задать шаблон-обёртку.
+* \* Providers → Select → Параметры → `providerParams->ids`: Если обязательный параметр пуст, ничего не выведется.
+
+
 ## Версия 1.7 (2024-10-06)
 
 * \+ Outputters → Json → Параметры:

README.md

@@ -28,7 +28,6 @@ require_once(
 // Install (MODX)EvolutionCMS.snippets.ddGetDocuments
 \DDInstaller::install([
 	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDocuments',
-	'type' => 'snippet',
 ]);
 ```
 
@@ -42,7 +41,7 @@ require_once(
 #### 1. Elements → Snippets: Create a new snippet with the following data
 
 1. Snippet name: `ddGetDocuments`.
-2. Description: `<b>1.7</b> A snippet for fetching and parsing resources from the document tree or custom DB table by a custom rule.`.
+2. Description: `<b>1.8</b> A snippet for fetching and parsing resources from the document tree or custom DB table by a custom rule.`.
 3. Category: `Core`.
 4. Parse DocBlock: `no`.
 5. Snippet code (php): Insert content of the `ddGetDocuments_snippet.php` file from the archive.
@@ -307,7 +306,25 @@ Get resources from custom DB table.
 	* Valid values:
 		* `stringChunkName`
 		* `string` — use inline templates starting with `@CODE:`
-	* **Required**
+	* Default value: —
+
+* `outputterParams->templates->noResults`
+	* Description: A chunk or text to output when no items found.
+	* Valid values:
+		* `stringChunkName`
+		* `string` — use inline templates starting with `@CODE:`
+	* Default value: `'[]'`
+
+* `outputterParams->templates->wrapper`
+	* Description: Wrapper template.
+		* Available placeholders:
+			* `[+ddGetDocuments_items+]`
+			* `[+total+]` — number of returned items
+			* `[+totalFound+]` — number of found items
+	* Valid values:
+		* `stringChunkName`
+		* `string` — use inline templates starting with `@CODE:`
+	* Default value: `'[+ddGetDocuments_items+]'`
 
 
 #### Outputter → Sitemap (``&outputter=`sitemap` ``)

composer.json

@@ -1,7 +1,7 @@
 {
 	"name": "dd/evolutioncms-snippets-ddgetdocuments",
 	"type": "modxevo-snippet",
-	"version": "1.7.0",
+	"version": "1.8.0",
 	"description": "A snippet for fetching and parsing resources from the document tree or custom DB table by a custom rule.",
 	"keywords": [
 		"modx",

ddGetDocuments_snippet.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * ddGetDocuments
- * @version 1.7 (2024-10-06)
+ * @version 1.8 (2024-10-06)
  * 
  * @see README.md
  * 

src/DataProvider/Select/DataProvider.php

@@ -32,4 +32,27 @@ public function get(){
 			'resourcesIds' => $this->ids
 		]);
 	}
+
+	/**
+	 * prepareQuery
+	 * @version 1.0 (2024-10-06)
+	 * 
+	 * @param $params {arrayAssociative|stdClass}
+	 * @param $params['resourcesIds'] — Document IDs to get ($this->filter will be used).
+	 * 
+	 * @return $result {string}
+	 */
+	protected function prepareQuery($params = []){
+		return
+			// resourcesIds is required
+			!empty(
+				\DDTools\Tools\Objects::getPropValue([
+					'object' => $params,
+					'propName' => 'resourcesIds',
+				])
+			)
+			? parent::prepareQuery($params)
+			: ''
+		;
+	}
 }

src/Outputter/Json/Outputter.php

@@ -7,7 +7,7 @@
 class Outputter extends \ddGetDocuments\Outputter\Outputter {
 	/**
 	 * parse
-	 * @version 2.5 (2024-10-05)
+	 * @version 2.7 (2024-10-06)
 	 * 
 	 * @param $data {Output}
 	 * 
@@ -76,10 +76,37 @@ public function parse(Output $data){
 			$result[] = $result_item;
 		}
 
-		// JSON_UNESCAPED_UNICODE — Не кодировать многобайтные символы Unicode || JSON_UNESCAPED_SLASHES — Не экранировать /
-		return json_encode(
-			$result,
-			JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
-		);
+		if (
+			empty($result)
+			&& \DDTools\Tools\Objects::isPropExists([
+				'object' => $this->templates,
+				'propName' => 'noResults',
+			])
+		){
+			$result = $this->templates->noResults;
+		}else{
+			$result = \DDTools\Tools\Objects::convertType([
+				'object' => $result,
+				'type' => 'stringJsonAuto',
+			]);
+
+			if (
+				\DDTools\Tools\Objects::isPropExists([
+					'object' => $this->templates,
+					'propName' => 'wrapper',
+				])
+			){
+				$result = \ddTools::parseText([
+					'text' => $this->templates->wrapper,
+					'data' => [
+						'ddGetDocuments_items' => $result,
+						'total' => count($data->provider->items),
+						'totalFound' => $data->provider->totalFound,
+					],
+				]);
+			}
+		}
+
+		return $result;
 	}
 }

src/Snippet.php

@@ -3,7 +3,7 @@
 
 class Snippet extends \DDTools\Snippet {
 	protected
-		$version = '1.7.0',
+		$version = '1.8.0',
 
 		$renamedParamsCompliance = [
 			'outputter' => 'outputFormat',