Skip to content

Alpha Release: 5.0.0-alpha1

Pre-release
Pre-release
Compare
Choose a tag to compare
@mlwilkerson mlwilkerson released this 06 Aug 01:14
· 9 commits to epic/v5 since this release
5.0.0-alpha1
88cc4e5

Overview

The big changes:

  1. Improved block editor experience
  2. Icon chooser performance improvements
  3. Support for use without CDN dependence

add-icons

This release introduces major changes to the block editing experience with Font Awesome. What you see is what you get (WYSIWYG)! Icons appear visually in the block editor just as they'll render on front end web pages. They can be styled and animated visually. They can be added as icon blocks, or as rich text within any rich text block--like paragraphs.

This version also introduces the possibility of loading without dependence on the Font Awesome CDN for front end page loads (the CDN is still used on the back end by admins and content creators). This may be preferable for users looking to avoid CDN usage as part of their GDPR-compliance, for example.

The icon chooser now queries the Font Awesome API service directly, instead of proxying through the WordPress server. This will avoid some lag and errors experienced by some users, and overall reduces the round trip request times.

The icon chooser also uses localStorage to cache queries, especially the initial query for kit metadata, which is required for loading the icon chooser modal. This results in a much snappier open event once cached. (However, it currently requires manual cache-clearing to get kit settings updates, including new custom icons.)

Install and Use

  1. Download the font-awesome.zip attached to this release.
  2. In WP Admin, select Plugins -> Add New Plugin in WP Admin.
  3. Click "Upload Plugin" and choose the font-awesome.zip you just downloaded.
  4. If you haven't already configured the plugin, go copy an API token from your fontawesome.com account. (It needs to have the "Read kits data" scope.)
  5. In WP Admin, go into the Font Awesome plugin settings by clicking Settings on the plugin entry on the plugins page, or Settings -> Font Awesome from the side nav.
  6. Choose "Use a Kit" and paste in your API token, if you haven't already.
  7. Select a kit, if you haven't already.
  8. Save changes.
  9. Edit or create a new post using the block editor.
  10. Add a block, select the "Font Awesome Icon" block.
  11. Or create a paragraph block--after enter some content, click the Font Awesome icon on the rich text toolbar.
    style-icons

Skip Kit Loading

A new WordPress filter has been introduced for skipping the enqueue of the kit. Add this one line to your theme's functions.php, for example:

add_filter( 'font_awesome_skip_enqueue_kit', '__return_true' );

This is the first move to load frontend pages without dependence on the Font Awesome CDN.

Heads Up: <i> tags won't render when skipping kit loading

Another other consequence of not loading the kit is that there will be no <i> tag support, and thus, no [icon] shortcode support (shortcodes still just output <i> tags).

If you skip loading the kit, then <i> tags will not render.

Some users find that multiple versions of Font Awesome are being loaded by their theme or other plugins. Skipping this plugin's loading of the kit on frontend page loads won't block those other plugins from loading whatever they load. (Though you may be able to block them using this plugin's Troubleshoot tab). Thus, if they are already loading Font Awesome in a way that works for them, then this might be just what you want: while this plugin won't load a kit, if another plugin loads its own version of Font Awesome to use with its own <i> tags or CSS pseuo-elements (::before), then it should still work.

Self-host SVG styles

In the block editor, this plugin now inserts <svg> elements directly into the post content. This is the final markup and no other rendering is required on the server side or client side.

However, styling via CSS is still required.

By default, the plugin will load those styles from the Font Awesome CDN.

A new filter allows you to switch that to self-hosting. Set this in your functions.php, for example:

add_filter(
	'font_awesome_svg_styles_loading',
	function() {
		return 'selfhost';
	}
);

Valid values are "selfhost", "cdn", or false.

By default, this asset is not loaded when loading an SVG Kit, because that would result in the same SVG support styling being added twice.

If this filter is set to "selfhost", then when you save any Font Awesome plugin settings, during that save action, the plugin will retrieve the stylesheet from the Font Awesome CDN and place in a versioned directory wherever your wp_upload_dir() points to. For example:

wp-content/uploads/font-awesome/v6.6.0/css/svg-with-js.css

Remove CDN Dependence for frontend page loads

To remove CDN dependence for frontend page loads, filter font_awesome_skip_enqueue_kit to return true, and font_awesome_svg_styles_loading to return "selfhost". See above.

Clear Icon Chooser Cache to Get Custom Icon Updates

One of the performance improvements to the icon chooser is that the kit metadata query is cached in the browser's localStorage. That kit metadata query is necessary to power the icon chooser: it provides all of the info about your kit, including its version of Font Awesome, and any of its custom icons. Now, after the initial opening of the icon chooser for a given kit, subsequent opens of the icon chooser happen in the blink of an eye.

Most of the time, that seems best.

However, if you change the version of Font Awesome used by the kit, or add or change any custom icons, you'll need to clear that cache, and then just use the icon chooser again--it'll run a fresh query.

For this alpha release, clearing that cache is a manual process.

Open the browser's Dev Tools, locate its localStorage for your web domain, and find a value that starts with {"data":{"me":{"kit". Select and delete it. That's it!

For example, this screenshot shows what that looks like in a Chromium browser:
wp-fa-5-0-0-alpha1-clear-cache

Outside the Block Editor

  • Working with icons in the Classic Editor has not changed. The icon chooser still inserts a textual shortcode.
  • See also the above not about <i> tags and shortcode not working when you skip kit loading.
  • If you use another page editor other than the block editor--same thing--there are no relevant changes to your editing experience. You should not skip kit loading, because your editor's Font Awesome integration probably relies on either <i> tags or [icon] shortcodes working.

Breaking Changes

  • Requires PHP 7.4 or newer.
  • Requires WordPress 5.8 or newer.
  • Deprecated v3 icon name usage in shortcodes has been removed.

Full Changelog: 4.4.0...5.0.0-alpha1

Assets 3
Loading