-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
352 lines (323 loc) · 17.5 KB
/
index.html
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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
<!doctype html>
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title></title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="apple-touch-icon" href="apple-touch-icon.png">
<!-- Place favicon.ico in the root directory -->
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css" integrity="sha384-AysaV+vQoT3kOAXZkl02PThvDr8HYKPZhNT5h/CXfBThSRXQ6jW5DO2ekP5ViFdi" crossorigin="anonymous">
<link rel="stylesheet" href="css/main.css">
<script src="js/vendor/modernizr-2.8.3.min.js"></script>
</head>
<body>
<!--[if lt IE 8]>
<p class="browserupgrade">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> to improve your experience.</p>
<![endif]-->
<div class="header">
<h1>Facebook Instant Articles Transformer Debugger</h1>
Put your HTML into box 1, and your transform rules JSON into box 2, and press "Transform" to see what the <a href="https://github.com/facebook/facebook-instant-articles-sdk-php">Facebook Instant Articles SDK</a> will transform it to.<BR>
You can see the log debug output of the transformer as it walks your HTML tree and applies rules.
</div>
<div class="html-input">
<textarea>
<html>
<head>
<script type="text/javascript" href="http://domain.com/javascript.js" />
</head>
<body>
<div class="header">
<div class="title">
<h1>The article title</h1>
<h2>Sub Title</h2>
<span class="author">Author name</span>
</div>
<div class="hero-image">
<img src="http://domain.com/image.png" />
<div class="image-caption">
Some amazing moment captured by Photographer
</div>
</div>
</div>
<p>Lorem <b>ipsum</b> dolor sit amet, consectetur adipiscing elit. Sed eu arcu porta, ultrices massa ut, porttitor diam. Integer id auctor augue.</p>
<p>Vivamus mattis, sem id consequat dapibus, odio urna fermentum risus, in blandit dolor justo vel ex. Curabitur a neque bibendum, hendrerit sem in, congue lectus.</p>
<div class="image">
<img src="http://domain.com/image.png" />
<div class="image-caption">
Some amazing moment captured by Photographer
</div>
</div>
<p>Curabitur vulputate odio eu justo <i>venenatis</i>, a pretium orci placerat. Nam sed neque quis eros vestibulum mattis. Donec vitae mi egestas, laoreet massa et, fringilla libero.</p>
</body>
</html></textarea>
</div>
<div class="rules-input">
<input type="checkbox" checked="true" id="include-wp-default-rules" name="include-wp-default-rules" class=".include-wp-default-rules">
<label for="include-wp-default-rules">
Include <a href="https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json">Wordpress plugin pre-defined rules</a> as a base. <a href="#wp-default-rules-help">[?]</a>
</label>
</input>
<textarea>
{
"rules" :[
{
"class": "TextNodeRule"
},
{
"class": "PassThroughRule",
"selector" : "html"
},
{
"class": "PassThroughRule",
"selector" : "head"
},
{
"class": "PassThroughRule",
"selector" : "script"
},
{
"class": "PassThroughRule",
"selector" : "body"
},
{
"class": "ItalicRule",
"selector" : "i"
},
{
"class": "BoldRule",
"selector" : "b"
},
{
"class": "ParagraphRule",
"selector" : "p"
},
{
"class": "HeaderTitleRule",
"selector" : "div.title h1"
},
{
"class": "HeaderSubTitleRule",
"selector" : "div.title h2"
},
{
"class": "HeaderRule",
"selector" : "div.header"
},
{
"class": "AuthorRule",
"selector" : "span.author",
"properties" : {
"author.name" : {
"type" : "string",
"selector" : "span"
}
}
},
{
"class": "CaptionRule",
"selector" : "div.image-caption"
},
{
"class": "ImageRule",
"selector" : "div.image",
"properties" : {
"image.url" : {
"type" : "string",
"selector" : "img",
"attribute": "src"
},
"image.caption" : {
"type" : "element",
"selector" : "div.image-caption"
}
}
},
{
"class": "HeaderImageRule",
"selector" : "div.hero-image",
"properties" : {
"image.url" : {
"type" : "string",
"selector" : "img",
"attribute": "src"
},
"image.caption" : {
"type" : "element",
"selector" : "div.image-caption"
}
}
}
]
}
</textarea>
</div>
<div class="button-container">
<button class="run btn btn-primary">Transform</button>
</div>
Transformed HTML:
<div class="html-output">
<textarea readonly>Output HTML</textarea>
</div>
Parsed Rules:
<div class="rules-output">
<textarea readonly>Parsed Rules</textarea>
</div>
Transformer Log:
<div class="log-output">
<textarea readonly>Output Debug Logs</textarea>
</div>
Instant Article Object:
<div class="instant-article-object">
<textarea readonly>Instant Article Object</textarea>
</div>
<div class="faqs">
<h3>What Is This Tool?</h3>
<p>
This tool helps you to debug <a href="https://developers.facebook.com/docs/instant-articles/sdk/transformer">Facebook Instant Articles Transformers</a>.
</p>
<h3>What are Facebook Instant Articles?</h3>
<p>
On mobile, someone clicking the link to one of your articles that has been shared on Facebook
will normally open their browser and load your website. This can be slow.
</p>
<p>
<a href="https://instantarticles.fb.com/">Instant Articles</a> open instantly inside the Facebook app on mobile-
they can be displayed very quickly (they are partially pre-loaded), and with a consistent user interface.
The articles are stored by Facebook to allow this speed, which takes pressure off your web server
and this means the articles will continue to load even if your site goes down.
</p>
<p>
Google's and Apple's similar technologies are <a href="https://www.ampproject.org/">Accelerated Mobile Pages (AMP)</a> and <a href="https://developer.apple.com/news-publisher/">Apple News</a>.
</p>
<h3>Why do I need a Transformer?</h3>
<p>
Instant Articles support only a subset of HTML. So your regular articles, full of complex website display HTML, CSS and Javascript need to be transformed into the <a href="https://developers.facebook.com/docs/instant-articles/reference">elements Facebook understands</a>.
<a href="https://developers.facebook.com/docs/instant-articles/sdk/transformer">Transformers</a> are the way was the Facebook SDK provides to map from your existing articles' HTML to this subset language using <a href="https://developers.facebook.com/docs/instant-articles/sdk/transformer-rules">Transfomer Rules</a>.
</p>
<p>
eg. Instant Articles expect <figure> tags instead of <img> tags. To transform these tags you would use an <a href="https://developers.facebook.com/docs/instant-articles/sdk/transformer-rules#rule-classes-graphic">ImageRule</a> with a selector "img" and property "image.url": {"type" : "string", "selector" : "img", "attribute": "src"}, as seen in the demo rules in box2 above.
</p>
<h3>Can't I just use a plugin?</h3>
<p>
If you are using Wordpress, there is a plugin to automatically convert your articles using a "best guess"
set of <a href="https://github.com/Automattic/facebook-instant-articles-wp/blob/f2edb173c65fd8a74147f2254d7e0fc480db8d1c/rules-configuration.json">default rules</a>.
This should provide a "good enough" transformation for the majority of websites.
</p>
<p>
If you have custom elements in your page, you will need to create <a href="https://en-gb.wordpress.org/plugins/fb-instant-articles/faq/">Custom Transformer Rules</a>, which this tool helps you create & test.
</p>
<h3>How does Transformation work?</h3>
<p>
Your HTML is walked over, starting from the root element. Each element is compared to the list of rules
(in reverse order- so later rules will override earlier ones). In the debug output (box 4) above, you will see
each element being processed in turn, starting with at the <html> element, and proceeding down the tree.
</p>
<p>
If an element matches a rule, the rule will be applied, which usually results in a new element
being created in the output (eg. a BoldRule will create a <strong> element, or an
InteractiveRule will create an <iframe>).
</p>
<p>
If an element does not match any rule, it will be ignored, and removed from the output. If you want to continue to process its child elements, you should create a PassThroughRule.
</p>
<p>
At the end you are left with a HTML article that uses only the allowed subset of elements that can be submitted to Facebook Instant Articles for display (box 3).
</p>
<a name="wp-default-rules-help"></a>
<h3>What does the "Include WP pre-defined rules" checkbox do?</h3>
<p>
The Wordpress Plugin has a starting set of <a href="https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json">pre-defined rules</a> that transform common elements from wordpress HTML into HTML for Instant Articles.
If you have custom elements (or elements created by non-default WP plugins) in your page you use "Custom transformer rules" to transform these elements.
The plugin adds these custom rules <b>in addition to</b> the pre-defined rules.
The custom rules are added after the pre-defined rules so that you can extend or override them.
</p>
<p>
If you are using the WP Plugin, you should leave this box checked.
</p>
<p>
If you are not using Wordpress, you can uncheck it to start with no rules, and build your own ruleset from scratch.
</p>
<h3>I get an empty <article> tag in my output!</h3>
<p>
Before processing, your input HTML will be wrapped with <html> and <body> tags to make it valid HTML.
You will need rules to "Pass Through" the content of these tags in order for the transformer to transform your content:
</p>
<pre><code>{
"class": "PassThroughRule",
"selector" : "html"
},
{
"class": "PassThroughRule",
"selector" : "body"
}</code></pre>
<h3>Why did you create this tool?</h3>
<p>
I wanted to publish Instant Articles from a Wordpress website, but I had several custom elements in
my HTML templates which were not appearing in the instant articles, when transformed by the
<a href="https://en-gb.wordpress.org/plugins/fb-instant-articles/">Wordpress Instant Articles Plugin</a>.
The solution is to use <a href="https://en-gb.wordpress.org/plugins/fb-instant-articles/faq/">Custom Transformer Rules</a>
through the plugin, but because the plugin is not designed for advanced transforming (but rather to work out of the box for simple websites)
it is very slow to change the rules in plugin setup, edit & republish the article, then check on a phone to see if the change had any effect.
The plugin also provides very little debug logging or error messages, and often fails silenlty.
</p>
<p>
This tool is my attempt at creating a better workflow for developing custom transformer rules.
If you are using Wordpress, you can create your rules using this tool then copy and paste them into the
"Advanced Custom Transformer Rules" section of the plugin's setup.
</p>
<p>
The rules produced are not Wordpress specific. You can test / develop them here, then
<a href="https://github.com/Crashthatch/fb-instant-articles-debugger/blob/6404819b6cf113a1dfb3d5bc8bf71dfbf34ee3e3/transform.php#L61">use them as input</a> to the FB PHP SDK Transformer.
</p>
<h3>How do I debug further?</h3>
<p>
If you need more information than this tool provides, you can use the Facebook SDK locally to run your rules on your HTML using something like the script at the end of FB's <a href="https://developers.facebook.com/docs/instant-articles/sdk/transformer">transformer documentation</a> (which <a href="https://github.com/Crashthatch/fb-instant-articles-debugger/blob/master/transform.php">this tool</a> is based on).
<a href="https://github.com/Crashthatch/fb-instant-articles-debugger">Cloning this tool</a> and modifying transform.php to work as a CLI script might be a good starting point.
</p>
<p>
You can then step through it with your IDE's PHP debugger, add breakpoints, or add extra print statements into the <a href="https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/src/Facebook/InstantArticles/Transformer/Transformer.php">Transformer</a> or specific <a href="https://github.com/facebook/facebook-instant-articles-sdk-php/tree/master/src/Facebook/InstantArticles/Transformer/Rules">Rules</a> to identify exactly what is happening.
</p>
<h3>How can I get more help?</h3>
<p>
I offer consultancy services at a rate of $100 / hour. <a href="https://twitter.com/thomasfletcher">Contact Me</a>
</p>
<h3>How can I help?</h3>
<p>
If you found a bug that you would like to fix, or you would like to implement a new feature,
please <a href="https://github.com/Crashthatch/fb-instant-articles-debugger/issues">open a Github issue</a>,
and then make the modifications needed to the source code and submit a <a href="https://github.com/Crashthatch/fb-instant-articles-debugger/pulls">pull request</a>.
</p>
<h3>Disclaimer</h3>
<p>
I am not affiliated with Facebook in any way, and this is an unofficial tool that uses the
open-source <a href="https://github.com/facebook/facebook-instant-articles-sdk-php">Facebook Instant Articles SDK</a>.
I provide no support, guarantee of correctness or continued operation.
</p>
</div>
<footer>
<div class="footertext">
Created by <a href="https://twitter.com/thomasfletcher">@thomasfletcher</a> -
<a href="https://github.com/Crashthatch/fb-instant-articles-debugger">Github</a>
</div>
<div class="addthis_inline_share_toolbox"></div>
</footer>
<script src="https://code.jquery.com/jquery-1.12.0.min.js"></script>
<script>window.jQuery || document.write('<script src="js/vendor/jquery-1.12.0.min.js"><\/script>')</script>
<!--<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/js/bootstrap.min.js" integrity="sha384-BLiI7JTZm+JWlgKa0M0kGRpJbF2J8q+qreVrKBC47e3K6BW78kGLrCkeRX6I9RoK" crossorigin="anonymous"></script>-->
<script src="js/plugins.js"></script>
<script src="js/main.js"></script>
<!-- Go to www.addthis.com/dashboard to customize your tools -->
<script type="text/javascript" src="//s7.addthis.com/js/300/addthis_widget.js#pubid=ra-584afeef83da06b9"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-2714250-6', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>