Iconize WordPress Plugin - Documentation

by: THATplugin

Thank you for using our plugin. If you have any questions that are beyond the scope of this help file, please feel free to ask on support forum. Thanks so much!

If you have previously Premium version of Iconize plugin installed (1.1.x), please download and activate Legacy Font Pack Plugin so that you don't lose icons from fonts that are removed in new version (1.2.x) - only Font Awesome and Dashicons from old version are available in new version as well. Please note that old fonts won't work with some new features so we advise you to replace old icons with icons from new fonts.

To install this plugin you must have a working version of WordPress already installed. For informations about installing the WordPress platform, please visit the WordPress Codex - http://codex.wordpress.org/Installing_WordPress.

For informations about installing plugins please visit this WordPress Codex page - https://wordpress.org/support/article/managing-plugins/#installing-plugins.

Plugin Settings

After installing and activating Iconize WordPress Plugin you can access the settings page by:

  1. Clicking the "Settings" link under "Iconize" in Plugins page.



  2. Navigating to the Settings > Iconize from the left menu.

The Iconize Settings page contains only options to enable or disable Fonts and enable or disable Iconize plugin components. There are four components available:

  1. Editor component - for inserting and editing icons to posts and pages.
  2. Custom menus component - for inserting and editing menu item icons.
  3. Widgets component - for inserting and editing widget title icons.
  4. Taxonomy component - for inserting and editing taxonomy terms icons ( categories, tags, custom taxonomies ).

All options are enabled by default.

Dialog Usage

The main feature of Iconize plugin is the ability to visually add and edit icons using a set of options shown in modal dialog.



Selecting icon

You can search for and select icons in two ways:

1. Manually
Use the Change set dropdown and click on desired icon to select it. You'll notice that the name of selected icon will appear on Search by name input.



2. Using Search by name input
To search for icon, you'll have to click on Search by name input and start typing. The dropdown with all possible matches will appear, and the list will update itself while you're typing. To select icon just click on one from the list.



Configuring icon

If you want to customize selected icon you can use:

  1. Color options - Color picker to set icon color and checkbox to apply parent color inheritance on icon hover
  2. Select dropdowns to assign predefined effect, size and align CSS classes to icon
  3. Custom classes input to assign your own classes to icon
Custom classes

To enter custom classes, click on input and type your CSS class names. Separate classes by hitting space, comma or enter on your keyboard.

Note that you will not be able to type duplicates, invalid CSS class names, or class names that are already in use by Iconize plugin.



After installing the plugin, head over to post visual editor and you will notice four new buttons below default set of buttons. Those buttons are added by Iconize plugin and with them you can insert icons, edit selected icons, create icon stacks, edit icon stacks and remove icons.


If you switch to text editor mode you will notice "icon" button placed between "more" and "close tags" buttons. With this button you can only insert icon.

Inserting icon

To insert icon, put the cursor on desired place in editor content and click the editor button for inserting/editing icon ( see the images below ). The dialog will appear. After selecting and configuring icon inside the dialog, click on button and that's it. In visual editor mode, you will see the resulting icon directly in editors content, in text mode, you will see that the HTML code for icon is inserted. No shortcodes or image placeholders. Nice.

Step 1 ( visual mode ):



Step 1 ( text mode ):



Step 2:



Result ( visual mode ):



Result ( text mode ):



Editing icon ( visual editor only )

To edit previusly inserted icon, select icon you wish to edit by clicking on it and the button for inserting/editing icon will be activated, click on it to open the dialog. The dialog options will be populated with values from selected icon. Edit what you want and click button.



Creating and editing stacked icons ( visual editor only )

In order to create icon stack, you'll need to - insert one icon normaly, select inserted icon and open the dialog to edit icon. When the dialog appears you will see the button placed right before the button.

