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