jkphl / iconizr
A PHP command line tool for converting SVG images to a set of CSS icons (SVG & PNG, single icons and / or CSS sprites) with support for image optimization and Sass output
Installs: 8 761
Dependents: 0
Suggesters: 0
Security: 0
Stars: 485
Watchers: 28
Forks: 36
Open Issues: 11
Language:CSS
This package is auto-updated.
Last update: 2024-10-23 00:18:44 UTC
README
is an – at present: proof-of-concept – command line tool that helps you prepare your vector based SVG icons for use with the widest possible range of devices. It takes a folder of SVG files and processes them to a bunch of files including
- cleaned versions of the original SVG icons (optional),
- a single compact SVG icon sprite,
- single PNG icons (optional),
- a combined PNG icon sprite,
- several CSS files with different formats, including
- SVG single image icons (optional),
- SVG data URIs,
- SVG sprite references,
- PNG single image icons (optional),
- PNG data URIs and
- PNG sprite references,
- Sass variants (scss dialect) of these CSS files for easy inclusion into your Sass project,
- a HTML fragment including some JavaScript for asynchronously loading the most appropriate icon variant
- and finally a couple of HTML preview documents (depending on the options you specified) for previewing and testing the different icon variants.
To leverage iconizr to the greatest extent possible, some additional tools have to be installed on the system independently (see below).
iconizr is written in (namespaced) PHP and meant to be used on the (Linux) command line (i.e. with the PHP CLI SAPI). To be honest, there was only one reason making me go for PHP: It is what I know best. Im sure there are quite some other fancy modern languages and techniques one could use for achieving the same, but I guess I'm just not smart enough for those. Having said this, I'd welcome anyone contributing a port of iconizr.
Getting started
As iconizr is written in PHP, there's nothing much of an installation process. Just put the iconizr.phps
script (along with it's accompanying files and directories) to a location of your liking and make sure that it may be executed by setting the proper file permissions. If you'd like to simplify the invocation of iconizr you might create a symlink into your local executables directory, e.g.:
ln -s /path/to/iconizr.phps /usr/local/bin/iconizr
Run iconizr by calling the script with the apropriate command line options (see below). Please consider that – for security reasons – the output directory has to be a sub(sub)directory of the current working directory, so change your working directory first if necessary:
cd /path/to/website/docroot
/path/to/iconizr.phps --css --out css source/svg
or using the symlink mentioned above:
iconizr --css --out css source/svg
This will take all the SVG files found in /path/to/website/docroot/source/svg
and render the resulting CSS files and sprites to the directory /path/to/website/docroot/css
(and below). For the sake of simplicity, Sass files have been omitted in this example.
Documentation
Usage:
iconizr [options] input/dir1 [input/dir2 ...]
CSS pseudo classes
As of Beta 5 iconizr supports CSS pseudo classes (like e.g. hover or active states) for individual icons. To bind an icon to a specific pseudo class, just append it as a suffix to the icon file name, separated by the string specified with the --pseudo
parameter (defaults to a tilde ~
). For example, two icon files named
foo-bar.svg
foo-bar~hover.svg
would result in the CSS rules
icon-foo-bar { ... }
icon-foo-bar:hover { ... }
This way you can easily achieve a normal and a hover state for an icon. In general, any conceivable pseudo class can be generated like this, as long as the involved characters are allowed in file names on your system. In fact, iconizr isn't aware of what is a real CSS pseudo class and what isn't, it's just dumb delimiter-to-colon substitution ... These could be some reasonable examples:
hover
active
target
first-child
last-child
nth-child()
...
The storm icon included in this package is an example for an icon with hover state:
In the HTML preview documents both icons will be shown, but also if you hover over the regular one, you will see it's hover state as well.
For every pseudo class iconizr also adds an additional CSS selector which you can use to explicitly apply the stateful icon styles to an element (independently from the element's real state). Starting with version v0.1.2 iconizr even adds such a selector for the regular icon state (which doesn't have a pseudo class by design), so you can also use this icon variant without letting the other pseudo classes become effective:
icon-foo-bar, icon-foo-bar\:regular { ... }
icon-foo-bar:hover, icon-foo-bar\:hover { ... }
To apply these icon styles to HTML elements just use them like this:
<span class="icon-foo-bar:regular">Regular icon state</span>
<span class="icon-foo-bar:hover">Hover icon state</span>
It may seem weird to use colons als parts of CSS class names, but in fact it's perfectly legal – you just have to escape the colons in your CSS files using a backslash \
.
Comparison to grunticon
While doing pretty much the same as the Filament Group's / Scott Jehl's grunticon, iconizr especially focuses on reducing the size of files and number of HTTP requests, addressing mobile devices in particular:
- SVG files are cleaned and freed from a lot of cruft typically introduced by SVG editing application before they get converted to data URIs or embedded into the SVG sprite.
- PNG files are losslessly optimized (and optionally quantized to 8-bit files) before being used in data URIs or the PNG sprite.
- As soon as even one of the icons needs to be loaded externally (due to exceeding a potential data URI size limitation), all icons will get loaded via the corresponding sprite.
Evtl. kein Limit für data-URIs bei SVG? Welcher Browser mit SVG-Support hat das kleinste data-URI-Limit?
Requirements
For iconizr to run, you will need some programs installed on your machine. These are:
For SVG optimization you will need either of the following (or both):
For PNG optimization you should have as many of the following as possible:
Other versions
I'm currently working on a native Node.js / Grunt / Gulp.js implementation of iconizr. As a first step, I published svg-sprite (respectively grunt-svg-sprite) which will be the SVG sprite generator component. As opposed to the PHP based iconizr, svg-sprite comes with several improvements like Mustache template based output, so you can produce customized CSS output (formats). I plan to backport these improvements to the PHP based version as well.
Also, I'm very happy to announce that Haithem Bel Haj published an iconizr Grunt plugin that's based on the PHP based version of iconizr, so you can start using iconizr with Grunt right away! Cool, huh?
Resources
There are some useful resources on data URIs in general:
- Data URIs
- Data URI support
- Data URI limitation to 128kB on iPhone / Safari 3.0
- Data URI limitation checker to test which data URI size is supported by your device
As soon as I'll find some time I will do some tests in our Open Device Lab to see if there are any device specific data URI limitations.
Resources on SVG support:
Legal
Copyright © 2014 Joschi Kuphal joschi@kuphal.net / @jkphl
As of version 0.1.1, iconizr is licensed under the terms of the MIT license. Before that, a Creative Commons Attribution 3.0 Unported License applied.
The contained example SVG icons are part of the Tango Icon Library and belong to the Public Domain.