Select other icon within dialog, apply all desired customizations ( change icon color to better see what's happening ) and click button.

Note: Icon align and icon size classes will be applied to icon stack wrapper, not to single icon, so if you want to manually make or edit icon stack in text editor, apply all size and positioning related css rules and classes to ".iconized-stack" wrapper.

Let's create icon stack with WordPress icon from above examples and another icon.

If we select WordPress icon in visual editors content and click the button, the same dialog from the step 2 of Inserting icon example above will appear. Without closing the dialog we will select and configure icon like on the following image, and click the button to create icon stack.



This is what we will have in editor:



We will have "icon stack" - icon selected in dialog in front of the icon that have already been in editor. Also you will notice that now all four editor butons are available. The and buttons are for editing icon stacks. We will use them next.

We will click the button once. This action will swap the positions of icons in our stack ( it will bring WordPress icon to front / send blank icon to back ). After that, we will click the button, which swaps the sizes of stacked icons ( enlarge the smaller one and vice versa ), and our final result will look like this:



Note that icon stack is two times larger than single icon.

Editing icons in stack

Since the dialog can't edit both icons at once, you'll have to bring icon you wish to edit to front using button and than call the dialog with button.

Removing icon

The editor button is for removing selected icon. You can remove icon by hitting backspace on your keyboard too, but not on all browsers.

CSS Classes

The icon CSS classes naming conventions in Iconize plugin is a little different from naming conventions in stylesheets of popular icon fonts, icon fonts generators or other plugins containing icon fonts. I've done it differently mostly to try to avoid as much possible conflicts with themes and another plugins as i could. I'm sure you'll get used to it very quickly without any problems.

I've used the following scheme to define single icon ( red classes are required ).

iconized [font-class] glyph-[iconname] [effect-class] [size-class] [align-class]

As you can see above, there are three required classes that are responsible for displaying icon. Other three classes are optional.
Note about size classes:

Altho iconic font glyphs are infinitely scalable, they get blurred somethimes ( especially at small font sizes ) because every icon font have specified minimum resolution ( minimum font size in pixels ) at which icons show up crisp.

With that fact in mind, I've added two types of predefined size classes to this plugin:

All fonts included in Iconize plugin are sharp at minimum of 16px ( except Dashicons font - 20px ), and size-sharp class sets icon size to this value.

Examine the following examples ( notice that the font size of container paragraph is set to 17px ).

<p style="font-size:17px;">
    <span class="iconized font-foundicons glyph-flag"></span> - may not be sharp, icon size is 17px
    <span class="iconized font-foundicons glyph-flag size-sharp"></span> - sharp, icon size is 16px
</p>
<p style="font-size:17px;">
    <span class="iconized font-foundicons glyph-flag size-2x"></span> - may not be sharp, icon size is 2em ( 34px )
    <span class="iconized font-foundicons glyph-flag size-sharp-2x"></span> - sharp, icon size is 32px
</p>

HTML Examples

To display icon manually using HTML, you'll have to add at least three CSS classes to <span> or <i> tag ( Iconize plugin uses <span> tag ).

Single Icon Examples

Example inline icon:

<span class="iconized font-foundicons glyph-flag"></span>

Example HTML of left aligned icon, 3 times larger:

<span class="iconized font-entypo glyph-home size-3x align-left"></span>

Example spinner:

<span class="iconized font-awesome glyph-spinner animate-spin"></span>
Stacked Icons Example
<span class="iconized-stack size-3x align-left">
   <span class="iconized font-awesome glyph-android" style="color: #81d742;"></span>
   <span class="iconized font-awesome glyph-dropbox iconized-stack-base" style="color: #dd3333;"></span>
</span>
Few notes about icon stacks:

Wrapper with iconized-stack class and iconized-stack-base class added to one of two wrapped icons are required steps for creating icon stack.

Icon with iconized-stack-base class is two times larger than other icon in stack.

Second icon in stack source is displayed in front of first icon.

Classes ( or inlined CSS rules ) responsible for icon sizing and alignment, must be assigned to iconized-stack wrapper.

Icons List Example

To create icons list you must add iconized-ul class to <ul> tag and iconized-li class to each list icon.

<ul class="iconized-ul">
   <li><span class="iconized iconized-li font-awesome glyph-ok"></span>list item 1</li>
   <li><span class="iconized iconized-li font-awesome glyph-ok-circled"></span>list item 2</li>
   <li><span class="iconized iconized-li font-awesome glyph-ok-squared"></span>list item 3</li>
</ul>
Hover effect trigger element

If you want to trigger icons hover effect when user hover over one of the parent elements, you can do it by adding iconized-hover-trigger class to desired parent element.

<h4 class="iconized-hover-trigger"><span class="iconized font-awesome glyph-up-hand hover-animate-fade-out"></span> Lorem ipsum</h4>
Parent hover color inheritance

If you add hover-color-change class to icon tag, on hover, its color will change to whatever parent color is.

<p style="color: #accbe8;"><span style="color: #4d9379;" class="iconized font-entypo glyph-palette size-sharp-5x align-left hover-color-change"></span>Lorem ipsum dolor sit amet,...</p>

Similarly to menus, on each widget of Widgets admin interface and on Customizer you will find a new empty button labeled with "Widget Title Icon". To assign icon just click on this button and the dialog will appear. After selecting icon and clicking button, you will see preview of selected icon placed in button that opened the dialog.







If you want to edit or remove inserted icon, just click the button again and the dialog with configured options for that icon will be shown. Edit what you need and click button within dialog, or click button to remove it from widget title.

Proccess is the same in customizer interface. You can find icon options here:

On front end, this icon will be displayed before or after widget title and will have additional CSS class widget_title-icon so that you can easily target it in you stylesheet if you need to style it to match the design of your sidebar.

Note: We've intentionally disabled icon size and icon alignment options on the dialog in Widgets system too. If you want to include those options, you can do that using iconize_dialog_options_for_widgets filter ( read about it in the "Customization" section below ).

When you navigate to Categories or Tags ( or custom taxonomy ) edit screens you will find a new empty button labeled with "Icon", below the "Description field" and "Icon" column on term list.



On edit screens you will also have icon option.



To assign icon just click on icon button and the dialog will appear. After selecting icon and clicking button, you will see preview of selected icon placed in button that opened the dialog.

If you want to edit or remove inserted icon, just click the button again and the dialog with configured options for that icon will be shown. Edit what you need and click button within dialog, or click button to remove it from widget title.

You can display this icons on front end with Iconized Taxonomies widget or using iconize_get_term_icon_by() function.

Iconized Taxonomies widget

The fastest way to display taxonomy icons is using Iconized Taxonomies widget. You can choose which taxonomy to display, how should widget look, set fallback icon, override effect, color and hover color behavior of all icons.



Term Icon in Templates

If you want to display term icon in your archive templates ( or anywhere else ) with PHP you can use iconize_get_term_icon_by() function, which is using WordPress function - get_term_by().

Usage:

<?php iconize_get_term_icon_by( $field, $value, $taxonomy, $format $after_icon ) ?>

Parameters:
$field
(string) (required) Either 'id', 'slug' or 'name'
Default: 'id'
$value
(string|integer) (required) Search for this term value
Default: None
$taxonomy
(string) (required) Taxonomy Name category, post_tag or something custom
Default: None
$format
(string) (optional) 'html' or 'array'
Default: 'html'
$after_icon
(string) (optional) html to insert after icon
Default: '  ' two non breaking spaces
Return Values:
(string or array)
Will return empty string if $taxonomy does not exist or $term was not found or there is no icon assigned.
Othewise returns icon HTML (by default) or array of icon settings depending on $format parameter.

For example, if you want to display term icon in taxonomy archive template you can insert something like this in desired place of your archive template:

<?php echo iconize_get_term_icon_by( 'name', get_queried_object()->name, get_queried_object()->taxonomy ); ?>

If you want to customize Iconize plugins behavior or extend its functionality, please consider using built in filters instead of editing plugin files directly. This way all customizations are done from themes ( parent or child ) functions.php file and you can safely apply upcoming plugin updates.

If you have any previous experience in customizing WordPress using actions and filters, you'll find it very easy to customize or extend Iconize plugin using several custom filters We've added to it. If you don't have any expirience and you want to do something listed in this section - just follow the instructions.

All filters added by Iconize plugin ( with short descriptions ):

Extend plugin generally.

Plugin options.

Menus, widgets, taxonomies.

Editor.

Adding your own icon fonts

You can extend Iconize plugin with your own icon sets in few simple steps.

  1. Place font files and stylesheet file with icon definitions in your theme directory
  2. Prepare stylesheet file for Iconize plugin
  3. Tell the Iconize plugin where to find this stylesheet file
Example:

In this example We will add Ionicons font ( licensed under the MIT license ) to Iconize plugin. You can add any font you like in the same way, altho the folder organization in different fonts isn't always the same. The important part is that the paths to font files in @font-face declaration are correct.

Step 1. Include font files.

After extracting downloaded font package, we will copy the fonts folder and the ionicons.css file to ionicons folder of my child theme directory and edit paths to font files in ionicons.css file.

After editing, the @font-face declaration in ionicons.css file will look like this:

@font-face {
    font-family: "Ionicons";
    src: url("fonts/ionicons.eot?v=1.4.0");
    src: url("fonts/ionicons.eot?v=1.4.0#iefix") format("embedded-opentype"),
         url("fonts/ionicons.ttf?v=1.4.0") format("truetype"),
         url("fonts/ionicons.woff?v=1.4.0") format("woff"),
         url("fonts/ionicons.svg?v=1.4.0#Ionicons") format("svg");
    font-weight: normal;
    font-style: normal;
}
Step 2. Prepare stylesheet.

The next step is to edit ionicons.css so that the Iconize plugin can read icons from it. Since we only need the @font-face declaration and icons definitions, we will delete everything else. After @font-face declaration we will declare new font class.

.font-ionicons:before {
    font-family: "Ionicons";
    /* other font specific rules*/
}

The final step in preparing stylesheet is to edit singulair icon definitions to match the following pattern.

.[fontclass].glyph-[name] { content: "..."; }

In this example icons are prefixed with .ion- by default, so we will replace that with .font-ionicons.glyph- and icon definitions will be transformed from this:

.ion-alert:before {
  content: "\f101"; }

.ion-alert-circled:before {
  content: "\f100"; }

.ion-android-add:before {
  content: "\f2c7"; }

.ion-android-add-contact:before {
  content: "\f2c6"; }

.ion-android-alarm:before {
  content: "\f2c8"; }

 /* etc */

To this:

.font-ionicons.glyph-alert:before {
  content: "\f101"; }

.font-ionicons.glyph-alert-circled:before {
  content: "\f100"; }

.font-ionicons.glyph-android-add:before {
  content: "\f2c7"; }

.font-ionicons.glyph-android-add-contact:before {
  content: "\f2c6"; }

.font-ionicons.glyph-android-alarm:before {
  content: "\f2c8"; }

 /* etc */

Important note: The semicolon (;) MUST be at the end of each content property. So, if you intend to use minimized stylesheet make sure that semicolons are there. Also, each icon should have only one class name.

The final result of preparing the stylesheet file in our example should look something like this:

@font-face {
    font-family: "Ionicons";
    src: url("fonts/ionicons.eot?v=1.4.0");
    src: url("fonts/ionicons.eot?v=1.4.0#iefix") format("embedded-opentype"),
         url("fonts/ionicons.ttf?v=1.4.0") format("truetype"),
         url("fonts/ionicons.woff?v=1.4.0") format("woff"),
         url("fonts/ionicons.svg?v=1.4.0#Ionicons") format("svg");
    font-weight: normal;
    font-style: normal;
}

.font-ionicons:before {
    font-family: "Ionicons";
}

.font-ionicons.glyph-alert:before { content: "\f101"; }
.font-ionicons.glyph-alert-circled:before { content: "\f100"; }
.font-ionicons.glyph-android-add:before { content: "\f2c7"; }
.font-ionicons.glyph-android-add-contact:before { content: "\f2c6"; }
.font-ionicons.glyph-android-alarm:before { content: "\f2c8"; }
 /* etc */

Step 3. Apply font to Iconize plugin.

The final step in this process is the easiest one - just tell this plugin where to find your icons. To do that you'll have to add the following lines of code to your themes functions.php file.

Child Themes:

function my_font_styles( $array ) {

	$array['custom'] = array(
	    'path' =>  get_stylesheet_directory() . 'path/to/my/custom.css',
	    'url' => get_stylesheet_directory_uri() . 'path/to/my/custom.css'
	);

	return $array; 
}

add_filter( 'iconize_fonts_styles', 'my_font_styles' );

Parent Themes:

function my_font_styles( $array ) {

	$array['custom'] = array(
	    'path' =>  get_template_directory() . 'path/to/my/custom.css',
	    'url' => get_template_directory_uri() . 'path/to/my/custom.css'
	);

	return $array; 
}

add_filter( 'iconize_fonts_styles', 'my_font_styles' );

Our Example:

function ionicons_styles( $array ) {

	$array['ionicons'] = array(
	    'path' =>  get_stylesheet_directory() . 'ionicons/ionicons.css',
	    'url' => get_stylesheet_directory_uri() . 'ionicons/ionicons.css'
	);

	return $array; 
}

add_filter( 'iconize_fonts_styles', 'ionicons_styles' );

Using this filter you can add as many fonts as you like.

Customizing and extending dialog options

Include/exclude dialog option

As we've mentioned earlier, it is possible to control which options will be included in dialog on specific admin screen ( this doesn't applies to editor dialog ) using iconize_dialog_options_for_(screen id) filter.

