README
1NAME
2 CSS::Inliner - Library for converting CSS <style> blocks to inline
3 styles.
4
5SYNOPSIS
6 use CSS::Inliner;
7
8 my $inliner = new CSS::Inliner();
9
10 $inliner->read_file({ filename => 'myfile.html' });
11
12 print $inliner->inlinify();
13
14DESCRIPTION
15 Library for converting CSS style blocks into inline styles in an HTML
16 document. Specifically this is intended for the ease of generating HTML
17 emails. This is useful as even in 2015 Gmail and Hotmail don't support
18 top level <style> declarations.
19
20METHODS
21 new
22 Instantiates the Inliner object. Sets up class variables that are used
23 during file parsing/processing. Possible options are:
24
25 html_tree - (optional) Pass in a fresh unparsed instance of
26 HTML::Treebuilder
27
28 NOTE: Any passed references to HTML::TreeBuilder will be substantially
29 altered by passing it in here...
30
31 strip_attrs - (optional) Remove all "id" and "class" attributes during
32 inlining
33
34 leave_style - (optional) Leave style/link tags alone within <head>
35 during inlining
36
37 relaxed - (optional) Relaxed HTML parsing which will attempt to
38 interpret non-HTML4 documents.
39
40 NOTE: This argument is not compatible with passing an html_tree.
41
42 agent - (optional) Pass in a string containing a preferred user-agent,
43 overrides the internal default provided by the module for handling
44 remote documents
45
46 fetch_file
47 Fetches a remote HTML file that supposedly contains both HTML and a
48 style declaration, properly tags the data with the proper charset as
49 provided by the remote webserver (if any). Subsequently calls the read
50 method automatically.
51
52 This method expands all relative urls, as well as fully expands the
53 stylesheet reference within the document.
54
55 This method requires you to pass in a params hash that contains a url
56 argument for the requested document. For example:
57
58 $self->fetch_file({ url => 'http://www.example.com' });
59
60 Note that you can specify a user-agent to override the default
61 user-agent of 'Mozilla/4.0' within the constructor. Doing so may avoid
62 certain issues with agent filtering related to quirky webserver configs.
63
64 Input Parameters: url - the desired url for a remote asset presumably
65 containing both html and css charset - (optional) programmer specified
66 charset for the pass url
67
68 read_file
69 Opens and reads an HTML file that supposedly contains both HTML and a
70 style declaration, properly tags the data with the proper charset if
71 specified. It subsequently calls the read() method automatically.
72
73 This method requires you to pass in a params hash that contains a
74 filename argument. For example:
75
76 $self->read_file({ filename => 'myfile.html' });
77
78 Additionally you can specify the character encoding within the file, for
79 example:
80
81 $self->read_file({ filename => 'myfile.html', charset => 'utf8' });
82
83 Input Parameters: filename - name of local file presumably containing
84 both html and css charset - (optional) programmer specified charset of
85 the passed file
86
87 read
88 Reads passed html data and parses it. The intermediate data is stored in
89 class variables.
90
91 The <style> block is ripped out of the html here, and stored separately.
92 Class/ID/Names used in the markup are left alone.
93
94 This method requires you to pass in a params hash that contains scalar
95 html data. For example:
96
97 $self->read({ html => $html });
98
99 NOTE: You are required to pass a properly encoded perl reference to the
100 html data. This method does *not* do the dirty work of encoding the html
101 as utf8 - do that before calling this method.
102
103 Input Parameters: html - scalar presumably containing both html and css
104 charset - (optional) scalar representing the original charset of the
105 passed html
106
107 detect_charset
108 Detect the charset of the passed content.
109
110 The algorithm present here is roughly based off of the HTML5 W3C working
111 group document, which lays out a recommendation for determining the
112 character set of a received document, which can be seen here under the
113 "determining the character encoding" section:
114 http://www.w3.org/TR/html5/syntax.html
115
116 NOTE: In the event that no charset can be identified the library will
117 handle the content as a mix of UTF-8/CP-1252/8859-1/ASCII by attempting
118 to use the Encoding::FixLatin module, as this combination is relatively
119 common in the wild. Finally, if Encoding::FixLatin is unavailable the
120 content will be treated as ASCII.
121
122 Input Parameters: content - scalar presumably containing both html and
123 css charset - (optional) programmer specified charset for the passed
124 content ctcharset - (optional) content-type specified charset for
125 content retrieved via a url
126
127 decode_characters
128 Implement the character decoding algorithm for HTML as outlined by the
129 various working groups
130
131 Basically apply best practices for determining the applied character
132 encoding and properly decode it
133
134 It is expected that this method will be called before any calls to
135 read()
136
137 Input Parameters: content - scalar presumably containing both html and
138 css charset - known charset for the passed content
139
140 inlinify
141 Processes the html data that was entered through either 'read' or
142 'read_file', returns a scalar that contains a composite chunk of html
143 that has inline styles instead of a top level <style> declaration.
144
145 query
146 Given a particular selector return back the applicable styles
147
148 specificity
149 Given a particular selector return back the associated selectivity
150
151 content_warnings
152 Return back any warnings thrown while inlining a given block of content.
153
154 Note: content warnings are initialized at inlining time, not at read
155 time. In order to receive back content feedback you must perform
156 inlinify first
157
158Sponsor
159 This code has been developed under sponsorship of MailerMailer LLC,
160 http://www.mailermailer.com/
161
162AUTHOR
163 Kevin Kamel <kamelkev@mailermailer.com>
164
165CONTRIBUTORS
166 Dave Gray <cpan@doesntsuck.com>
167 Vivek Khera <vivek@khera.org>
168 Michael Peters <wonko@cpan.org>
169 Chelsea Rio <chelseario@gmail.com>
170
171LICENSE
172 This module is Copyright 2015 Khera Communications, Inc. It is licensed
173 under the same terms as Perl itself.
174
175