Custom Snippets - when to use $scriptProperties

Support
1

I’m currently dipping my toes into writing custom snippets, so I had a read on
https://docs.modx.com/3.x/en/extending-modx/snippets/good-snippet

I was wondering, when is it recommended/required to use getOption and when would it be enough to just use the passed values as variables by themselves?

For example right now I’m creating a simple percent calculation snippet, so I pass two values and a chunk as an output template:

[[mySnippet? &value1=`5` &value2=`10` &tpl=`myChunk`]]

Now in the snippet itself, would I use

$value1 = (int) $modx->getOption('value1', $scriptProperties);
$value2 = (int) $modx->getOption('value2', $scriptProperties);

$ouput = (1 - $value1 / $value2) * 100;

or simply start calculating with the variables which hold my passed value

$ouput = (1 - $value1 / $value2) * 100;

I’m guessing that $scriptProperties are only required to set default values in case they aren’t set through the tag, but maybe there’s more to it?

Thanks in advance for any clarifications!

2

Before your snippet code is executed, MODX uses the PHP extract function to create a variable for every value in the $scriptProperties array.

So $value1 and $scriptProperties['value1'] gives you the same value (if the property is set in the snippet call).

However, if the property isn’t defined in the snippet call, and you try to use $value1, it generates a PHP warning “Undefined variable” (or “Undefined array key” in case of $scriptProperties['value1'])

When you use the getOption function $value1 = $modx->getOption('value1', $scriptProperties); the variable $value1 is always defined (but maybe has a value of null).

If you want to pass all the properties to a different PHP class or function, it is easier to use the $scriptProperties array than to pass the variables individually.

Also, when you use $value1 directly, it can be unclear for someone reading your snippet code, where this variable was set.
$value1 = $modx->getOption('value1', $scriptProperties); on the other hand makes it quite clear, that the value was passed as a property.

1 Like
3

Using getOption() makes it easier to set a default value, which is often useful, and can make the code shorter. Also, getOption() has a final, optional, boolean argument (defaults to false), which if true, tells getOption() to use the default value if the $scriptProperties value is set, but empty (which often happens if the property is in the default properties of the snippet but not set). Sometimes that final argument will save you several lines of code.

Be careful not to set that final argument to true if the $scriptProperties value might have a valid value of 0, or an empty string, which would cause the default value to be used instead of the actual value.

In a long snippet with lots of properties, it’s common to do something like this at the top to save typing and avoid spelling errors:

$sp = $scriptProperties;

BTW, you can use getOption() on any array, including things like $_POST or your own array set in the snippet.

1 Like
4

Thank you @halftrainedharry and @bobray! As I suspected lots more to learn here.