xF2 Add-on Font Awesome Manager 1.2.7

How can I install and configure the Add-on?​

1. If possible, install pyftsubset
2. Make sure that styles/fonts/fa is writable by PHP and install the Add-on as usual
3. Configure the options under Setup / Options / Font Awesome
   Some options are Advanced and might thus not be shown by default (buth those should not be needed for basic setups anyway, hence they are Advanced)
4. Configure style properties under Appearance / Style properties / Font Awesome

How can I install pyftsubset?​

Depending on your OS, a package of fontTools including all dependencies might or might not be available.
If a package is not available, you might have to install some dependencies manually.
At least fontTools 3.1.0 with support for WOFF and WOFF2 is required.

Debian 8-9 / Unbutu 16.04
apt-get install fonttools python-brotli

Debian 10+ / Ubuntu 18.04+
apt install fonttools

CentOS 7
Installation depends on wether Python 2.7 (default) or Python 3 is being used.

Python 2.7
If PIP (Python package manager) is not already installed, it must be installed before fonttools can be installed:
yum install python-pip

Please note that some versions of PIP may fail to install fontTools and it might therefore be necessary to use a specific PIP version.

fontTools can be installed via PIP:
pip install fonttools
pip install fonttools[woff]

Python 3
If PIP (Python package manager) is not already installed, it must be installed before fonttools can be installed:
yum install python3-pip

fontTools can be installed via PIP:
pip3 install fonttools
pip3 install fonttools[woff]

CentOS 8
TBD

I am getting warnings about modified templates, what do I have to do?​

This Add-on was built to work with the templates font_awesome_setup and fa.css as they are in standard XenForo.
If these templates have been modified you might run into probelms and it is terhefore recommended to revert them.

Can other local font subsetting tools be used instead of pyftsubset?​

Currently the Add-on does only support fontTools/pyftsubset as a local subsetting tool.
Support for other tools might be added in teh future.
If you wand to use anothe tool right now this might still be possile by creating a wrapper script that provides pyftsubset compatible commands.

How can the Add-on be configured?​

Options​

Build Mode
This option determines how the subsets are being generated.
Manual
In manual mode, it is all up to the admin - you specify the icons that should be included and that’s it.
This does allow for a very small subset (eg. by not listing social sharing icons that are referenced in templates but are not being used).
Pro: Smallest possible subset and CSS
Contra: A lot of work and hard to maintain, high chance of missing icons, currently not being tested well (if at all?)
Automatic
In automatic mode, the Add-on does try to automatically discover all icons thate are referenced in PHP files and database entities.
This usually does work pretty well but it cannot be guaranteed that every icon can be found, so the admin might still need to manually add some icons that are not being discovered automatically.
Pro: A lot eaasier than manual mode, does usually work pretty well.
Contra: Some overhead in backend processes for scanning/monitoring, subsets might/will be larger than absolutely necessary
Load subsets only
This setting controls if the subsets should be used exclusively or only additionally to the full font files.
If this setting is enabled, the subsets will be used exclusively - that original font files will not be loaded and the CSS will only contain the definitions for the icons included in the subset.
Pro Enabled: CSS will be a lot smaller if enabled
Contra Enabled: If icons are missing in the subset, those icons will not be available
Pro Disabled: All icon definitions will be available, if an icon is missing in a subset it will still be available via the full font file.
Contra Disabled: CSS will be a lot larger, if an icon is missing in the subset the browser will perform even more requests and data transfer than without this Add-on.
In most cases it would be recommended to have this option enabled. But if your site does use a large amount of icons of which many are only used on specific pages, it might make sense to keep this disabled and only have the most common used icons in the subset (might even require manual build mode).
This way, the majority of pages could benefit from the subset font file while those pages that need aadditional icons would suffer a bit.
Enable Push
If this setting is eanbeld from a client that does not have cookies (e.g there it is more or less likely that this is the first visit), WOFF2 font files will be pushed to the client if they are not being embedded in CSS and the server and client do support HTTP/2 push.
Having this setting enabled can improve performance by reducing latency as the client will most likely have the font(s) earlier than if they must be requested explicitely.
Log Level
Should be farily self-explaning. The higer the log level, the more information does get logged.
Log Level Debug does cause signigicant overhead as it does inject metadata and JavaScript into public pages to find and log missing icons.
This does increase HTML page size and JavaScript processing time on the client.
In most cases (except for initial setup/changes/troubleshooting) it is recommended to leave this at Error.
Automatically add missing icons
If this option is enabled, missing icons will be added automatically.
This is very convenient if using manual build mode or if there are quite a few missing icons.
Having this enabled does result in having the same frontend overhead as with Log Level Debug but will also trigger automatic rebuilds that will cause additional load.
In most cases it would be recommended to keep this disabled for normal production use except for initial setup/significant changes.

