Font Awesome Manager 1.2.7

About this FAQ​

Due to the nature of this Add-on, it does have some unusual system requirements and might require more configuration effort than other Add-ons.
If you run into problems installing ur using this Add-on, please take the time to carefully read the whole FAQ - in most cases your issues should be covered here.
If you still have problems getting icons displayed properly afterwards, you can find a section how to get direct help at the very end of FAQ.
This section does include a list of all information that is necessary to provide support.
Without all the information requested it will most likely be impossible to solve your issue!

Compatibility​

Is this Add-on compatible with Add-on X?
I don't know. Most likely it is compatible but depending on what the Add-on does specific configuration might be required.

Is this Add-on compatible with Style X?
I don't know. Most likely it is compatible but depending on what the Style does specific configuration might be required.
Especially if styles are (additionally) using icon fonts other than Font Awesome 5 Pro it might be a bit problematic and require further configuration.

ThemeHouse UI.X
This Style (Framework) does (optionally) use Material Design icons, it does this by "piggybacking" on Font Awesome CSS definitions.
This does cause problems in detecting used icons and you must add the following templates to the list of ignored templates:

• uix_materialVars_solid.less
• uix_materialVars_outline.less
• uix_material_outline.less
• uix_material_solid.less

If UI.X is configured to use Font Awesome icons it is currently necessary to revert template fa.css, future versions of Font Awesome Manager might add specific support to avoid this.
Important: Don't forget that this needs to be redone whenever UI.X ist updated.

If UI.X is configured to use Material Design icons it is not necessary to revert this template.

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 (but 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.

If pyftsubset cannot be installed on the server directly (due to lack of shell access, permissions, etc.) but the server is running on Linux x64 and PHP function proc_open is not disabled, it might be possible to use a precompiled binary - this additional Add-on must to be installed after Font Awesome Manager.

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]
pip install brotli

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]
pip3 install brotli

An article describing installation of fontTools on CentOS including some benchmarks has been published at Centminmod:

CentOS 8
TBD

If pyftsubset cannot be installed system-wide for whatever reason, it might still be possible to use this Add-on by using a precompiled binary.

I am getting warnings about modified templates when trying to install the Add-on, 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 problems and it is therefore recommended to revert them.

Warning
Do not blindly revert templates if you do not know exactly what modifications were made and if those are necessary!
If you did not modify those templates yourself (eg. they are vendor-modified in a 3rd party Style you are using) contact the designer and ask for support.
Don't forget that the revert process needs to be redone whenever such styles do get updated / reimported.

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​

The options for this Add-on can be found at Admin Control Panel > Setup > Options > Font Awesome.

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.
The generated logs (if any) can be found at Admin Control Panel > Logs > Server error log

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​

The style properties for this Add-on can be found at Admin Control Panel > Appearance > Style properties > Font Awesome.

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 fa.css 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 find every icon.

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, how can I fix this?
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 unicode range definition which should be more 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.
Transfonter.org cannot be used any longer since about January 2022 as the service is actively blocking requests by XenForo.

What is a rebuild and how can a rebuild be performed?
A rebuild is an action that does regenerate the subset font files and CSS.
In automatic build mode a rebuild will be triggered automatically if necessary.
In manual build mode, rebuilds have to be done manually either via web (Admin Control Panel > Tools > Rebuild Caches > Rebuild Font Awesome subsets or via CLI command php cmd.php xf-rebuild:kirby-font-awesome.

I've tried everything, but icons are still missing or otherwise broken. How can I get help?

1. Set option Log level to Debug and perform a rebuild
2. Enable option Automatically add missing icons
3. Visit a page that has missing/broken icons in an fresh browsing context (private tab, other browser, completely cleared site data, etc.)
4. Continue browsing the forums for a few minutes
   This is necessary to trigger the execution of jobs if the site does have only a low amount of traffic (or no traffic at all).
   If this is the case you can simulate traffic by just visiting many different pages to trigger job execution.
   Alternatively it is also possible to run a rebuild job manually at his point.
5. Recheck the page from step 3)
6. Take a screenshot of the page that has missing icons and mark the area(s) where icons are missing/broken
7. Disable the Add-on
8. Revisit the page from step 3), take another screenshot and mark the area(s) where icons were missing/broken
9. Take a screenshot showing all settings in Font Awesome
10. Take a screnshot showing all style properties in Font Awesome
11. Perform a manual rebuild and save the log to a textfile
12. Start a conversation with me
    Your message must include the URL of the page from step 3), the screenshots as attachments (not embedded!) and the rebuild log.
    
    If you do provide multiple URLs for pages that have missing icons please include a table like this in your conversation message:
    

    URL	Filename screenshot FAM disabled	Filename screenshot FAM enabled
    http://example.com/threads/broken.1234	thread-fam-disabled.png	thread-fam-enabled.png
    http://example.com/members/broken.1234	member-profile-fam-disabled.png	member-profile-fam-enabled.png

    
    If the pages are not publically accesssible please also provide login details for an account that can access them.