VI. Appendices

[ Previous: A. Standard Smileys | Next: C. Content Classes ]

B. Rule Parameters

Tag rules are arrays that may contain any of the following members to describe how the tag is to be processed. Most members are optional, and default values will usually be assumed if no member is given.

• 'mode'         (Default value: BBCODE_MODE_SIMPLE)
  Must be exactly one of the following identifiers:
  
  
  • BBCODE_MODE_SIMPLE: Replaces the tag with the text defined in 'simple_start' and 'simple_end'.
  • BBCODE_MODE_CALLBACK: Calls a callback function or method to format the tag. The formatting function is specified in the 'method' parameter.
  • BBCODE_MODE_INTERNAL: Calls an internal formatting function in the BBCode parser. The formatting function is specified in the 'method' parameter, which must be a string.
  • BBCODE_MODE_LIBRARY: Calls a formatting function that's part of the Standard BBCode Library (the BBCodeLibrary object). The formatting function is specified in the 'method' parameter, which must be a string.
  
  
• 'allow_params'         (Default value: true)
  Sets flag on whether tag can accept parameters or not. Set to false on common tags such as [b], [u], [i], [s], [sup], and [sub].
  
  
• 'simple_start'         (Default value: "")
  This parameter stores a text string that, in BBCODE_MODE_SIMPLE, describes what HTML to use in place of the start tag.
  
  
• 'simple_end'         (Default value: "")
  This parameter stores a text string that, in BBCODE_MODE_SIMPLE, describes what HTML to use in place of the end tag. Note that if the rule's 'content' member is set to BBCODE_PROHIBIT, the 'simple_end' string will be concatenated to 'simple_start' and the two of them together will be used in place of the start tag (the start tag, effectively, behaves as both the start and end tags if content is prohibited).
  
  
• 'method'         (Default value: "")
  This member is used with BBCODE_MODE_CALLBACK, BBCODE_MODE_INTERNAL, and in BBCODE_MODE_LIBRARY to determine what function to call:
  
  
  • BBCODE_MODE_CALLBACK: This may be a string, for calling a function, or an array, for calling a method of a class. See PHP's documentation on call_user_func() for more details on how to define a callback function. See the section on callback tags for more details on how to set up a BBCODE_MODE_CALLBACK tag.
  • BBCODE_MODE_INTERNAL: This is a string, the name of an internal method of an instance of class BBCode.
  • BBCODE_MODE_LIBRARY: This is a string, the name of a method of an instance of class BBCodeLibrary.
  
  Note: Unlike most members, this member must be defined if BBCODE_MODE_CALLBACK, BBCODE_MODE_INTERNAL, or BBCODE_MODE_LIBRARY is used. If you fail to define this member, NBBC may produce error messages or warnings, and will definitely not format your content correctly!
  
  
• 'content'         (Default value: BBCODE_OPTIONAL)
  Must be exactly one of the following identifiers:
  
  
  • BBCODE_REQUIRED: Non-empty content must be provided for this tag to be properly converted. If empty content is provided by the user, this tag will be rendered verbatim rather than formatted.
  • BBCODE_OPTIONAL: (The most common setting.) Content is optional, and may be provided by the user between the start tag and the end tag.
  • BBCODE_PROHIBIT: Content is disallowed. Generally, this is used in conjunction with the 'end_tag' member (see below) when end tags are prohibited as well as content.
  • BBCODE_VERBATIM: Content is optional, but any tags or special formatting contained within it will be ignored: The content is treated as plain text, and is sent to the formatting function exactly as given. If this is used in conjunction with BBCODE_MODE_SIMPLE, the content will be passed through safety routines like htmlspecialchars(), so you can safely use this in combination with elements like <pre>, but not with elements like <xmp>. If this is used with a formatting function, the formatting function will be responsible for applying htmlspecialchars() or any other form of cleanup necessary: The formatting function will receive the exact text given by the user, whitespace included. This setting is generally intended to be combined with the white-space:pre CSS rule applied to the block that contains the verbatim content.
  
  
• 'before_tag'         (Default value: "")
• 'after_tag'         (Default value: "")
• 'before_endtag'         (Default value: "")
• 'after_endtag'         (Default value: "")
  These settings collectively control how (non-newline) whitespace and newlines are treated when placed in proximity to this tag or to its end tag. For each setting, you use a simple pattern comprised of the following characters to describe what to remove:
  
  
  • s         Remove any non-newline whitespace found.
  • n         Remove a single newline, if one exists.
  • a         Remove as many spaces and newlines as are found.
  
  For 'before' removal, the pattern is matched backward from the tag; for 'after' removal, the pattern is matched forward from the tag. The default is the empty string, which means no whitespace or newlines are to be removed.
  
  Common examples:
        's'           Remove all non-newline whitespace
        'sn'          Remove all non-newline whitespace, then a single newline if it exists.
        'ns'          Remove a single newline if it exists, then all non-newline whitespace.
        'sns'         Remove all non-newline whitespace, then a single newline if it exists,
                                then any non-newline whitespace found past that newline.
  
  
• 'end_tag'         (Default value: BBCODE_REQUIRED)
Must be exactly one of the following identifiers:


• BBCODE_REQUIRED: (The most common setting.) An ending [/tag] must be provided if the starting [tag] is used; if no end tag is given by the user, the start tag will be ignored and formatted verbatim.
• BBCODE_OPTIONAL: An end tag is optional, and the content of the start tag extends until the end of this node of the document tree, or to the end of the document, whichever comes first.
• BBCODE_PROHIBIT: An end tag is disallowed. The start tag has no content, and is formatted as an isolated tag. If an end tag is provided, it will be formatted verbatim. This is most useful for tags like [rule] and [wiki] that have no content.


• 'allow_in'         (Default value: array('block'))
This is an array that lists which other classes this tag may be placed inside. See the description of content classes below to understand how this is used.


• 'class'         (Default value: 'block')
This describes what content-class this tag belongs to. There is one special class, "block", which is used by the invisible "root tag" of the BBCode tree, but may be used for other tags as well. See the description of content classes below to understand how this is used.