Documentation

It is managed through the plugin's settings page.

Its result is valid only after the font_awesome_enqueued has been triggered.

It's a handy way to toggle the use of Pro icons in client theme or plugin template code.

Its results are only valid after the font_awesome_enqueued action has been triggered.

There are known performance problems with this SVG and pseudo-elements, but it is provided for added compatibility where pseudo-elements must be used.

Always returns true if technology() === 'webfont', because pseudo-elements are always inherently supported by the CSS/Webfont technology.

It accepts a GraphQL query string like 'query { releases { version } }' and returns the json encoded body of response from the API server when the response has an HTTP status of 200. Otherwise, it throws an exception whose message, if non-null, is appropriate for displaying in the WordPress admin ui to an admin user.

It also accepts an associative array with keys "query" and "variables".

Requests to the Font Awesome API server will automatically be authorized by the WordPress site owner's API Token if they have added one through the plugin's settings page. The API Token is used to retrieve a short-lived access_token, and that that access_token is used for subsequent API requests.

Refreshing an expired access_token using the API Token is also handled automatically, when necessary.

Each API Token has any number of authorization scopes on it. Most fields in the GraphQL schema have a public scope, and so do not require an API Token at all.

For example, the following query lists all icons in the latest version of Font Awesome, with various metadata properties, including an icon's membership in Font Awesome Pro and/or Font Awesome Free. All fields in this query are in the public scope.

query {
  release(version:"latest") {
    icons {
      id
      label
      membership {
        free
        pro
      }
      shim {
        id
        name
        prefix
      }
      styles
      unicode
    }
  }
}

When the site owner has configured an API Token that includes the kits_read scope, the following query would retrieve the name and version properites for each kit in that authenticated account:

query {
  me {
    kits {
      name
      version
    }
  }
}

Error Handling

Errors that prevent the API server from handling the query will result in thrown exceptions.

If the query is resolved and the request returns with an HTTP 200 status, there may still be GraphQL errors encoded in the response.

For example, if the site owner has not added an API Token, then requests to the API will only have public scope. In that case, any GraphQL schema fields that would require some higher privilege will be resolved as null, and the response body will include errors indicating the resolution failure.

For example, if the above kits query were made without an API Token having the kits_read scope, then the following response would be returned:

{
  "data":{
    "me":null
  },
  "errors":[
    {
      "locations":[
        {"column":0,"line":1}
      ],
      "message":"unauthorized",
      "path":["me"]
    }
  ]
}

It is possible that a query could select both authorized and unauthorized fields. The data property in the response will include all of those field resolutions, and the error property--if present--will include any errors during resolution, such as attempting to resolve fields without proper authorization. This is all standard GraphQL: this plugin just passes through the GraphQL query and passes back the GraphQL response without modification.

See documentation about GraphQL validation for more on error handling.

Adding Authorization

If you know that you need access to some part of the schema that requires some additional authorization scope, the way to get that is to instruct the site owner to copy an API Token from their fontawesome.com account and add it to this plugin's configuration on the plugin's settings page.

As of version 4.0.0 of this plugin, the only non-public portions of the GraphQL schema that are relevant to usage in WordPress involve querying the user's kits, which requires the kits_read scope, as shown above.

Additional Resources

For more on how to construct GraphQL queries, see here.

A reference on the Font Awesome GraphQL API is available here.

You can explore the Font Awesome GraphQL API using an app like GraphiQL. Point it at https://api.fontawesome.com.

The shape of the $client_preferences array parameter looks like this:

  array(
    'technology'        => 'svg', // "svg" or "webfont"
    'compat'            => true, // true or false
    'pseudoElements'    => false, // true or false
    'name'              => 'Foo Plugin', // (required)
    'version'           => [
                             [ '5.10.0', '>=']
                           ]
  )

We use camelCase instead of snake_case for these keys, because they end up being passed to the JavaScript admin UI client encoded as json and camelCase is preferred for object properties in JavaScript.

All preference specifications are optional, except name. The name provided here is how your theme or plugin will be identified in the Troubleshoot tab on the plugin settings page.

Only the WordPress site owner can determine the Font Awesome configuration, using the plugin's admin settings page. This registration mechanism only allows plugin or theme developers to provide hints to the site owner as to their preferred configurations. These preferences are automatically checked any time the user makes configuration changes, providing immediate visual feedback before saving changes that might cause problems for your theme or plugin.

Because this plugin also gives you an API for discovering those configured options at page load time, you can adapt to any configuration differences, or possibly issue your own admin notices to the site owner as may be appropriate.

Hopefully, the site owner will be able to set a configuration that satisfies any preferences registered by their theme and any plugins that rely upon this Font Awesome plugin. However, similar to writing mobile responsive code where you don't control the size of display but can detect the screen size and adapt, here too, theme and plugin developers do not control the Font Awesome environment but should be prepared to adapt.

The reason is that when any one theme or plugin controls or determines the Font Awesome configuration, it is very likely to produce conflicts for others. This plugin provides a coordination service to significantly increase the likelihood that everyone has a reliable Font Awesome environment.

Maximize Compatibility

Here is a checklist for maximizing compatibility.