Style Properties​

Enable Font Awesome Duotone Icons
Having this option enabled does allow the use of Duotone icons, eg. icons in two colors.
XenForo Default style does not use duotone icons at all, so in most cases it just unused CSS and it is therefor recommended to turn this off.
Only use CSS for selected weight
If this property is enabled, CSS for weights other than the selected one is removed.
This does reduce the size of the CSS, but if are icons being used with a different weight, thos icons would be missing.
Brand Icons
The brands icon set is a distinct font file that does contain icons like Facebook, Twiotter, etc.
Those icons by default are being used on many pages causin an additional HTTP request for the font file.
By lazy loading the sharing icons, this request in many can be avoided for thei nitial page view as the icons are commonlynot not within the initial viewport.
Lazy Loading does inject a little bit of JavaScript in public pages if they contain social sharing icons which does increase HTML page size by a few hundred bytes and does increase JS processing time.
Usually, this overhead does still result in faster loading time for guests on first visit but would most likely reduce performance for registered users (which do have a high probability of having the brands icon file already in browser cache).
Generally, setting this property to Lazy Load for Guests without Cookies is recommended if it does not cause problems.
Another option to save the additional HTTP request is to embed the font file into the CSS at the expense of making it larger (but still usually a lot smaller then the original <u>fa.css</u> if using Load subsets only, disable duotone and unused wieghts) and taking more time to process it.
Main Icons
This setting does allow to choose between normal delivery and embedding the font in CSS.
Same advantages and disadvantages for embedding do apply.

What are the recommended settings?​

Each option and style property has its own advantages and disadvantages, there is no setup that is best for everyone - it always depends on the usecase.
The default settings are “fail-safe”, but they will not give the best possible performance.
Therefore it is crucial to understand what those tunables are being used for.
If the used style is pretty much Default:
Options
Build mode = Automatic
Load subsets only = Yes
Log Level = Error
Automatically add missing Icons = Disabled
Style properties
Enable Font Awesome Duotone Icons = Disabled
Font Awesome Brands = Lazy Load Share Buttons for Guests without Cookies
Only use CSS for selected weight = Enabled
Think about the usecase, decide the settings and test, test, test!

Troubleshooting​

Some icons are missing, how can I fix this?
This can (and depending on the Style and/or Add-ons will) happen.
Although the Add-on does try to automatically discover as many used icons as possible, it is not possible to finde every iconn.
If an icon is missing, it can easily be added to the appropriate list to make it available.
There are 4 lists

• • Icons
    This list is for icons that are being used in the selected Font Awesome weight (the default style does use Regular).
  • Light Icons
    This list is for icons that are being used in light weight.
    It is only being used if style property Only use CSS for selected weight is enabled and the selected Font Awesome weight is not Light.
  • Regular Icons
    This list is for icons that are being used in regular weight.
    It is only being used if style property Only use CSS for selected weight is enabled and the selected Font Awesome weight is not Regular.
  • Solid Icons
    This list is for icons that are being used in solid weight.
    It is only being used if style property Only use CSS for selected weight is enabled and the selected Font Awesome weight is not Solid.

If the name and/or weight of a missing icon is unknown, the easiest way to add it is to temporaily enable the option Automatically add missing Icons and reload the page where the icon(s) are missing.
This will automatically add the missing icon and rebuild the subsets.
Alternatively it is also possible to set option Log level to debug - this will generate error log entries for missing icons.
I am getting the error LogicException: Subset is too large to be processed
This error message does indicate that the subset (eg. the amount of icons) is too large.
transfonter.org has a limit of 5000 characters for unnicode range definition which should be mor than enough in most cases.
If you do get this error message, please check if there are templates that reference a large amount of icons without actually using them and exclude those from being scanned.