1 filter.api.php callback_filter_allowed_html($filter, $format)

Returns HTML allowed by this filter's configuration.

This callback function is only necessary for filters that strip away HTML tags (and possibly attributes) and allows other modules to gain insight in a generic manner into which HTML tags and attributes are allowed by a format.

Note that providing this callback does not mean that Backdrop will strip out these tags for you. This still must be done using callback_filter_prepare() and callback_filter_process(). This callback is used to collect the end-result list of tags and attributes so that it may be passed to front-end editors such as CKEditor.

Parameters

$filter: The filter object containing settings for the given format.

$format: The full text format object.

Return value

array: A nested array with the following keys:

  • 'allowed': (optional) the allowed tags as keys, and for each of those tags (keys) either of the following values:

    • TRUE to indicate any attribute is allowed.
    • FALSE to indicate no attributes are allowed.
    • an array to convey attribute restrictions: the keys must be attribute names (which may use a wildcard, e.g. "data-*"), the possible values are similar to the above:

      • TRUE to indicate any attribute value is allowed.
      • FALSE to indicate the attribute is forbidden.
      • an array to convey attribute value restrictions: the key must be attribute values (which may use a wildcard, e.g. "xsd:*"), the possible values are TRUE or FALSE: to mark the attribute value as allowed or forbidden, respectively.
  • 'forbidden': (optional) the forbidden tags.

There is one special case: the "wildcard tag", "*": any attribute restrictions on that pseudo-tag apply to all tags.

Here is an extensive example, for a very granular filter:

  array(
    'allowed' => array(
      // Allows any attribute with any value on the <div> tag.
      'div' => TRUE,
      // Allows no attributes on the <p> tag.
      'p' => FALSE,
      // Allows the following attributes on the <a> tag:
      //  - 'href', with any value;
      //  - 'rel', with the value 'nofollow' value.
      'a' => array(
        'href' => TRUE,
        'rel' => array('nofollow' => TRUE),
      ),
      // Only allows the 'src' and 'alt' attributes on the <alt> tag,
      // with any value.
      'img' => array(
        'src' => TRUE,
        'alt' => TRUE,
      ),
      // Allow RDFa on <span> tags, using only the dc, foaf, xsd and sioc
      // vocabularies/namespaces.
      'span' => array(
        'property' => array('dc:*' => TRUE, 'foaf:*' => TRUE),
        'datatype' => array('xsd:*' => TRUE),
        'rel' => array('sioc:*' => TRUE),
      ),
      // Forbid the 'style' and 'on*' ('onClick' etc.) attributes on any
      // tag.
      '*' => array(
        'style' => FALSE,
        'on*' => FALSE,
      ),
    )
  )
  

A simpler example disallowing a few tags:

  array(
    'forbidden' => array('iframe', 'script')
  )
  

A filter that doesn't allow any HTML at all.

  array(
    'allowed' => array()
  )
  

And for a filter that applies no restrictions, i.e. allows any HTML:

  FALSE
  

See also

filter_format_allowed_html()

File

core/modules/filter/filter.api.php, line 413
Hooks provided by the Filter module.

Code

function callback_filter_allowed_html($filter, $format) {
  // This example is pulled from "filter_html" filter provided by core.
  $restrictions = array('allowed' => array());
  $tags = preg_split('/\s+|<|>/', $filter->settings['allowed_html'], -1, PREG_SPLIT_NO_EMPTY);
  // List the allowed HTML tags.
  foreach ($tags as $tag) {
    $restrictions['allowed'][$tag] = TRUE;
  }
  // The 'style' and 'on*' ('onClick' etc.) attributes are always forbidden.
  $restrictions['allowed']['*'] = array('style' => FALSE, 'on*' => FALSE);
  return $restrictions;
}