• Write your plugin or theme to works just as well with either Webfont or SVG technology.

  There may be a good reason that you need to insist on SVG. For example, you might be building a page designer that includes a feature for for visually composing icons with Power Transforms, Layering, or Text, all features that are only avaialble in SVG. For that feature to work in your theme or plugin, the site owner must configure SVG, not Webfont.

  That may be a good use case for registering a preference for SVG. It will aid your communication with the site owner, increasingly the likelihood that they'll avoid mis-configuring Font Awesome.

  However, a tradeoff will be that using your theme or plugin is that much less compatible with others. For example, some themes or plugins reference icons as CSS pseudo-elements (not recommended, but it's common). Pseudo-elements can be enabled under the SVG technology, but there can be some significant performance problems with SVG Pseudo-elements.

  Summary: you may have a good reason to try and insist on SVG over Webfont, but your code might be running on a WordPress site where some other theme or plugin assumes a similar good reason for insisting on Webfont over SVG. We're trying to work together here to make it more delightful for the site owner to get our code up and running painlessly. Consider the tradeoffs carefully any time you think it's necessary to insist on a particular Font Awesome configuration.

• Update your icon references to use version 5 names so no v4 shim is required.

• Don't use pseudo-elements

• Be mindful of which icons you use and in which versions of Font Awesome they're available.

• Adapt gracefully when the version loaded lacks icons you want to use (see more below).

Using Pro icons

If you are shipping a theme or plugin for which you insist on being able to use Font Awesome Pro, your only option is to instruct your users to purchase and enable appropriate licenses of Font Awesome Pro for their websites.

Font Awesome version

To maximize compatibility and user-friendliness, keep track of the icons you use and in which versions they're introduced (new ones are being added all the time). Add a hook on the font_awesome_enqueued action to discover what version of Font Awesome is being loaded and either turn off or replace newer icons that are not available in older releases, or warn the site owner in your own WordPress admin UI that they'll need to update to a new version in order for icons to work as expected in your templates.

The version key in the $client_preferences array should contain one element per version constraint, where each individual constraint is itself an array of arguments that can be passed as the second and third arguments to the standard PHP version_compare function. The constraints will be ANDed together.

For example, the following means "prefer a Font Awesome version greater than or equal to 5.10.0."

  [
    [ '5.10.0', '>=']
  ]

Your theme may add this if you prefer to use Duotone style icons, since Duotone was first released in Font Awesome 5.10.0.

The following means "greater than or equal to 5.10.0 AND strictly less than 6.0.0".

  [
    [ '5.10.0', '>='],
    [ '6.0.0', '<']
  ]

Additional Notes on Specific Preferences

• compat

  This was previously called 'v4Compat'. If older code uses v4Compat, it will be taken as the value for v4Compat.

  There were major changes between Font Awesome 4 and Font Awesome 5, including some re-named icons. It's best to upgrade name references to the version 5 names, but to ease the upgrade path, the "v4 shims" accept the v4 icon names and translate them into the equivalent v5 icon names. Shims for SVG with JavaScript have been available since 5.0.0 and shims for Web Font with CSS have been available since 5.1.0.

  Another common pattern out there on the web (not a recommended practice these days, though) is to place icons as pseudo-elements where the unicode is specific in CSS as content and "FontAwesome" is specified as the font-family. The main problem here is that the font-family name has changed for Font Awesome 5, and there are multiple font-family names. So the compat feature of this plugin also "shims" those hardcoded version 4 font-family names so that they will use the corresponding Font Awesome 5 webfont files.

  There have been some changes across major versions at the level of unicode differences. For example, the glyph associated with the v4 icon named "diamond" with unicode f219 appears in FA5 and FA6 as the icon named "gem" with unicode f3a5. That glyph looked like the "precious stone" diamond.

  The glyph associated with the icon named "diamond" and unicode f3a5 in FA5 and FA6 is like the diamond as a suit in playing cards.

  Without all of the compatibility assets to fix up such mappings, any old pseudo-elements that used the v4 font-family of "FontAwesome" with a unicode of f219, when rendered using the FA5 or FA6 fonts, will get the "suit" diamond instead of the "precious stone" diamond.

  In general, a key improvement in v6 is much more comprehensive compatibility with pseudo-elements that may have been defined using font-family or unicode values from older versions. This option enables all of the various compatibility accommodations.

• pseudoElements

  Pseudo-elements are always intrinsically available when using the Web Font with CSS method. However, for the SVG with JavaScript method, additional functionality must be enabled. It's not a recommended approach, because the performance can be poor. Really poor, in some cases. However, sometimes, it's necessary.

It normally shouldn't make a difference to other theme's or plugins as to whether Font Awesome is configured to use the standard CDN or a kit. Yet this is a valid way to determine that.

Your theme or plugin can call this method in order to determine whether all of the icons used in your templates will be available, especially if you tend to use newer icons.

It should be really easy for site owners to update to a new Font Awesome version to accommodate your templates--just a simple dropdown selection on the Font Awesome plugin settings page. You might need to show an admin notice to nudge them to do so if you detect that the current version of Font Awesome being loaded is older than you'd like.

When Font Awesome is configured to use a kit, that kit may be configured to load the "latest" version. The resolution of that symoblic "latest" version happens internal to the kit's own loading logic, which is outside the scope of this plugin.

Before the release of Font Awesome 6.0.0-beta1, the symbolic version "latest" on a kit always meant: "the latest stable release with major version 5." Using "latest" for kits has been deprecated, but where it is still present on a kit, it will continue to mean just "the latest stable release with major version 5."

New symbolic major version ranges have been introduced instead "5.x" and "6.x". These mean, respectively: "the latest stable release with major version 5", and "the latest stable release with major version 6, when available, otherwise the latest pre-release with major version 6."

So if this function does not return a semver parseable version, then it must be one of these symbolic versions.

The recommended way to resolve the symbolic versions 'latest', '5.x', or '6.x' into their current concrete values is to query the GraphQL API like this:

query { release(version: "5.x") { version } }