README

片段运行必要的片段，并带有必要的参数。功能

• 连续运行几个片段。
• 片段结果可以发送到参数名称和/或到其他片段值（可以重复此操作，次数不限）。
• 任何已执行的片段都可以返回一个字符串或一个本机PHP数组。它方便与“嵌套”占位符一起使用（请参阅下面的示例）。
• 片段结果可以返回到块 outputterParams->tpl，并通过参数 outputterParams->placeholders 传递额外的数据。

请参阅文档以获取更完整的视图。

☝ 请注意，片段是通过 \DDTools\Snippet::runSnippet 运行的。这提高了性能并节省了服务器资源，但不幸的是，您不能运行不使用 \DDTools\Snippet 的片段。如果您认为这很重要，请通过 Telegram聊天 给我们反馈。

需求

• PHP >= 7.4
• (MODX)EvolutionCMS.libraries.ddTools >= 0.63

安装

使用 (MODX)EvolutionCMS.libraries.ddInstaller

只需在您的源文件中运行以下PHP代码，或在 控制台 中运行

//Include (MODX)EvolutionCMS.libraries.ddInstaller
require_once(
	$modx->getConfig('base_path')
	. 'assets/libs/ddInstaller/require.php'
);

//Install (MODX)EvolutionCMS.snippets.ddRunSnippets
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddRunSnippets',
	'type' => 'snippet',
]);

//Install (MODX)EvolutionCMS.plugins.ddRunSnippets (it is required if you want to use the `snippets->{$snippetName}->runParams->cache` parameters)
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.plugins.ddRunSnippets',
	'type' => 'plugin',
]);

• 如果您的网站上不存在 ddRunSnippets，则 ddInstaller 将仅安装它。
• 如果您的网站上已存在 ddRunSnippets，则 ddInstaller 将检查其版本并在需要时更新它。

手动

1. 元素 → 片段：创建一个新片段，如下所示

1. 片段名称：ddRunSnippets。
2. 描述：<b>4.2.1</b> 片段运行必要的片段，并带有必要的参数。。
3. 分类：核心。
4. 解析DocBlock：否。
5. 片段代码（PHP）：插入存档中 ddRunSnippets_snippet.php 文件的内容。

2. 元素 → 管理文件

1. 创建一个名为 assets/snippets/ddRunSnippets/ 的新文件夹。
2. 将存档解压到该文件夹中（除了 ddRunSnippets_snippet.php）。

3. 安装 (MODX)EvolutionCMS.plugins.ddRunSnippets

如果您想使用 snippets->{$snippetName}->runParams->cache 参数，则需要此插件。

参数描述

片段执行参数

• snippets

  • 描述：要运行的片段列表。片段将按照指定的顺序调用。
  • 有效值
    • stringJsonObject — 作为 JSON
    • stringHjsonObject — 作为 HJSON
    • stringQueryFormatted — 作为 查询字符串
    • 它也可以设置为本地PHP对象或数组（例如，通过 \DDTools\Snippet::runSnippet 调用）
      • arrayAssociative
      • object
  • 必需

• snippets->{$snippetName}

  • 描述：一个片段，当键是片段名称时，值是片段参数。
    • 默认情况下，片段结果将等于参数和块中的 [+snippetName+]（其中 snippetName 是片段名称）。
    • 但您也可以使用此参数设置自定义片段别名，使用 '=' 分隔符（例如 ddGetDocuments=docs）。
    • 每个代码片段可以返回字符串或原生PHP数组（方便与“嵌套”占位符一起使用，请参见下面的示例）。
  • 有效值
    • object — 包含代码片段参数的对象（请参见下面）
    • boolean — 对于不带参数或需要使用默认参数的简单代码片段调用，只需传递 true
  • 必需

