Skip to content

Latest commit

 

History

History
420 lines (319 loc) · 7.4 KB

README.md

File metadata and controls

420 lines (319 loc) · 7.4 KB

(MODX)EvolutionCMS.snippets.ddStash

Save data as JSON or Query string, then extend if needed and use it later without database queries.

Requires

Documentation

Installation

Manually

1. Elements → Snippets: Create a new snippet with the following data
  1. Snippet name: ddStash.
  2. Description: <b>1.3</b> Save data as JSON or QueryString, then extend if needed and use it later without database queries..
  3. Category: Core.
  4. Parse DocBlock: no.
  5. Snippet code (php): Insert content of the ddStash_snippet.php file from the archive.
2. Elements → Manage Files
  1. Create a new folder assets/snippets/ddStash/.
  2. Extract the archive to the folder (except ddStash_snippet.php).

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.ddStash
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddStash',
	'type' => 'snippet'
]);
  • If ddStash is not exist on your site, ddInstaller will just install it.
  • If ddStash is already exist on your site, ddInstaller will check it version and update it if needed.

Parameters description

  • save

    • Desctription: Data to save in stash. Nested objects are supported too, see examples below.
    • Valid values:
      • stringJsonObject — as JSON
      • stringHjsonObject — as HJSON
      • stringQueryFormated — as Query string
      • It can also be set as a native PHP object or array (e. g. for calls through $modx->runSnippet):
        • arrayAssociative
        • object
    • Default value: —

  • save_extendExisting

    • Desctription: Extend an existing object instead of overwriting it.
    • Valid values:
      • 0
      • 1
    • Default value: 0

  • save_extendExistingWithEmpty

    • Desctription: Overwrite fields with empty values (see examples below).
      The following values are considered to be empty:
      • "" — an empty string
      • [] — an empty array
      • {} — an empty object
      • null
    • Valid values:
      • 0
      • 1
    • Default value: 1

  • get

    • Desctription: Data key for getting from stash.
    • Valid values: string
    • Default value: —

  • get_tpl

    • Desctription: Output template.

      Available placeholders:

      • [+snippetResult+] — data from stash

    • Valid values:

      • stringChunkName
      • string — use inline templates starting with @CODE:

    • Default value: '@CODE:[+snippetResult+]'

  • storage

    • Desctription: Data storage.
    • Valid values:
      • 'post' — $_POST
      • 'session' — $_SESSION
    • Default value: 'post'

Examples

Save some data

[[ddStash?
	&save=`{
		"userData": {
			"firstName": "John",
			"lastName": "[[ddGetDocumentField?
				&docId=`1`
				&docField=`lastName`
			]]",
			"children": [
				{
					"firstName": "Alice"
				},
				{
					"firstName": "Robert"
				}
			]
		},
		"someData": "someValue"
	}`
]]

Get saved data

You can get field value in any depth
[[ddStash? &get=`someData`]]

Returns someValue.

[[ddStash? &get=`userData.firstName`]]

Returns John.

[[ddStash? &get=`userData.children.0.firstName`]]

Returns Alice.

Also you can get objects in JSON

If field value is object or array, it will be returned in JSON format.

Get first John child
[[ddStash? &get=`userData.children.0`]]

Returns:

{
	"firstName": "Alice"
}
Get all John children:
[[ddStash? &get=`userData.children`]]

Returns:

[
	{
		"firstName": "Alice"
	},
	{
		"firstName": "Robert"
	}
]
Get all data about John
[[ddStash? &get=`userData`]]

Returns:

{
	"firstName": "John",
	"lastName": "Doe",
	"children": [
		{
			"firstName": "Alice"
		},
		{
			"firstName": "Robert"
		}
	]
}

Save: Extend an existing object instead of overwriting it (&save_extendExisting=`1` )

First you save some object:

[[ddStash?
	&save=`{
		"userData": {
			"firstName": "Chuck",
			"lastName": "Doe",
			"children": [
				{
					"firstName": "Alice"
				},
				{
					"firstName": "Robert"
				}
			]
		}
	}`
]]

Then if you just save object with the same key (userData):

[[ddStash?
	&save=`{
		"userData": {
			"middleName": "Ray",
			"lastName": "Norris"
		}
	}`
]]

The snippet will overwrite previous saved object completely:

[[ddStash? &get=`userData`]]

Returns:

{
	"middleName": "Ray",
	"lastName": "Norris"
}

So, if you want to extend the first object just use the save_extendExisting parameter:

[[ddStash?
	&save=`{
		"userData": {
			"middleName": "Ray",
			"lastName": "Norris"
		}
	}`
	&save_extendExisting=`1`
]]

In this case the snippet will recursive extend the first object with the data from the second:

[[ddStash? &get=`userData`]]

Returns:

{
	"firstName": "Chuck",
	"middleName": "Ray",
	"lastName": "Norris",
	"children": [
		{
			"firstName": "Alice"
		},
		{
			"firstName": "Robert"
		}
	]
}

Save: Extend without overwriting fields with empty values (&save_extendExistingWithEmpty=`0` )

By default, empty field values (e. g. '') are treated as other values and will replace non-empty ones.

[[ddStash?
	&save=`{
		"userData": {
			"firstName": "John",
			"lastName": "Tesla",
			"discipline": "Electrical engineering"
		}
	}`
]]
[[ddStash?
	&save=`{
		"userData": {
			"firstName": "Nikola",
			"lastName": ""
		}
	}`
	&save_extendExisting=`1`
]]

Returns:

{
	"firstName": "Nikola",
	"lastName": "",
	"discipline": "Electrical engineering"
}

Empty lastName from the second object replaced non-empty lastName from the first.

If you want to ignore empty values, just use save_extendExistingWithEmpty == 0:

[[ddStash?
	&save=`{
		"userData": {
			"firstName": "John",
			"lastName": "Tesla",
			"discipline": "Electrical engineering"
		}
	}`
]]
[[ddStash?
	&save=`{
		"userData": {
			"firstName": "Nikola",
			"lastName": ""
		}
	}`
	&save_extendExisting=`1`
	&save_extendExistingWithEmpty=`0`
]]

Returns:

{
	"firstName": "Nikola",
	"lastName": "Tesla",
	"discipline": "Electrical engineering"
}

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.ddStash
\DDTools\Snippet::runSnippet([
	'name' => 'ddStash',
	'params' => [
		'get' => 'userData.firstName'
	]
]);

Links