Skip to content
This repository has been archived by the owner on Nov 16, 2018. It is now read-only.

Home

Jump to bottom
tivac edited this page Dec 18, 2011 · 23 revisions

Introduction

CSSEmbed is a simple utility to automate creation of CSS files with embedded data URIs. It can read in any CSS file, detect the image files referenced, and then replace them with data URIs. The result is a CSS file that is exactly the same as the original with the exception that all valid image files have been replaced with data URIs.

Basic Usage

CSSEmbed is used as follows:

java -jar cssembed-x.y.z.jar <options> <css file>

For example:

java -jar cssembed-x.y.z.jar -v styles.css

The -v or --verbose flags result in additional messages and warnings being output to the console, which can be useful if you run into problems.

Using the -h option shows all of the options:

Usage: java -jar cssembed-x.y.z.jar [options] [input file]

Global Options
    -h, --help              Displays this information.
    --charset <charset>     Character set of the input file.
    --mhtml                 Enable MHTML mode.
    --mhtmlroot <root>      Use <root> as the MHTML root for the file.
    -v, --verbose           Display informational messages and warnings.
    --root <root>           Prepends <root> to all relative URLs.
    --skip-missing          Don't throw an error for missing image files.
    --max-uri-length len    Maximum length for a data URI. Defaults to 32768.
    --max-image-size size   Maximum image size (in bytes) to convert.
    -o <file>               Place the output into <file>. Defaults to stdout.

Ant Task Usage

Define the task

<taskdef
    name="cssembed"
    classname="net.nczonline.web.cssembed.CSSEmbedTask"
    classpath="/path/to/cssembed.jar"
/>

then use it.

<cssembed
    root="."
    skipMissing="true"
    maxImageSize="4096"
>
    <fileset dir="." includes="**/*.css" />
</cssembed>

Attributes on the cssembed task line up with the command-line arguments, simply replace - with camelCase.

Resolving Files

When CSSEmbed comes across a URL reference in CSS (url(filename)), it inspects the filename to determine where the file is actually located. If the filename begins with “http://”, then the file is downloaded from that location. Files that don’t begin with “http://” are assumed to be local and their location is resolved relative to the location of the CSS file. If, for example, the CSS code contains url(../../image.png), then CSSEmbed looks to the directory that is two levels above the CSS file for image.png.

You can force a specific resolution by using the --root option on the command line and specifying what the root should be. For example:

java -jar cssembed-x.y.z.jar --root http://www.nczonline.net/images styles.css

This causes all image URLs to be prepended with http://www.nczonline.net/images before attempting resolution (this happens only for those URLs that don’t already have “http://” at the beginning.

Skipping Images

You can specify that an image should be skipped by adding a special comment after the image:

background: url(foo.png);  /*CSSEmbed:SKIP*/

This ensures that the given image will not be converted to a data URI regardless of command line settings.

MHTML Support

Version 0.3.0 introduces initial support for generating MHTML CSS files (for more information on MHTML files, see MHTML – when you need data: URIs in IE7 and under). When you specify the --mhtml option, this puts CSSEmbed into MHTML mode and the resulting CSS file is generated for use with Internet Explorer 7 and lower using the format specified in the linked article.

You must specify a root URL to use in the generated file. As per MHTML format, each url() must be filled in with a fully-qualified URL. Since there is no way for CSSEmbed to guess where the resulting output file will reside, you need to pass in that information using --mhtmlroot, such as:

java -jar cssembed-x.y.z.jar --mhtml --mhtmlroot http://www.example.com/styles/ -o styles_ie.css styles.css

The filename used inside of the resulting CSS file will be http://www.example.com/styles/styles_ie.css.

A note about IE on Vista: MHTML doesn’t always work with default settings. Please read Mhtml doesn’t work in Vista IE7 for more information.

Troubleshooting

I get a java.lang.UnsupportedClassVersionError message

You may get encounter an error such as this:

Exception in thread “main” java.lang.UnsupportedClassVersionError: Bad version number in .class file
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(ClassLoader.java:675)
at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:124)
at java.net.URLClassLoader.defineClass(URLClassLoader.java:260)
at java.net.URLClassLoader.access$100(URLClassLoader.java:56)
at java.net.URLClassLoader$1.run(URLClassLoader.java:195)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:188)
at java.lang.ClassLoader.loadClass(ClassLoader.java:316)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:280)
at java.lang.ClassLoader.loadClass(ClassLoader.java:251)
at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:374)

This means that you’re attempting to run CSSEmbed on an earlier version of the JVM. CSSEmbed requires Java 1.5 to execute.

Related Reading

Posts About CSSEmbed

Posts About Data URIs

Copyright and License

Copyright © 2009 Nicholas C. Zakas. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Clone this wiki locally