Skip to content

Commit b5d8fc9

Browse files
michaelspissmichaelspiss
committed
Add configurator usage information to readme
1 parent 3502d79 commit b5d8fc9

File tree

2 files changed

+117
-60
lines changed

2 files changed

+117
-60
lines changed

‎README.md‎

Lines changed: 117 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -54,85 +54,101 @@ Icon name | Code | Style
5454

5555
View the Flutter app in the `example` directory to see all the available `FontAwesomeIcons`.
5656

57-
## FAQ
58-
59-
### Why aren't the icons aligned properly or why are the icons being cut off?
60-
61-
Please use the `FaIcon` widget provided by the library instead of the `Icon`
62-
widget provided by Flutter. The `Icon` widget assumes all icons are square, but
63-
many Font Awesome Icons are not.
57+
## Customizing font awesome flutter
6458

65-
### What about file size
66-
This package has been written in a way so that it only uses the minimum amount of resources required.
59+
We supply a configurator tool to assist you with common customizations to this package.
60+
All options are interoperable.
61+
By default, if run without arguments and no `icons.json` in `lib/fonts` exists, it updates all icons to the
62+
newest free version of font awesome.
6763

68-
All links (eg. `FontAwesomeIcons.abacus`) to unused icons will be removed automatically, which means only required icon
69-
definitions are loaded into ram.
64+
### Setup
65+
To use your custom version, you must first clone [this repository](https://github.com/fluttercommunity/font_awesome_flutter.git)
66+
to a location of your choice and run `flutter pub get` inside. This installs all dependencies.
7067

71-
Flutter 1.22 added icon tree shaking. This means unused icon "images" will be removed as well. However, this only
72-
applies to styles of which at least one icon has been used. Assuming only icons of style "regular" are being used,
73-
"regular" will be minified and "solid" and "brands" will stay in their raw, complete form. This issue is being [tracked
74-
over in the flutter repository](https://github.com/flutter/flutter/issues/64106). While it is open, a workaround is
75-
to create an icon of each style and put it in an invisible container.
68+
The configurator is located in the `util` folder and can be started by running `configurator.bat` on Windows, or
69+
`configurator.sh` on linux. All following examples use the `.sh` version, but are exactly the same for `.bat`.
70+
An overview of available options can be viewed with `configurator.sh --help`.
7671

77-
### Why aren't the icons showing up on Mobile devices?
72+
To use your customized version in an app, go to the app's `pubspec.yaml` and add a dependency for
73+
`font_awesome_flutter: '>= 4.7.0'`. Then override the dependency's location:
74+
```yaml
75+
dependencies:
76+
font_awesome_flutter: '>= 4.7.0'
77+
...
78+
79+
dependency_overrides:
80+
font_awesome_flutter:
81+
path: /path/to/your/font_awesome_flutter
82+
...
83+
```
7884

79-
If you're not seeing any icons at all, sometimes it means that Flutter has a cached version of the app on device and hasn't pushed the new fonts. I've run into that as well a few times...
85+
### Enable pro icons
86+
:exclamation: By importing pro icons you acknowledge that it is your obligation
87+
to keep these files private. This includes **not** uploading your package to
88+
a public github repository or other public file sharing services.
8089

81-
Please try:
90+
* Go to the location of your custom font_awesome_flutter version (see [setup](#setup))
91+
* Download the web version of font awesome pro and open it
92+
* Move **all** `.ttf` files from the `webfonts` directory and `icons.json` from `metadata` to
93+
`/path/to/your/font_awesome_flutter/lib/fonts`. Replace existing files.
94+
* Run the configurator. It should say "Custom icons.json found"
8295

83-
1. Stopping the app
84-
2. Running `flutter clean` in your app directory
85-
3. Deleting the app from your simulator / emulator / device
86-
4. Rebuild & Deploy the app.
96+
It may be required to run `flutter clean` in apps who use this version for changes to appear.
8797

88-
### Why aren't the icons showing up on Web?
98+
### Excluding styles
99+
One or more styles can be excluded from all generation processes by passing them with the `--exclude` option:
100+
```
101+
$ configurator.sh --exclude solid
102+
$ configurator.sh --exclude solid,brands
103+
```
89104

90-
Most likely, the fonts were not correctly added to the `FontManifest.json`.
91-
Note: older versions of Flutter did not properly package non-Material fonts
92-
in the `FontManifest.json` during the build step, but that issue has been
93-
resolved and this shouldn't be much of a problem these days.
105+
See the [optimizations](#what-about-file-size-and-ram-usage) and [dynamic icon retrieval by name](#retrieve-icons-dynamically-by-their-name-or-css-class)
106+
sections for more information as to why it makes sense for your app.
94107

95-
Please ensure you are using `Flutter 1.14.6 beta` or newer!
108+
### Retrieve icons dynamically by their name or css class
109+
Probably the most requested feature after support for pro icons is the ability to retrieve an icon by their name.
110+
This was previously not possible, because a mapping from name to icon would break all
111+
[discussed optimizations](#what-about-file-size-and-ram-usage). Please bear in mind that this is still the case.
112+
As all icons could theoretically be requested, none can be removed by flutter. It is strongly advised to only use this
113+
option in conjunction with [a limited set of styles](#excluding-styles) and with as few of them as possible. You may
114+
need to build your app with the `--no-tree-shake-icons` flag for it to succeed.
96115

97-
### How can I use pro icons?
116+
Using the new configurator tool, this is now an optional feature. Run the tool with the `--dynamic` flag to generate...
117+
```
118+
$ configurator.sh --dynamic
119+
```
120+
...and the following import to use the map. For normal icons, use `faIconMapping` with a key of this format:
121+
'style icon-name'. For duotone icon, use `faIconMappingDuotone` - the icon name is sufficient as key.
122+
```dart
123+
import 'package:font_awesome_flutter/name_icon_mapping.dart';
98124
99-
This library only packages the free Font Awesome icon fonts. If you own the pro
100-
icon fonts and want to use them with Flutter, please follow these instructions.
125+
...
126+
FaIcon(
127+
icon: faIconMapping['solid abacus'],
128+
);
129+
...
130+
```
101131

102-
:exclamation: By importing pro icons you acknowledge that it is your obligation
103-
to keep these files private. This includes **not** uploading your package to
104-
a public github repository or other public file sharing services.
132+
To exclude unused styles combine the configurator options:
133+
```
134+
$ configurator.sh --dynamic --exclude solid
135+
```
105136

106-
* Clone [this repository](https://github.com/fluttercommunity/font_awesome_flutter.git) to a location of your choice and go into the newly created directory.
107-
* Remove `#`s from `pubspec.yaml` at the indicated position
108-
* run `flutter packages get`
109-
* Download your font awesome pro icons (web version)
110-
* Move **all** `.ttf` files from the `webfonts` directory to `/path/to/your/font_awesome_flutter/lib/fonts` (replace existing fonts)
111-
* _Note:_ Please make sure **all** `.ttf` files (and the following `icons.json`) are of the same version to avoid missing icons!
112-
* Move `icons.json` from `metadata` to `/path/to/your/font_awesome_flutter`
113-
* From there run `./tool/update.sh` on linux or `.\tool\update.bat` on windows
114-
* _Note for windows users:_ Please run the script in cmd or powershell only. Flutter is known to have problems with third-party shells.
115-
* Add version `>= 4.7.0` to your project's dependencies, Override it with the path to your local installation:
116137

117-
```yaml
118-
dependencies:
119-
font_awesome_flutter: '>= 4.7.0'
120-
...
121-
122-
dependency_overrides:
123-
font_awesome_flutter:
124-
path: /path/to/your/font_awesome_flutter
125-
...
138+
A common use case also includes fetching css classes from a server. The utility function `getIconFromCss()` takes a
139+
string of classes and returns the icon which would be shown by a browser:
140+
```dart
141+
getIconFromCss('far custom-class fa-abacus'); // returns the abacus icon in regular style. custom-class is ignored
126142
```
127143

128-
### Duotone icons
144+
## Duotone icons
129145

130146
Duotone icons require special treatment. Instead of `FaIcon` a special class
131147
`FaDuotoneIcon` needs to be used. It allows to set the primary and secondary colors
132148
for the icon. If primary and / or secondary color are not defined, they will default
133-
to the standard `IconTheme` color. Please be aware that only duotone style icons
134-
can be passed to this class. `FaDuotoneIcon` is only available if at least one duotone
135-
icon is available.
149+
to the standard `IconTheme` color. Please be aware that only duotone style icons
150+
can be passed to this class. `FaDuotoneIcon` is only available if [at least one duotone
151+
icon was added using the configurator](#enable-pro-icons).
136152

137153

138154
```dart
@@ -142,3 +158,46 @@ FaDuotoneIcon(
142158
secondaryColor: Colors.black,
143159
);
144160
```
161+
162+
## FAQ
163+
164+
### Why aren't the icons aligned properly or why are the icons being cut off?
165+
166+
Please use the `FaIcon` widget provided by the library instead of the `Icon`
167+
widget provided by Flutter. The `Icon` widget assumes all icons are square, but
168+
many Font Awesome Icons are not.
169+
170+
### What about file size and ram usage
171+
This package has been written in a way so that it only uses the minimum amount of resources required.
172+
173+
All links (eg. `FontAwesomeIcons.abacus`) to unused icons will be removed automatically, which means only required icon
174+
definitions are loaded into ram.
175+
176+
Flutter 1.22 added icon tree shaking. This means unused icon "images" will be removed as well. However, this only
177+
applies to styles of which at least one icon has been used. Assuming only icons of style "regular" are being used,
178+
"regular" will be minified to only include the used icons and "solid" and "brands" will stay in their raw, complete
179+
form. This issue is being [tracked over in the flutter repository](https://github.com/flutter/flutter/issues/64106).
180+
181+
However, using the configurator, you can easily exclude styles from the package. For more information, see
182+
[customizing font awesome flutter](#customizing-font-awesome-flutter)
183+
184+
### Why aren't the icons showing up on Mobile devices?
185+
186+
If you're not seeing any icons at all, sometimes it means that Flutter has a cached version of the app on device and
187+
hasn't pushed the new fonts. I've run into that as well a few times...
188+
189+
Please try:
190+
191+
1. Stopping the app
192+
2. Running `flutter clean` in your app directory
193+
3. Deleting the app from your simulator / emulator / device
194+
4. Rebuild & Deploy the app.
195+
196+
### Why aren't the icons showing up on Web?
197+
198+
Most likely, the fonts were not correctly added to the `FontManifest.json`.
199+
Note: older versions of Flutter did not properly package non-Material fonts
200+
in the `FontManifest.json` during the build step, but that issue has been
201+
resolved and this shouldn't be much of a problem these days.
202+
203+
Please ensure you are using `Flutter 1.14.6 beta` or newer!

‎util/lib/main.dart‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -537,8 +537,6 @@ Future download(String url, File target) async {
537537
ArgParser setUpArgParser() {
538538
final argParser = ArgParser();
539539

540-
// TODO: Update readme with new workflow for pro icons
541-
// TODO: Update readme with new workflow to exclude styles "customizing font awesome flutter"
542540
argParser.addFlag('help',
543541
abbr: 'h',
544542
defaultsTo: false,

0 commit comments

Comments
 (0)