• snippets->{$snippetName}->{$paramName}

  • 描述：代码片段参数，其中键是参数名称，值是参数值。
    • 使用 [+snippetName+] 通过任何先前代码片段执行结果替换参数名称或值（其中 snippetName 是代码片段名称）。
    • 或使用指定 [+snippetAlias+]（例如，如果代码片段名称设置为 ddGetDocuments=docs，则 docs）。
  • 有效值
    • mixed — 与标准CMS调用相比，您不仅可以传递字符串参数到代码片段，任何类型都受支持
  • 默认值：—

• snippets->{$snippetName}->runParams

  • 描述：代码片段运行的附加参数。
  • 有效值：object
  • 默认值：—

• snippets->{$snippetName}->runParams->parseResultCompletely

  • 描述：通过CMS解析器完全解析代码片段的结果。
  • 有效值：boolean
  • 默认值：—（取决于 snippets_parseEachResultCompletely）

• snippets->{$snippetName}->runParams->cache

  • 描述：您可以将代码片段结果缓存在特定文件中。
  • 有效值：object
  • 默认值：—

• snippets->{$snippetName}->runParams->cache->resourceId

  • 描述：与缓存相关的资源ID（例如文档）。
    这意味着在更新或删除文档时，缓存文件将被销毁。
  • 有效值：string
  • 必需

• snippets->{$snippetName}->runParams->cache->suffix

  • 描述：文档的唯一缓存名称。
  • 有效值：string
  • 必需

• snippets->{$snippetName}->runParams->cache->prefix

  • 描述：缓存文件前缀。如果您想缓存一些与任何文档无关的定制数据，则很有用。
  • 有效值：string
  • 默认值：'doc'

• snippets_parseEachResultCompletely

  • 描述：通过CMS解析器解析每个代码片段的结果。
    在运行每个代码片段后立即，其结果将通过 $modx->parseDocumentSource() 进行解析。
  • 有效值：boolean
  • 默认值：false

输出参数

• outputterParams

  • 描述：传递给指定输出器的参数。
  • 有效值
    • stringJsonObject — 作为 JSON
    • stringHjsonObject — 作为 HJSON
    • stringQueryFormatted — 作为 查询字符串
    • 它也可以设置为原生PHP对象或数组（例如，通过 \DDTools\Snippet::runSnippet 或 $modx->runSnippet 调用）
      • arrayAssociative
      • object
  • 默认值：—

• outputterParams->tpl

  • 描述：用于输出结果的块。
    可用占位符
    • [+snippetName+] — 代码片段结果（其中 snippetName 是代码片段名称）
    • [+ddRunSnippetsResult.all+] — 所有已执行代码片段的组合结果（通过 ''）
    • [+outputterParams->placeholders 参数中的任何占位符+]
  • 有效值
    • stringChunkName
    • string — 使用以 @CODE: 开头的内联模板
    • '' — 将执行所有代码片段但不会返回任何内容
  • 默认值：''

• outputterParams->placeholders

  • 描述：需要传递到 outputterParams->tpl 的附加数据。
    支持嵌套对象和数组
    • {"someOne": "1", "someTwo": "test" } => [+someOne+], [+someTwo+].
    • {"some": {"a": "one", "b": "two"} } => [+some.a+], [+some.b+].
    • {"some": ["one", "two"] } => [+some.0+], [+some.1+].
  • 有效值：object
  • 默认值：—

示例

所有示例均使用 HJSON 编写，但您也可以使用纯JSON。

基本示例

[[ddRunSnippets?
	&snippets=`{
		someSnippet: {
			exampleParam: Example value.
		}
		
		otherSnippet: {
			someParam: "[+someSnippet+]"
		}
		
		anotherSnippet: {
			//Results of previous snippets can be used both in parameters names and their values
			"[+otherSnippet+]": "[+someSnippet+]"
		}
	}`
	&outputterParams=`{
		tpl: "@CODE:[+anotherSnippet+]"
	}`
]]

在代码片段名称中使用别名

