Icon

Purpose

The Icon field in Ultimate Fields allows the selection of a font-based icon from Font Awesome, Dashicons or a custom set of yours.

Icon Sets

Default sets

Out of the box the Icon field supports:

• Font Awesome (font-awesome)
• Dashicons (dashicons)

In the interface you can check which set(s) you'd like to use.

In PHP you can use the add_set( $name ) method of the field to specify what icons to use. If you do not call the method, both default sets will be available.

Field::create( 'icon', 'item_icon' )
	->add_set( 'font-awesome' )

Even if you are using a custom font set (see below), you still need to use the add_set method.

Custom sets

You can define custom icon sets for the icon field.

Step 1: Use the add_set method with a unique keyword

Even a custom set must have a name. For those examples, let's use ultimate-icons:

Field::create( 'icon', 'my_icon' )->add_set( 'ultimate-icons' )

Step 2: Load the set

When the time to display the field comes, Ultimate Fields will attempt to load the icon set. You can use the following two filters to aid the process:

• uf.icon.$name" allows you to immediately provide the data for the icon set.
• uf.icon.$name.path allows you to return the absolute path to a JSON file, which contains a definition of the set in the same format.

Step 3: Format the set properly

The example below includes both the filter that you need, as well as a sample structure.

<?php
add_filter( 'uf.icon.ultimate-icons', 'my_theme_icon_set' );
function my_theme_icon_set() {
	return array(
		// This name will appear in in the popup tab
		'name'       => 'Ultimate Icons',

		// Optional: This stylesheet will be loaded in the admin
		'stylesheet' => get_stylesheet_directory_uri() . '/css/icons.css',

		// A version, used to load the latest CSS
		'version'    => '4.7.1',

		// A prefix, which will be used to determine which set is being used
		'prefix'     => 'dashicons',

		// The actual icons
		'groups'     => array(
			array(
				'groupName' => 'Admin Menu Icons',
				'icons'     => array( 'dashicons-menu', 'dashicons-filter' /* ,... */ )
			),
			// ...
	);
}

Output format

There are two options for the output format of the Icon field:

• CSS Class ("class"): Default. Outputs simply the CSS class of the icon.
• The full icon ("icon"): Generates a complete <span> HTML element, which has the proper CSS class applied.

In PHP you can use the set_output_format( $format ) method with the keyword above.

Field::create( 'icon', 'block_icon' )
	->set_output_format( 'icon' )

Usage

Using the_value function will return the format, which you selected above. Using get_value will return a full CSS class for the icon.

Here is an example on how to use the values of an icon field.

Ultimate Fields does not automatically load CSS in the front-end. No matter which icon set you choose, please make sure that the appropriate resources have been linked!

<!-- CSS class -->
<span class="icon <?php the_value( 'block_icon' ) ?>"></span>

<!-- Icon output -->
<span class="icon">
	<?php the_value( 'block_icon' ) ?>
</span>