Working with icons

Recommendations

Only add new icon when it is needed in the GUI
Do not use the same icon to represent different features

Font Awesome Icon Subsetting

HSLayers-NG uses Font Awesome icons and provides a custom subsetting mechanism to optimize the bundle size by including only the icons that are needed.

For HSLayers-NG Library Developers

Overview

The library uses a Python script (create-fa-icons.py) to generate an optimized subset of Font Awesome icons. This script:

Reads a list of required icons from icons.txt
Extracts icon definitions from Font Awesome's CSS
Creates font subsets containing only the required glyphs
Embeds the fonts as base64 in the output CSS
Includes necessary CSS rules for icon display

Updating Library Icons

Browse available icons at Font Awesome Free Icons
Update the icon list in projects/hslayers/css/icons/icons.txt:
```
pencil
cloud
map-location
# Add one icon name per line
```

Run the script using either:

# Option 1: Run directly
cd projects/hslayers/css/icons
python create-fa-icons.py

# Option 2: Use npm script
npm run subset-icons

This will generate hslayers-ng-fa-icons.css with the optimized icon subset.

Rebuild the library to include the updated icons.

Script Details

The script supports the following arguments:

--icons-file: Path to icon list file (default: icons.txt)
--output-file: Path for generated CSS (default: hslayers-ng-fa-icons.css)
--fa-path: Path to @fortawesome/fontawesome-free package (optional)

For HSLayers-NG Users

If you need additional Font Awesome icons in your application that aren't included in HSLayers-NG's default set, you can create your own optimized subset.

Creating Custom Icon Subset

There are several ways to generate your custom icon subset:

Option 1: Direct Command Line Usage

Create your icon list file (e.g., custom-icons.txt):
```
chart-line
chart-pie
map-marker
# One icon name per line
```
Browse available icons at Font Awesome Free Icons

Run the Python script directly:

# If using the script from node_modules
python ./node_modules/hslayers-ng/css/icons/create-fa-icons.py \
  --icons-file ./custom-icons.txt \
  --output-file ./custom-fa-icons.css

# Or if you copied the script locally
python create-fa-icons.py \
  --icons-file ./custom-icons.txt \
  --output-file ./custom-fa-icons.css

The script will:

Read icons from custom-icons.txt
Generate optimized CSS at custom-fa-icons.css
Automatically locate Font Awesome in node_modules

Import the generated CSS in your styles:
```
@use "./custom-fa-icons.css";
```

Option 2: Using Node Script

Create your icon list file (e.g., custom-icons.txt) as shown in Option 1.

Create a script to generate your custom subset (e.g., generate-icons.js):

const { execSync } = require('child_process');
const path = require('path');

const ICONS_FILE = path.join(__dirname, './custom-icons.txt');
const OUTPUT_FILE = path.join(__dirname, './custom-fa-icons.css');
const SCRIPT_PATH = path.join(__dirname, 
  '../../node_modules/hslayers-ng/css/icons/create-fa-icons.py');

try {
  console.log('Generating custom Font Awesome icons subset...');
  const command = `python "${SCRIPT_PATH}" --icons-file "${ICONS_FILE}" --output-file "${OUTPUT_FILE}"`;
  execSync(command, { stdio: 'inherit' });
} catch (error) {
  console.error('Error generating icons:', error.message);
  process.exit(1);
}

Add a script to your package.json:

{
  "scripts": {
    "generate-icons": "node generate-icons.js"
  }
}

Run the generator:
```
npm run generate-icons
```
Import the generated CSS in your styles:
```
@use "./custom-fa-icons.css";
```

Requirements

Python 3.x
fonttools Python package (pip install fonttools)
@fortawesome/fontawesome-free npm package

Notes

The generated CSS will only include the icons you specified
Base Font Awesome styles are already included in HSLayers-NG
Generated file includes optimized font subsets as base64
Custom icons work alongside HSLayers-NG's default icons

(DEPRECATED since v15): How to add new icon from the WHHG font

Find the icon you need at https://www.webhostinghub.com/glyphs/#preview
Inspect the icon to find its code, e.g. .icon-addcomment::before {content: '\f74a';}
Copy this CSS style into whhg.css file (projects > hslayers > css > whhg-font > css)
Add correspondingg new line inside the subset-font.sh file (projects > hslayers > css), e.g. # icon-addcomment U+f74a and the icon's code into the penultimate line, e.g. ...",U+f05c,U+f74a" --output-file="...
Run the subset-font.sh script
Navigate to https://www.giftofspeed.com/base64-encoder/ , encode the updated subset.ttf file and copy the base64-encoded content
Paste the base64-encoded font inside the src property of @font-face rule inside the whhg.css file. E.g. @font-face { font-family: 'WebHostingHub-Glyphs'; /* Encoded using https://www.giftofspeed.com/base64-encoder/ */ src: url(data:font/opentype;charset=utf-8;base64,AAEAAAAQAQAABAAAR0RFRgASAE..... Don't touch the url(data:font/opentype;charset=utf-8;base64, prefix, neither the ) format('truetype'); suffix
DONE