1CSS::Squish(3)        User Contributed Perl Documentation       CSS::Squish(3)
2
3
4

NAME

6       CSS::Squish - Compact many CSS files into one big file
7

SYNOPSIS

9         use CSS::Squish;
10         my $concatenated = CSS::Squish->concatenate(@files);
11
12         my $squisher = CSS::Squish->new( roots => ['/root1', '/root2'] );
13         my $concatenated = $squisher->concatenate(@files);
14

DESCRIPTION

16       This module takes a list of CSS files and concatenates them, making
17       sure to honor any valid @import statements included in the files.
18
19       The benefit of this is that you get to keep your CSS as individual
20       files, but can serve it to users in one big file, saving the overhead
21       of possibly dozens of HTTP requests.
22
23       Following the CSS 2.1 spec, @import statements must be the first rules
24       in a CSS file.  Media-specific @import statements will be honored by
25       enclosing the included file in an @media rule.  This has the side
26       effect of actually improving compatibility in Internet Explorer, which
27       ignores media-specific @import rules but understands @media rules.
28
29       It is possible that future versions will include methods to compact
30       whitespace and other parts of the CSS itself, but this functionality is
31       not supported at the current time.
32

COMMON METHODS

34   new( [roots=>[...]] )
35       A constructor. For backward compatibility with versions prior to 0.06
36       you can still call everything as a class method, but should remember
37       that roots are shared between all callers in this case.
38
39       if you're using persistent environment (like mod_perl) then it's very
40       recomended to use objects.
41
42   concatenate( @files )
43       Takes a list of files to concatenate and returns the results as one big
44       scalar.
45
46   concatenate_to( $dest, @files )
47       Takes a filehandle to print to and a list of files to concatenate.
48       "concatenate" uses this method with an "open"ed scalar.
49

RESOLVING METHODS

51       The following methods help map URIs to files and find them on the disk.
52
53       In common situation you control CSS and can adopt it to use imports
54       with relative URIs and most probably only have to set root(s).
55
56       However, you can subclass these methods to parse css files before
57       submitting, implement advanced mapping of URIs to file system and other
58       things.
59
60       Mapping works in the following way. When you call concatenate method we
61       get content of file using file_handle method which as well lookup files
62       in roots.  If roots are not defined then files are treated as absolute
63       paths or relative to the current directory. Using of absolute paths is
64       not recommended as unhide server dirrectory layout to clients in css
65       comments and as well don't allow to handle @import commands with
66       absolute URIs. When files is found we parse its content for @import
67       commands. On each URI we call resolve_uri method that convert absolute
68       and relative URIs into file paths.
69
70       Here is example of processing:
71
72           roots: /www/overlay/, /www/shared/
73
74           $squisher->concatenate('/css/main.css');
75
76           ->file_handle('/css/main.css');
77               ->resolve_file('/css/main.css');
78               <- '/www/shared/css/main.css';
79           <- handle;
80
81           content parsing
82           find '@import url(nav.css)'
83           -> resolve_uri('nav.css', '/css/main.css');
84           <- '/css/nav.css';
85               ... recursivly process file
86           find '@import url(/css/another.css)'
87           -> resolve_uri('/css/another.css', '/css/main.css');
88           <- '/css/another.css'
89           ...
90
91   roots( @dirs )
92       A getter/setter for paths to search when looking for files.
93
94       The paths specified here are searched for files. This is useful if your
95       server has multiple document roots or document root doesn't match the
96       current dir.
97
98       See also 'resolve_file' below.
99
100   file_handle( $file )
101       Takes a path to a file, resolves (see resolve_file) it and returns a
102       handle.
103
104       Returns undef if file couldn't be resolved or it's impossible to open
105       file.
106
107       You can subclass it to filter content, process it with templating
108       system or generate it on the fly:
109
110           package My::CSS::Squish;
111           use base qw(CSS::Squish);
112
113           sub file_handle {
114               my $self = shift;
115               my $file = shift;
116
117               my $content = $self->my_prepare_content($file);
118               return undef unless defined $content;
119
120               open my $fh, "<", \$content or warn "Couldn't open handle: $!";
121               return $fh;
122           }
123
124       Note that the file is not resolved yet and is relative to the root(s),
125       so you have to resolve it yourself or call resolve_file method.
126
127   resolve_file( $file )
128       Lookup file in the root(s) and returns first path it found or undef.
129
130       When roots are not set just checks if file exists.
131
132   _resolve_file( $file, @roots )
133       DEPRECATED. This private method is deprecated and do nothing useful
134       except maintaining backwards compatibility. If you were using it then
135       most probably to find files in roots before submitting them into
136       concatenate method. Now, it's not required and this method returns back
137       file path without changes.
138
139   resolve_uri( $uri_string, $base_file )
140       Takes an URI and base file path and transforms it into new file path.
141

BUGS AND SHORTCOMINGS

143       At the current time, comments are not skipped.  This means comments
144       happening before @import statements at the top of a file will cause the
145       @import rules to not be parsed.  Make sure the @import rules are the
146       very first thing in the file (and only one per line).  Processing of
147       @import rules stops as soon as the first line that doesn't match an
148       @import rule is encountered.
149
150       All other bugs should be reported via
151       <http://rt.cpan.org/Public/Dist/Display.html?Name=CSS-Squish> or
152       bug-CSS-Squish@rt.cpan.org.
153

AUTHOR

155       Thomas Sibley <trs@bestpractical.com>, Ruslan Zakirov
156       <ruz@bestpractical.com>
157
159       Copyright (c) 2006.
160
161       This library is free software; you can redistribute it and/or modify it
162       under the same terms as Perl itself, either Perl version 5.8.3 or, at
163       your option, any later version of Perl 5 you may have available.
164
165
166
167perl v5.36.0                      2023-01-20                    CSS::Squish(3)
Impressum