dd / evolutioncms-snippets-ddrunsnippets
Snippet runs necessary snippets with necessary params.
Installs: 2
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Type:modxevo-snippet
Requires
- php: >=7.4.0
- dd/evolutioncms-libraries-ddtools: >=0.63.0
README
Snippet runs necessary snippets with necessary params. Capabilities:
- Run a few snippets consequentially.
- Snippets results can be sent into parameters names and/or into other snippets values (can repeat this as much as you like).
- Any executed snippet can return either a string or a native PHP array. It is convenient to use with “nested” placeholders (see examples below).
- The snippet result can be returned into the chunk
outputterParams->tpl
, have transferring additional data through the parameteroutputterParams->placeholders
.
See the documentation for a more complete picture.
☝ Please note that snippets are run through \DDTools\Snippet::runSnippet
.
This increases performance and saves server resources, but unfortunately you can't run snippets that do not use \DDTools\Snippet
.
Please give us feedback via Telegram chat if this is critical.
Requires
- PHP >= 7.4
- (MODX)EvolutionCMS.libraries.ddTools >= 0.63
Installation
Using (MODX)EvolutionCMS.libraries.ddInstaller
Just run the following PHP code in your sources or Console:
//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', ]);
- If
ddRunSnippets
is not exist on your site,ddInstaller
will just install it. - If
ddRunSnippets
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
- Snippet name:
ddRunSnippets
. - Description:
<b>4.2.1</b> Snippet runs necessary snippets with necessary params.
. - Category:
Core
. - Parse DocBlock:
no
. - Snippet code (php): Insert content of the
ddRunSnippets_snippet.php
file from the archive.
2. Elements → Manage Files
- Create a new folder
assets/snippets/ddRunSnippets/
. - Extract the archive to the folder (except
ddRunSnippets_snippet.php
).
3. Install (MODX)EvolutionCMS.plugins.ddRunSnippets
The plugin is required if you want to use the snippets->{$snippetName}->runParams->cache
parameters.
Parameters description
Snippets execution parameters
-
snippets
- Description: List of snippets to be run. Snippets are called in accordance with the specified order.
- Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormatted
— as Query string- It can also be set as a native PHP object or array (e. g. for calls through
\DDTools\Snippet::runSnippet
):arrayAssociative
object
- Required
-
snippets->{$snippetName}
- Description: A snippet, when the key is the snippet name and the value is the snippet parameters.
- By default a snippet result will be equal to
[+snippetName+]
in parameters and chunk (wheresnippetName
is the snippet name). - But also you can set custom snippet aliases in this parameter using the
'='
delimiter (e. g.ddGetDocuments=docs
). - Every snippet can return either a string or a native PHP array (it is convenient to use with “nested” placeholders, see examples below).
- By default a snippet result will be equal to
- Valid values:
object
— an object with snippet parameters (see below)boolean
— for simple snippet calls without parameters or if you need to use default parameters, you can just passtrue
- Required
- Description: A snippet, when the key is the snippet name and the value is the snippet parameters.
-
snippets->{$snippetName}->{$paramName}
- Description: A snippet parameter, when the key is the parameter name and the value is the parameter value.
- Use
[+snippetName+]
for substitution by any previous snippet execution result in the parameter name or value (wheresnippetName
is the snippet name). - Or use
[+snippetAlias+]
if specified (e. g.docs
if the snippet name set asddGetDocuments=docs
).
- Use
- Valid values:
mixed
— as opposed to standard CMS calling you can pass not only string parameters to the snippet, any types are supported
- Default value: —
- Description: A snippet parameter, when the key is the parameter name and the value is the parameter value.
-
snippets->{$snippetName}->runParams
- Description: Additional parameters of snippet running.
- Valid values:
object
- Default value: —
-
snippets->{$snippetName}->runParams->parseResultCompletely
- Description: Completely parse result of the snippet by CMS parser.
- Valid values:
boolean
- Default value: — (depends on
snippets_parseEachResultCompletely
)
-
snippets->{$snippetName}->runParams->cache
- Description: You can cache snippet result to a specific file.
- Valid values:
object
- Default value: —
-
snippets->{$snippetName}->runParams->cache->resourceId
- Description: Resource ID (e. g. document) related to cache.
It means that the cache file will be destroyed when the document will be updated or deleted. - Valid values:
string
- Required
- Description: Resource ID (e. g. document) related to cache.
-
snippets->{$snippetName}->runParams->cache->suffix
- Description: Unique cache name for the document.
- Valid values:
string
- Required
-
snippets->{$snippetName}->runParams->cache->prefix
- Description: Cache file prefix. Useful if you want to cache some custom data that is not related to any documents.
- Valid values:
string
- Default value:
'doc'
-
snippets_parseEachResultCompletely
- Description: Parse result of each snippet by CMS parser.
Immediately after running each snippet, its result will be parsed by$modx->parseDocumentSource()
. - Valid values:
boolean
- Default value:
false
- Description: Parse result of each snippet by CMS parser.
Output parameters
-
outputterParams
- Description: Parameters to be passed to the specified outputter.
- Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormatted
— as Query string- It can also be set as native PHP object or array (e. g. for calls through
\DDTools\Snippet::runSnippet
or$modx->runSnippet
):arrayAssociative
object
- Default value: —
-
outputterParams->tpl
- Description: Chunk for output results.
Available placeholders:[+
snippetName+]
— a snippet result (wheresnippetName
is a snippet name)[+ddRunSnippetsResult.all+]
— results of all executed snippets combined by''
[+
any placeholders from theoutputterParams->placeholders
parameter+]
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
''
— all snippets will be executed but nothing will be returned
- Default value:
''
- Description: Chunk for output results.
-
outputterParams->placeholders
- Description:
Additional data has to be passed into
outputterParams->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:
object
- Default value: —
- Description:
Additional data has to be passed into
Examples
All examples are written using HJSON, but if you want you can use vanilla JSON instead.
Basic example
[[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+]"
}`
]]
Use alias in snippet names
[[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+]"
}`
]]
We called snippet someSnippet
twice with different parameters using two different aliases for each call: snippet1
and snippet2
.
Pass objects and arrays as snippet params
As opposed to standard CMS calling you can pass not only string parameters to a snippet, any types are supported.
[[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
]
}
}`
]]
Using results of previous snippets in object-values of parameters
[[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.
}
}
}
}`
]]
Native PHP arrays as results of snippets and “nested” placeholders
Let the example snippet named personData
that returs a native PHP array instead of usual string:
//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', ], ];
Then execute some snippets via 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+]"
}
}`
]]
Run the snippet through \DDTools\Snippet::runSnippet
without DB and eval
//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+]', ], ], ]);