1 icon.inc icon($icon_name, array $options = array())

Return the markup for outputting an icon by a machine name.

This will first check if an icon is provided by the active theme (in the theme's "icons" directory). If so, that icon will be used. Next, the icon will be pulled from any module that provided the icon through hook_icon_info(). If the icon is not provided by a theme or module, a matching icon will be returned from the /core/misc/icons directory.

If the "immutable" option is set to TRUE, the selection order will be reversed, that is the original provider of an icon will return the icon rather than allowing any overriding by a theme or module.

@since 1.28.0 Function added.

Parameters

string $icon_name: The icon name such as "home", "info", etc. Do not include the file extension.

array $options: An array of options to pass to the icon. Keys include:

  • alt: An alternative text to be used for screen readers. If not specified the icon will be marked as decorative with aria-hidden="true". Note that in the case of SVG icons, this will rendered as a <title> attribute within the <svg> tag.
  • attributes: Any additional attributes to add to the icon, including classes (as an array), name, id, etc.
  • immutable: Boolean value if this icon is not allowed to be overridden by themes or modules. If an icon is provided by core, it cannot be overridden, but an icon can still be added.

Return value

string:

See also

https://docs.backdropcms.org/documentation/icon-api

File

core/includes/icon.inc, line 44
Provides the Backdrop API for placing icons.

Code

function icon($icon_name, array $options = array()) {
  // Populate default options.
  $options += array(
    'alt' => NULL,
    'attributes' => array(),
    'immutable' => FALSE,
  );

  $immutable = !empty($options['immutable']);
  $icon_path = icon_get_path($icon_name, $immutable);

  if ($icon_path) {
    unset($options['immutable']);
    return theme('icon', array(
      'name' => $icon_name,
      'path' => $icon_path,
      'alt' => $options['alt'],
      'attributes' => $options['attributes'],
    ));
  }

  return '<!-- ' . t('Icon @name not found.', array('@name' => $icon_name)) . ' -->';
}