The "screen-id" part in filters name refers to:

$screen = get_current_screen();
$screen_id = $screen->id;

For example, if you want to enable all options on Custom Menus or Widgets integrations, you will drop the following lines of code in your themes functions.php file:

function enable_all_dialog_options() {

    $dialog_options_array = array( 'transform', 'animate', 'hover', 'color', 'size', 'align', 'custom_classes' );

    return $dialog_options_array;
}

and:

add_filter( 'iconize_dialog_options_for_nav-menus', 'enable_all_dialog_options' );

for menus, or:

add_filter( 'iconize_dialog_options_for_widgets', 'enable_all_dialog_options' );

for widgets.

Add your own options to select dropdowns

Adding additional options to dialog align, size or effects dropdowns, is as simple as:

function my_extra_size_options( $array ) {

    $array ['my-size-class-1'] = __( 'My Size Class 1 Label', 'my-text-domain');
    $array ['my-size-class-2'] = __( 'My Size Class 2 Label', 'my-text-domain');

    return $array; 
}

add_filter( 'iconize_dialog_size_options', 'my_extra_size_options' );

Of course, you'll have to apply rules to my-size-class-1 and my-size-class-2 classes in your stylesheet file.

Usage of iconize_dialog_transform_options, iconize_dialog_animate_options, iconize_dialog_hover_options and iconize_dialog_align_options filters is the same as above. You can also override default options if you want.

