Final Argument to getOption()

MODX logoIn an earlier article, I wrote about some of the finer points of the $modx->getOption() method. It occurred to me that I could do a better job of explaining how
the final (optional) argument works and clear up some possible areas of confusion with a little code.

A Brief Review

All MODX snippets receive any properties sent in the snippet tag or that exist as properties in the default properties or in an attached property set. The properties come to the snippet as a single merged array in the $scriptProperties variable.

You can get the properties directly from the array, but if you reference one that’s not there, PHP can throw an E_NOTICE error, and you usually want to set up a default value. It’s safer and simpler to use $modx->getOption() to get the values.

The first argument to getOption is the property key you want, the second is the array to search, the third is the default value to use if the property is not set, and the fourth we’ll get to in a bit.

Consider this snippet tag:

[code language=”html”]
&test = “
&zero = `0`
&zeroQ = `’0’`

Notice that the final property, zeroQ, is a zero inside quotation marks.

In the snippet, the properties above will arrive in this form:

[code language=”php”]
$scriptProperties = array(
’email’ => ‘’,
‘test’ => ”,
‘zero’ => 0,
‘zeroQ’ => ‘0’,

The fourth argument to getOption() can be true or false. The default value is false, so that’s what the argument will be if you leave it out. If the fourth argument is true, it tells getOption to use the default value if the value is an empty string. This will be clearer when you look at the results of our test snippet.

Test Snippet

We could use an actual snippet tag that calls a snippet to test this, but since we know what the $scriptProperties array will look like, we can put it right in the snippet. We’ll test each of the four properties listed above, with and without the fourth argument to getOption(), plus a fifth property that doesn’t exist. We’ll set a default value of ‘xxx’ each time so we can see when it’s used.


The Code

[code language=”php”]
$scriptProperties = array(
’email’ => ‘’,
‘test’ => ”,
‘zero’ => 0,
‘zeroQ’ => ‘0’,

$val = $modx->getOption(’email’, $scriptProperties, ‘xxx’);
$output .= "<br/>1. email: " . $val;

$val = $modx->getOption(’email’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>2. email + true: " . $val;

$val = $modx->getOption(‘test’, $scriptProperties, ‘xxx’);
$output .= "<br/>3. test: " . $val;

$val = $modx->getOption(‘test’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>4. test + true: " . $val;

$val = $modx->getOption(‘zero’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>5. zero: " . $val;

$val = $modx->getOption(‘zero’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>6. zero + true: " . $val;

$val = $modx->getOption(‘zeroQ’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>7. zeroQ: " . $val;

$val = $modx->getOption(‘zeroQ’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>8. zeroQ + true: " . $val;

$val = $modx->getOption(‘notThere’, $scriptProperties, ‘xxx’);
$output .= "<br/>9. notThere: " . $val;

$val = $modx->getOption(‘notThere’, $scriptProperties, ‘xxx’, true);
$output .= "<br/>10. notThere + true: " . $val;

return $output;



The Results

[code language=”html”]
1. email:
2. email + true:
3. test:
4. test + true: xxx
5. zero: 0
6. zero + true: 0
7. zeroQ: 0
8. zeroQ + true: 0
9. notThere: xxx
10. notThere + true: xxx


What’s Happening

If the fourth argument to getOption() is true, it will use the default value from the third argument if the property is an empty string.

In our test output, you’ll notice that the fourth argument only has an effect in one condition: test number 4. If you look at the getOption() code, you’ll see that the fourth argument is referred to as skip_empty. This is somewhat misleading. The values in tests 5 through 8 are empty, but the argument has no effect. That’s because it *only* acts when the value is an empty *string*. If it’s a number, even a number in quotes, getOption() does not consider it empty (even though PHP does).

You can send an empty string as the property (so that the default value will be used) by setting the fourth argument to true, and then leaving the value in the default properties or an attached property set blank, or by using the following in the snippet tag:

[code language=”html”]

Note that neither of the two lines below will work, since they result in a string containing the quote marks and won’t be considered empty:

[code language=”html”]


What About Default Properties?

If a property exists in the snippet’s default properties, but has a blank value, it will arrive in the $scriptProperties array as an empty string (even if the property is an integer type rather than a textfield). That means the fourth argument will determine whether getOption() gives it the default value or not. If the fourth argument is false or omitted, getOption() will return the empty string. If the fourth argument is true, getOption() will return the default value from the third argument.


Why Do We Care?

It’s important to understand these concepts if users of your snippet may modify or delete the values of the properties. Without the fourth argument being true, getOption() will *never* use your default value if the property exists in the snippet tag, in the default properties, or in an attached property set, even if any or all of them are empty.


Summing Up

Remember that properties in the snippet tag will override everything else, and that properties in an attached property set will override any default properties.

Here’s a short summary of what you can expect from getOption() (assuming that you’ve set a default value in the third argument):

  1. If the property value is set to an integer (even 0) or a non-empty string, getOption() will return it as is.
  2. If the property is missing from the tag, the default properties, and any attached property sets, getOption() will return your default value.
  3. If the property is an empty string (or blank), and the fourth argument is false or omitted, getOption() will return the empty string, not the default value.
  4. If the property is an empty string (or blank), and the fourth argument is true, getOption() will return the default value.


For more information on how to use MODX to create a web site, see my web site Bob’s Guides, or
better yet, buy my book: MODX: The Official Guide.

Looking for quality MODX Web Hosting? Look no further than Arvixe Web Hosting!

Tags: , , , | Posted under MODX, MODX | RSS 2.0

Author Spotlight

Bob Ray

Bob Ray is the author of MODX: The Official Guide and over 30 MODX add-on components. He hosts Bob's Guides, a source of valuable information for MODX users, and has been very active in the MODX Forums with over 19,000 posts.

Leave a Reply

Your email address will not be published. Required fields are marked *