CSS::Squish(3) User Contributed Perl Documentation CSS::Squish(3)NAMECSS::Squish - Compact many CSS files into one big file
SYNOPSIS
use CSS::Squish;
my $concatenated = CSS::Squish->concatenate(@files);
my $squisher = CSS::Squish->new( roots => ['/root1', '/root2'] );
my $concatenated = $squisher->concatenate(@files);
DESCRIPTION
This module takes a list of CSS files and concatenates them, making
sure to honor any valid @import statements included in the files.
The benefit of this is that you get to keep your CSS as individual
files, but can serve it to users in one big file, saving the overhead
of possibly dozens of HTTP requests.
Following the CSS 2.1 spec, @import statements must be the first rules
in a CSS file. Media-specific @import statements will be honored by
enclosing the included file in an @media rule. This has the side
effect of actually improving compatibility in Internet Explorer, which
ignores media-specific @import rules but understands @media rules.
It is possible that future versions will include methods to compact
whitespace and other parts of the CSS itself, but this functionality is
not supported at the current time.
COMMON METHODS
new( [roots=>[...]] )
A constructor. For backward compatibility with versions prior to 0.06
you can still call everything as a class method, but should remember
that roots are shared between all callers in this case.
if you're using persistent environment (like mod_perl) then it's very
recomended to use objects.
concatenate( @files )
Takes a list of files to concatenate and returns the results as one big
scalar.
concatenate_to( $dest, @files )
Takes a filehandle to print to and a list of files to concatenate.
"concatenate" uses this method with an "open"ed scalar.
RESOLVING METHODS
The following methods help map URIs to files and find them on the disk.
In common situation you control CSS and can adopt it to use imports
with relative URIs and most probably only have to set root(s).
However, you can subclass these methods to parse css files before
submitting, implement advanced mapping of URIs to file system and other
things.
Mapping works in the following way. When you call concatenate method we
get content of file using file_handle method which as well lookup files
in roots. If roots are not defined then files are treated as absolute
paths or relative to the current directory. Using of absolute paths is
not recommended as unhide server dirrectory layout to clients in css
comments and as well don't allow to handle @import commands with
absolute URIs. When files is found we parse its content for @import
commands. On each URI we call resolve_uri method that convert absolute
and relative URIs into file paths.
Here is example of processing:
roots: /www/overlay/, /www/shared/
$squisher->concatenate('/css/main.css');
->file_handle('/css/main.css');
->resolve_file('/css/main.css');
<- '/www/shared/css/main.css';
<- handle;
content parsing
find '@import url(nav.css)'
-> resolve_uri('nav.css', '/css/main.css');
<- '/css/nav.css';
... recursivly process file
find '@import url(/css/another.css)'
-> resolve_uri('/css/another.css', '/css/main.css');
<- '/css/another.css'
...
roots( @dirs )
A getter/setter for paths to search when looking for files.
The paths specified here are searched for files. This is useful if your
server has multiple document roots or document root doesn't match the
current dir.
See also 'resolve_file' below.
file_handle( $file )
Takes a path to a file, resolves (see resolve_file) it and returns a
handle.
Returns undef if file couldn't be resolved or it's impossible to open
file.
You can subclass it to filter content, process it with templating
system or generate it on the fly:
package My::CSS::Squish;
use base qw(CSS::Squish);
sub file_handle {
my $self = shift;
my $file = shift;
my $content = $self->my_prepare_content($file);
return undef unless defined $content;
open my $fh, "<", \$content or warn "Couldn't open handle: $!";
return $fh;
}
Note that the file is not resolved yet and is relative to the root(s),
so you have to resolve it yourself or call resolve_file method.
resolve_file( $file )
Lookup file in the root(s) and returns first path it found or undef.
When roots are not set just checks if file exists.
_resolve_file( $file, @roots )
DEPRECATED. This private method is deprecated and do nothing useful
except maintaining backwards compatibility. If you were using it then
most probably to find files in roots before submitting them into
concatenate method. Now, it's not required and this method returns back
file path without changes.
resolve_uri( $uri_string, $base_file )
Takes an URI and base file path and transforms it into new file path.
BUGS AND SHORTCOMINGS
At the current time, comments are not skipped. This means comments
happening before @import statements at the top of a file will cause the
@import rules to not be parsed. Make sure the @import rules are the
very first thing in the file (and only one per line). Processing of
@import rules stops as soon as the first line that doesn't match an
@import rule is encountered.
All other bugs should be reported via
http://rt.cpan.org/Public/Dist/Display.html?Name=CSS-Squish
<http://rt.cpan.org/Public/Dist/Display.html?Name=CSS-Squish> or
bug-CSS-Squish@rt.cpan.org.
AUTHOR
Thomas Sibley <trs@bestpractical.com>, Ruslan Zakirov
<ruz@bestpractical.com>
COPYRIGHT AND LICENSE
Copyright (c) 2006.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, either Perl version 5.8.3 or, at
your option, any later version of Perl 5 you may have available.
perl v5.14.1 2010-11-05 CSS::Squish(3)
