dd/evolutioncms-snippets-ddrunsnippets

There is no license information available for the latest version (4.2.1) of this package.

Snippet runs necessary snippets with necessary params.

4.2.1 2024-08-02 16:50 UTC

This package is auto-updated.

Last update: 2024-11-06 09:37:08 UTC


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 parameter outputterParams->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

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

  1. Snippet name: ddRunSnippets.
  2. Description: <b>4.2.1</b> Snippet runs necessary snippets with necessary params..
  3. Category: Core.
  4. Parse DocBlock: no.
  5. Snippet code (php): Insert content of the ddRunSnippets_snippet.php file from the archive.

2. Elements → Manage Files

  1. Create a new folder assets/snippets/ddRunSnippets/.
  2. 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 JSON
      • stringHjsonObject — as HJSON
      • stringQueryFormatted — 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 (where snippetName 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).
    • 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 pass true
    • Required
  • 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 (where snippetName is the snippet name).
      • Or use [+snippetAlias+] if specified (e. g. docs if the snippet name set as ddGetDocuments=docs).
    • 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: —
  • 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
  • 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

Output parameters

  • outputterParams

    • Description: Parameters to be passed to the specified outputter.
    • Valid values:
      • stringJsonObject — as JSON
      • stringHjsonObject — as HJSON
      • stringQueryFormatted — 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 (where snippetName is a snippet name)
      • [+ddRunSnippetsResult.all+] — results of all executed snippets combined by ''
      • [+any placeholders from the outputterParams->placeholders parameter+]
    • Valid values:
      • stringChunkName
      • string — use inline templates starting with @CODE:
      • '' — all snippets will be executed but nothing will be returned
    • Default value: ''
  • 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: —

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+]',
		],
	],
]);

Links