Icons

Tiki 14 - Icon sets

Why?

The goal of having icon sets is to
- make it easy to change icons in Tiki
- keep icon usage in smarty tpl files simple
- move icon customization out of the smarty tpl files
- more focus in having a centralized, future proof way of handling icons in Tiki

How icons work from Tiki14

- Tiki remains to have one central function to manage icons, which is the existing icon smarty_tiki function (/lib/smarty_tiki/function.icon.php)
- To include an icon in a smarty tpl file is use the icon smarty_tiki function in the tpl files like this:

//WRONG
{icon name=save}
//RIGHT
{icon name="save"}

//WRONG
<input type="submit" class="btn btn-default btn-sm" name="zip" value="{icon name="file-archive-o"} {tr}Generate a zip of those directories{/tr}">

//RIGHT
<button type="submit" class="btn btn-primary btn-sm" name="zip">{icon name="file-archive-o"} {tr}Generate zip{/tr}</button>

//RIGHT
{icon name="trash" href="tiki-admin_system.php?do=all" class="btn btn-primary" title="{tr}Empty{/tr}"}

//RIGHT but not preferred
<a href="tiki-admin_system.php?do=all" class="btn btn-primary" title="{tr}Empty{/tr}">{icon name="trash"} {tr}Clear all cache{/tr}</a>

// Modern button with icon
<button type="button" class="btn btn-primary">
    {icon name="save"} Save Changes
</button>

// Icon with Bootstrap tooltip
{icon name="info-circle" data-bs-toggle="tooltip" title="{tr}Help{/tr}"}

// Icon button with confirmation
{icon name="trash" 
      class="btn btn-danger" 
      href="delete.php" 
      _confirm="Are you sure you want to delete this?"}

- Icons are referenced by a descriptive name in tpl-s (eg: "save", "delete", etc). Icon naming in the tpl files is focusing on functionality (eg: save, edit, delete, etc).
- Icons are part of an icon set. Icon sets are defined using a multidimensional array in a php file that provide settings and definitions for the icon files.
- Tiki ships with a default icon set (themes/base_files/iconsets/default.php), which is the fallback for all other icon sets. This file should not be modified for local customizations. The default iconset uses font-awesome fonts.

• See all defined names and the icons Default Iconset - Font Awesome

- Cascading iconset approach (similar to css): there is a base (default) icon set, other icon sets need to define only what should be different than the default icon set
- File name convention for icon sets: nothing special, it just have to be distinct than the existing ones in the themes/base_files/iconsets/ folder
- In the Look&Feel administration you can choose from the icon sets shipped with Tiki.
- If you want to contribute an icon set to Tiki, put it to the themes/base_files/iconsets/ folder with a distinct name eg: mybelovediconset.php, famfam.php etc.

Specification

return array(
		'name' => tr('Default (Font-awesome)'), // Mandatory, will be displayed as Icon set option in the Look&Feel admin UI
		'description' => tr('The default system icon set using Font-awesome fonts'), // TODO display as Icon set description in the Look&Feel admin UI
		'tag' => 'span', // The default html tag for the icons in the icon set.
		'prepend' => 'fa fa-',
		'append' => ' fa-fw',
		'icons' => array(
			/* This is the definition of an icon in the icon set if it's an "alias" to one of the default icons.
			 * The key must be unique, it is the "name" parameter at the icon function,
			 * so eg: {icon name="actions"}
			 * will find 'save' in the array and apply the specified configuration */

			'actions' => array( 
				'id' => 'play-circle',    // id to match the defaults defined below
			),
			'add' => array(
				'id' => 'plus-circle',
			),
          );
}

Samples

Glyphicons iconset

function iconset_glyphicons()
{
	return array(
		'name' => tr('Glyphicons'),
		'description' => tr('Glyphicon focused iconset, see http://getbootstrap.com/components/'),
		'tag' => 'span',
		'prepend' => 'glyphicon glyphicon-',
		'append' => '',
		'icons' => array(
			'actions' => array(
				'id' => 'play-circle',
			),
			'add' => array(
				'id' => 'plus-sign',
			),
                ),
		'defaults' => array(
			'adjust',
			'align-center',
        );
}

Legacy iconset (mainly famfamfam icons)

function iconset_legacy()
{
	return array(
		'name' => tr('Legacy (pre Tiki14) icons'),
		'description' => tr('Legacy (pre Tiki14) icons, mainly using famfamfam images'),
		'tag' => 'img',
		'prepend' => 'img/icons/',
		'append' => '.png',
		'icons' => array(
			'actions' => array(
				'id' => 'application_form',
			),
			'add' => array(
				'id' => 'large/icon-configuration',
			),
               'defaults' => '',
            );
}

Theme specific icon set

Customization