Controlling plugin components and settings page

Using iconize_integrations/.../enabled, iconize_fonts/.../enabled filters you can set Iconize plugin options and hide them from settings page.

Function attached to these filters should return boolean value

Example use case scenario:

You are the site administrator or theme author, and you want to allow users of your site or theme to decide whether they will use Iconize plugin on post editor and widgets, but you don't want them to use it on menus. All you have to do is to add the following lines of code in your themes functions.php file.

add_filter( 'iconize_integrations/nav_menus/enabled', '__return_false' );

If you want to hide settings page from users completely, you'll do it like this:

add_filter( 'show_iconize_options_screen', '__return_false' );

Implementing icon selector button to custom locations in administration area ( advanced )

If you want to implement icon selector button from Custom Menus and Widgets systems on other admin pages, you can do that too. First of all, you will need to add HTML markup of icon selector button and hidden inputs on desired place. The markup should look like this:

<label class="preview-icon-label">
    Select icon:
    <button type="button" class="preview-icon button"><span class="iconized"></span></button>
</label>
<span>
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-name">
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-set">
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-transform">
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-color">
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-size">
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-align">
    <input type="hidden" id="[input id]" name="[input name]" value="" class="iconize-input-custom-classes">
</span>

After that, you will need to include dialog HTML, scripts and styles on page/s containing icon selector buttons using add_iconize_dialog_to_screens filter ( function attached to this filter must return an array of screen ids ). The final step is to find the way to store and update options from hidden fields in the database. To generate markup for single icon you can use iconize_get_icon() function.

We've used the following open source projects.

Fonts: Scripts:

Once again, thank you so much for using Iconize WordPress plugin. As we said at the beginning, We'd be glad to help you if you have any questions relating to our plugin. No guarantees, but We'll do our best to assist.

THATplugin