Tag Parameters - NBBC: The New BBCode Parser

VI. Appendices

H. Tag Parameters

In versions 1.0 through 1.3 of NBBC, the tag parameters provided to the callback function were fairly simple and straightforward. There were the parameters provided by the user, and these three parameters were provided by NBBC itself:

_name: The name of the tag, like "url" or "color".
_default: The default value of the tag; in [font=Arial size=5] the default value would be "Arial".
_end: A boolean value that is false if the tag is a start tag and true if the tag is an end tag (note that this will always be false for a callback function, so it's not very useful outside of NBBC's internals).

However, in v1.4 and later of NBBC, the tag parameters have been expanded to include the following additional parameters:

_tag: The raw verbatim text of the tag, unparsed. For example, in [font=Arial size=5]...[/font], this will contain "[font=Arial size=5]".
_endtag: The raw verbatim text of the closing tag, unparsed. For example, in [font=Arial size=5]...[/font], this will contain "[/font]". Note that if an end tag is optional, or it's required but the user forgets to provide it, this value will still contain appropriate closing-tag text (i.e., the parser will create a suitable end tag).
_hasend: If a closing tag was provided by the user, this will be set to true; if no closing tag was provided, or this tag didn't allow a closing tag, this will be set to false. You can use this field to distinguish whether the user has provided a closing tag or not when closing tags are optional.
_params: The exact parameters of the tag, parsed, in list form. For example, in [font=Arial size=5], this parameter will contain this array:
```
Array(
    Array("key" => "font", "value" => "Arial"),
    Array("key" => "size", "value" => "5")
)
```
While this may appear to be identical to the array that contains it, it's not. First, the 0th array element is always set to the tag's default value (even if there is no default value), and second, if redundant parameters are provided, this will list them separately. For example:
```
[includes file="Larry" file="George" file="Bill"]
=> Array(
    Array("key" => "includes", "value" => ""),
    Array("key" => "file", "value" => "Larry"),
    Array("key" => "file", "value" => "George"),
    Array("key" => "file", "value" => "Bill")
)
```

In addition, in v1.4, the rule was established that no user-provided parameter may have a name that starts with an underscore (_); names that start with underscores are reserved for use by NBBC itself.

Some of these values are debatably useful; for example, the _end parameter is primarily used by NBBC to ensure proper tag parsing and doesn't help a callback rule much. But others, such as the new _params parameter, provide significant power to callback rules that they never had before.

In particular, the _tag and _endtag parameters are now provided so that callbacks can do late validation of their data. For example, consider a callback for the tag [fruit]. This callback wants to allow [fruit]apple[/fruit] and [fruit]orange[/fruit] but not [fruit]green[/fruit]. The callback cannot use the validation stage of rule processing to answer this because it doesn't know what its contents will be until it has already said "yes". But with the _tag and _endtag parameters, the [fruit] tag can now "fake" correct behavior:

Notice how this callback, if given an invalid type of fruit, simply returns the original tag and its contents, unchanged. This pattern is used in several places in the Standard BBCode Library in NBBC v1.4, and can be very useful in your own rules as rell.

[ Previous: G. How the Parser Works ]