Download the PHP package dd/evolutioncms-snippets-ddrunsnippets without Composer

(MODX)EvolutionCMS.snippets.ddRunSnippets

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

• 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:

• 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

Use alias in snippet names

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.

Using results of previous snippets in object-values of parameters

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:

Then execute some snippets via ddRunSnippets:

Run the snippet through \DDTools\Snippet::runSnippet without DB and eval

Links

• Home page
• Telegram chat
• Packagist
• GitHub