[[ddRunSnippets?
	&snippets=`{
		//Run “someSnippet” and save it's result as “snippet1”
		someSnippet=snippet1: {
			exampleParam: First example value.
		}
		
		//Run “someSnippet” and save it's result as “snippet2”
		someSnippet=snippet2: {
			exampleParam: Second example value.
			//Placeholder “[+snippet1+]” will be replaced to results of previous “someSnippet” call
			exampleParam2: "[+snippet1+]"
		}
		
		anotherSnippet: {
			someParam: "[+snippet2+]"
			"[+snippet1+]": "[+snippet2+]"
		}
	}`
	&outputterParams=`{
		tpl: "@CODE:[+anotherSnippet+]"
	}`
]]

我们使用两个不同的别名分别对 someSnippet 进行了两次调用，并且两次调用的参数不同：snippet1 和 snippet2。

将对象和数组作为代码片段参数传递

与标准CMS调用不同，您不仅可以传递字符串参数到代码片段，任何类型都受支持。

[[ddRunSnippets?
	&snippets=`{
		someSnippet: {
			//Object as parameter value
			exampleParam1: {
				objectField: “exampleParam1” is an object, not a string.
				otherField: true
			}
			
			//Array as parameter value
			exampleParam2: [
				“exampleParam2” is an array, not a string
				2.71
			]
		}
	}`
]]

在参数的对象值中使用先前代码片段的结果

[[ddRunSnippets?
	&snippets=`{
		someSnippet: {
			exampleParam: Example value.
		}
		
		otherSnippet: {
			exampleParam1: {
				objectField: “exampleParam1” is an object, not a string.
				otherField: So, “someSnippet” result will be replace the [+someSnippet+] placeholder here.
				anotherField: {
					deepField: Snipepts results placeholders will work fine independent of object depth.
					otherDeepField: The palceholder [+someSnippet+] works here too.
				}
			}
		}
	}`
]]

片段和“嵌套”占位符的结果为原生PHP数组

以下是一个名为 personData 的示例片段，它返回原生PHP数组而不是通常的字符串

//Just for example let the snippet do nothing but only return an array :)
return [
	'name' => 'Tamara Eidelman',
	'birthdate' => '1959.12.15',
	'links' => [
		'youtube' => 'https://youtube.com/c/TamaraEidelmanHistory',
		'site' => 'https://eidelman.ru',
	],
];

然后通过 ddRunSnippets 执行一些片段

[[ddRunSnippets?
	&snippets=`{
		//Run our example snippet that returns a native PHP array (without parameters in this example case)
		personData: true
		
		//Run other snippet
		someSnippet: {
			//If we need to pass whole result of the first snippet, just use usual placeholder
			//ddRunSnippet will convert the native PHP array to JSON in this case
			personData: "[+personData+]"
		}
		
		//Run another snippet
		anotherSnippet: {
			//Also we can use “nested” placeholders to get an item of the snippet result array
			info: "[+personData.name+], [+personData.birthdate+]"
			//And it works with depth
			youtube: "[+personData.links.youtube+]"
		}
	}`
]]

在不使用数据库和 eval 的情况下通过 \DDTools\Snippet::runSnippet 运行片段

//Include (MODX)EvolutionCMS.libraries.ddTools
require_once(
	$modx->getConfig('base_path')
	. 'assets/libs/ddTools/modx.ddtools.class.php'
);

//Run (MODX)EvolutionCMS.snippets.ddRunSnippets
\DDTools\Snippet::runSnippet([
	'name' => 'ddRunSnippets',
	'params' => [
		'snippets' => [
			'someSnippet' => [
				'exampleParam' => 'Example value.',
			],
			'otherSnippet' => [
				'someParam' => '[+someSnippet+]',
			],
			'anotherSnippet' => [
				'[+otherSnippet+]' => '[+someSnippet+]',
			],
		],
		'outputterParams' => [
			'tpl' => '@CODE:[+anotherSnippet+]',
		],
	],
]);

链接

• 主页
• Telegram 聊天
• Packagist
• GitHub