This repository has been archived by the owner on Feb 21, 2023. It is now read-only.
/
index.html
293 lines (244 loc) · 24.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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Embedded buttons - Flattr Developers</title>
<link rel="stylesheet" href="/styles/base.css">
<link rel="stylesheet" href="/styles/custom.css">
<link rel="stylesheet" href="/styles/syntax.css">
<link rel="shortcut icon" href="/favicon.ico">
</head>
<body>
<div class="container">
<h1><a href="/">Flattr Developer Platform</a></h1>
<ul class="nav">
<li>
<a href="/api">REST API</a>
<ul>
<li>
<span>Resources</span>
<ul>
<li><a href="/api/resources/flattrs">Flattrs</a></li>
<li><a href="/api/resources/things">Things</a></li>
<li><a href="/api/resources/users">Users</a></li>
<li><a href="/api/resources/activities">Activities</a></li>
<li><a href="/api/resources/categories">Categories</a></li>
<li><a href="/api/resources/languages">Languages</a></li>
</ul>
</li>
<li><a href="http://console.apihq.com/api/flattr" target="_blank">Console</a></li>
<li><a href="/api/changelog">Changelog</a></li>
<li><a href="/api/libraries">Clients</a></li>
<li><a href="/api/policy">Policy</a></li>
</ul>
</li>
<li><a href="/button">Embedded buttons</a></li>
<li><a href="/auto-submit">Auto-submit URL</a></li>
<li><a href="/feed">Flattr in feeds and HTML</a></li>
<li><a href="/partner">Partner site integration</a></li>
<li><a href="/tools">Tools</a></li>
<li><a href="/api/questions">Questions</a></li>
</ul>
<div class="page">
<div class="header">
<h2>Embedded buttons</h2>
<div class="subtitle"></div>
</div>
<h3 id="introduction">Introduction</h3>
<blockquote>
<p>Important: The target audience of this document is mainly site builders, web masters and developers. We assume that you at the very least have moderate knowledge of HTML.</p>
</blockquote>
<p>The embedded button has two main uses. To load buttons for previously submitted things and to allow automatic submission (autosubmit from now on) of new things. The latter is very useful for web sites that may contain several pages, for example blogs.</p>
<p>There is two ways of defining a button in your code. One using HTML and another using JavaScript. Common for both of them is that the embedded button only has to be loaded once and that it is loaded asynchronously.</p>
<h3 id="the-loader">The Loader</h3>
<p>The first step of in using the embedded button is loading it. The url to the javascript is <code>http://api.flattr.com/js/0.6/load.js</code>. The embed script is loaded by placing the following call in the <code><head></code> tag of you HTML document:</p>
<div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></span>
<span class="cm">/* <![CDATA[ */</span>
<span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">s</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">createElement</span><span class="p">(</span><span class="s1">'script'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">t</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementsByTagName</span><span class="p">(</span><span class="s1">'script'</span><span class="p">)[</span><span class="mi">0</span><span class="p">];</span>
<span class="nx">s</span><span class="p">.</span><span class="nx">type</span> <span class="o">=</span> <span class="s1">'text/javascript'</span><span class="p">;</span>
<span class="nx">s</span><span class="p">.</span><span class="nx">async</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
<span class="nx">s</span><span class="p">.</span><span class="nx">src</span> <span class="o">=</span> <span class="s1">'//api.flattr.com/js/0.6/load.js?mode=auto'</span><span class="p">;</span>
<span class="nx">t</span><span class="p">.</span><span class="nx">parentNode</span><span class="p">.</span><span class="nx">insertBefore</span><span class="p">(</span><span class="nx">s</span><span class="p">,</span> <span class="nx">t</span><span class="p">);</span>
<span class="p">})();</span>
<span class="cm">/* ]]> */</span>
<span class="nt"></script></span>
</pre>
</div>
<p>A closer look at the url in the above example reveals that the url has a query string part to it. The embedded button loader supports adding optional parameters to the url which makes Flattr integration easier. In the above example we use the mode parameter to tell the loader to look for button definitions in the HTML source.</p>
<p><strong>Options</strong></p>
<p>For convenience we've also added a few query string parameters to set default parameters on all buttons.</p>
<ul>
<li><strong>mode</strong> - auto | manual(default)</li>
<li><strong>https</strong> - 1 | 0 (defaults to the schema of load.js)</li>
<li><strong>popout</strong> - 1 | 0 (show popout when hovering mouse over button)</li>
<li><strong>uid</strong> - username</li>
<li><strong>button</strong> - compact | default</li>
<li><strong>language</strong> - can be set to any of the available languages</li>
<li><strong>category</strong> - Can be set to any of the available categories</li>
<li><strong>html5-key-prefix</strong> - a string that must start with 'data-'</li>
</ul>
<p>The parameters <code>uid</code>, <code>button</code>, <code>language</code> and <code>category</code> can be used to set a default that will be used for your buttons unless they override the setting. The most useful of those being <code>uid</code>.</p>
<p><strong>Mode</strong> is used to alter the way buttons are loaded. The default mode is <code>manual</code>, meaning that the user will have to initialize the API themselves through calling <code>setup()</code> (for more information see <a href="#manual-mode">manual mode</a>). If the mode is set to <code>auto</code>, the embedded button script will search for button definitions in HTML as soon as the document is fully loaded (<code>onload</code>), removing the need to call <code>setup()</code>. This <strong>mode</strong> is the one used in the examples below, therefor we won't explain it further here.</p>
<p>As you've probably already figured out, the button can be loaded using HTTPS.
By default all buttons will be loaded with the same schema ( http or https ) as <code>load.js</code>.
In other words if you want to use HTTPS buttons then load <code>load.js</code> using HTTPS. If this doesn't work or you want to load the embedded button script using HTTP for whatever reason, you can set the query string parameter <code>https</code> to <code>1</code>.</p>
<p>In version 0.6 support for html5 custom data attributes was added. By default the embedded button script will look for data attributes starting with <code>data-flattr</code>. The parameter <code>html5-key-prefix</code> allows you to specify a custom prefix to use instead. Example: <code>&html5-key-prefix=data-fvar</code></p>
<p>Note that the query string parameters are added to the <code>load.js</code> url and not to your individual buttons.</p>
<h5 >Example</h5><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></span>
<span class="cm">/* <![CDATA[ */</span>
<span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">s</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">createElement</span><span class="p">(</span><span class="s1">'script'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">t</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementsByTagName</span><span class="p">(</span><span class="s1">'script'</span><span class="p">)[</span><span class="mi">0</span><span class="p">];</span>
<span class="nx">s</span><span class="p">.</span><span class="nx">type</span> <span class="o">=</span> <span class="s1">'text/javascript'</span><span class="p">;</span>
<span class="nx">s</span><span class="p">.</span><span class="nx">async</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
<span class="nx">s</span><span class="p">.</span><span class="nx">src</span> <span class="o">=</span> <span class="s1">'//api.flattr.com/js/0.6/load.js?'</span><span class="o">+</span>
<span class="s1">'mode=auto&uid=gargamel&language=sv_SE&category=text'</span><span class="p">;</span>
<span class="nx">t</span><span class="p">.</span><span class="nx">parentNode</span><span class="p">.</span><span class="nx">insertBefore</span><span class="p">(</span><span class="nx">s</span><span class="p">,</span> <span class="nx">t</span><span class="p">);</span>
<span class="p">})();</span>
<span class="cm">/* ]]> */</span>
<span class="nt"></script></span>
</pre>
</div>
<p>Loading the script asynchronously is great but without adding buttons it's no fun, so lets move on...</p>
<h3 id="adding-buttons">Adding buttons</h3>
<p>A button is basically made up of a set of configuration instructions that tells the embedded button script how it should be display. There are a few different ways of defining the buttons, but the parameters required are common to them all.</p>
<p>The parameters are a set of key value pairs. Some of them are required, others are optional. The parameters are listed here in order of importance: </p>
<ul>
<li><p><strong>url</strong> ( Always required ) - Each thing on Flattr requires a unique URL. All parts of the URL, including the both the parameters and fragments, are used to distinguish the difference between submitted URLs.</p></li>
<li><p><strong>uid</strong> ( Required when autosubmit, otherwise optional ) - A Flattr username. This is a required parameter for autosubmit but not for things that are already on flattr.com.</p></li>
<li><p><strong>title</strong> ( Required when autosubmit, otherwise optional ) - Will be used to describe your thing on Fattr. The <code>title</code> should be between 5-100 characters. All HTML is stripped.</p></li>
<li><p><strong>description</strong> ( Required when autosubmit, otherwise optional ) - Will be used to describe your thing. The <code>description</code> should be between 5-1000 characters. All HTML is stripped except the <code><br\></code> character which will be converted into newlines (<code>\n</code>).</p></li>
<li><p><strong>category</strong> ( Required when autosubmit, otherwise optional ) - This parameter is used to sort things on Flattr and has no impact on the functionality of your button. It's value must be one of the <a href="https://api.flattr.com/rest/v2/categories.txt">available categories</a>.</p></li>
<li><p><strong>language</strong> ( Optional ) - Specifies which language your thing is in. Specifying the language will allow visitors on Flattr to filter through the large amount of things and get a personalized feed of items in their selected languages. The value must be a language code from the <a href="https://api.flattr.com/rest/v2/languages.txt">available languages</a>. Note that even tho this parameter is optional, a language will be guessed and added automatically if it is omitted.</p></li>
<li><p><strong>tags</strong> ( Optional) - This parameter allows you to add tags that can be used to describe your thing. This is used on Flattr to allow further filtering and sorting of things. Multiple tags are seperated by a comma <code>,</code>. Using non alpha characters in tags are not supported nor is using a comma for obvious reasons.</p></li>
<li><p><strong>button</strong> ( Optional ) - We also provide a compact version of our Flattr button. This parameter tells the embedded button script which button layout to use. Set this parameter to <code>compact</code> if you want the compact button. Don't set the parameter at all if you are fine with the normal button.</p></li>
<li><p><strong>popout</strong> ( Optional ) - Set this parameter to <code>0</code> to disable the popout that appears when hovering the mouse cursor over the button.</p></li>
<li><p><strong>hidden</strong> ( Optional ) - Not all content is suitable for public listing. If you for one reason or another don't want your content to be listed on Flattr set this parameter to <code>1</code>.</p></li>
</ul>
<h3 id="defining-the-button-with-html">Defining the button with HTML</h3>
<p>The easiest way of using the embedded button script is by defining buttons through HTML. The HTML definition is easy to add and requires no knowledge of JavaScript since it's syntax is made up of basic HTML code.</p>
<p>Adding, or as we say defining, a button is done like this.</p>
<div class="highlight"><pre><span class="nt"><a</span> <span class="na">class=</span><span class="s">"FlattrButton"</span> <span class="na">href=</span><span class="s">"[URL]"</span> <span class="na">title=</span><span class="s">"[title]"</span> <span class="na">lang=</span><span class="s">"[language]"</span><span class="nt">></span>
[description]
<span class="nt"></a></span>
</pre>
</div>
<p>Where the text within <code>[ ]</code> (square brackets) should be replaced by their actual values.</p>
<p>Note that the attributes on the anchor tag in the above example are basic HTML attributes. There are additional parameters that we need to define our buttons, but we can't just add them to the anchor tag because then the code would no longer be valid HTML. We solve this by placing our parameters inside the <code>rel</code> attribute.</p>
<p>The <code>rel</code> attribute value must begin with "flattr;", this is the flattr identifier telling our loader to look for parameters inside the attribute value. Parameters in the <code>rel</code> attribute are defined through key value pairs, using CSS syntax. Example: <code>language:en_GB;</code></p>
<h5 >Example</h5><div class="highlight"><pre><span class="nt"><a</span> <span class="na">class=</span><span class="s">"FlattrButton"</span> <span class="na">style=</span><span class="s">"display:none;"</span>
<span class="na">title=</span><span class="s">"This is my title"</span>
<span class="na">rel=</span><span class="s">"flattr;uid:mario;category:text;tags:tag,tag2,tag3;"</span>
<span class="na">href=</span><span class="s">"http://wp.local/?p=444"</span><span class="nt">></span>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Lorem ipsum dolor sit amet, consectetur adipiscing
Maecenas aliquet aliquam leo quis fringilla.
<span class="nt"></a></span>
</pre>
</div>
<h4 id="html5">HTML5</h4>
<p>In HTML5 using the <code>rel</code> attribute is no longer possible. Instead we'll take advantage of a new feature in HTML5, custom data attributes. Unlike when using <code>rel</code> each parameter will be defined as a separate attribute where the attribute name is the parameter name prefixed with <code>data-flattr</code>. The attribute prefix can be changed using the query string parameter <code>html5-key-prefix</code>.</p>
<div class="highlight"><pre><span class="nt"><a</span> <span class="na">class=</span><span class="s">"FlattrButton"</span> <span class="na">style=</span><span class="s">"display:none;"</span>
<span class="na">title=</span><span class="s">"This is my title"</span>
<span class="na">data-flattr-uid=</span><span class="s">"flattr"</span>
<span class="na">data-flattr-tags=</span><span class="s">"text, opensource"</span>
<span class="na">data-flattr-category=</span><span class="s">"text"</span>
<span class="na">href=</span><span class="s">"http://wp.local/?p=444"</span><span class="nt">></span>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Lorem ipsum dolor sit amet, consectetur adipiscing
Maecenas aliquet aliquam leo quis fringilla.
<span class="nt"></a></span>
</pre>
</div>
<p>To avoid that the embedded button definition is shown while the page is loading we can either set the css class <code>FlattrButton</code> to be hidden in a stylesheet or add <code>style="display:none;"</code> to the a tag. In the example above we did the latter.</p>
<p>Note that you can add multiple buttons on your page. It's just a matter of adding another definition.</p>
<h4 id="manual-mode">Manual mode</h4>
<p>Manual mode is required when using JavaScript to define the buttons. But manual mode might also be useful in other cases. If you want to trigger the embedded button rendering manually all you need to do is call <code>FlattrLoader.setup()</code>.</p>
<h5 >Example</h5><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></span>
<span class="cm">/* <![CDATA[ */</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">onload</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(){</span>
<span class="nx">doSomeCoolStuffBeforeWeLoadTheFlattrButtons</span><span class="p">();</span>
<span class="nx">FlattrLoader</span><span class="p">.</span><span class="nx">setup</span><span class="p">();</span>
<span class="p">}</span>
<span class="cm">/* ]]> */</span>
<span class="nt"></script></span>
</pre>
</div>
<h4 id="defining-the-button-with-javascript">Defining the button with JavaScript</h4>
<p>Some people have more complex needs. We try to cater to developers using this alternative way of defining a Flattr button. Do not use this unless you are tech savvy and or comfortable with JavaScript.</p>
<p>Note that this will only work when the embedded button script is loaded in manual mode.</p>
<div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></span>
<span class="cm">/* <![CDATA[ */</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">onload</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">FlattrLoader</span><span class="p">.</span><span class="nx">render</span><span class="p">([</span><span class="nx">button</span> <span class="nx">parameters</span><span class="p">],</span> <span class="p">[</span><span class="nx">target</span><span class="p">],</span> <span class="p">[</span><span class="nx">insert</span> <span class="nx">method</span><span class="p">]);</span>
<span class="p">};</span>
<span class="cm">/* ]]> */</span>
<span class="nt"></script></span>
</pre>
</div>
<p>The <code>[button parameters]</code> are defined as a javascript object where the object property is the key. See the parameter list in the section Adding buttons above for valid keys.
In addition to the before mentioned parameters you can also use these:</p>
<ul>
<li><strong>url</strong> - URL to thing starting with <code>http://</code> or <code>https://</code></li>
<li><strong>title</strong> - Title of thing</li>
<li><strong>description</strong> - Description for thing max 1000 characters, HTML will be stripped</li>
</ul>
<p>Note that values should be escaped so that they don't break JS syntax.</p>
<p>Note that while <code>url</code>, <code>title</code> and <code>description</code> can also be used in the <code>rel</code> attribute (see <a href="#defining-the-button-with-html">html definition</a> ), their intended and recommended use is for the javascript implementations.</p>
<p><code>[target]</code> is either a DOM element or an ID of an tag. <code>[insert method]</code> is one of <code>append</code>, <code>before</code> or <code>replace</code>.</p>
<h5 >Example implementation</h5><div class="highlight"><pre><span class="nt"><html></span>
<span class="nt"><head></span>
<span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></span>
<span class="cm">/* <![CDATA[ */</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">onload</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">FlattrLoader</span><span class="p">.</span><span class="nx">render</span><span class="p">({</span>
<span class="s1">'uid'</span><span class="o">:</span> <span class="s1">'flattr'</span><span class="p">,</span>
<span class="s1">'url'</span><span class="o">:</span> <span class="s1">'http://wp.local'</span><span class="p">,</span>
<span class="s1">'title'</span><span class="o">:</span> <span class="s1">'Title of the thing'</span><span class="p">,</span>
<span class="s1">'description'</span><span class="o">:</span> <span class="s1">'Description of the thing'</span>
<span class="p">},</span> <span class="s1">'element_id'</span><span class="p">,</span> <span class="s1">'replace'</span><span class="p">);</span>
<span class="p">}</span>
<span class="cm">/* ]]> */</span>
<span class="nt"></script></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><div</span> <span class="na">id=</span><span class="s">"element_id"</span><span class="nt">></div></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</pre>
</div>
<h3 id="multiple-onload-events">Multiple onload events</h3>
<p>If you have an advanced website chances are that you are already using a JavaScript that is triggered by the documents <code>onload</code> event.
In the examples above the examples adding the scripts to the <code>onload</code> event using
<code>window.onload</code>. The downside to this is that is can only keep one function at a time, so if I add two different functions to <code>onload</code> the latter overwrites the first.</p>
<p>If you are using <a href="http://jquery.com">jQuery</a>, <a href="http://prototypejs.org/">prototype</a> or another javascript lib then you can use their event handlers to get around this. If not then <code>load.js</code> comes with it's own method. It is not as advanced as that of a full fledged javascript lib but it should get the job done for those of you with simpler needs.</p>
<p>The method is called <code>FlattrLoader.addLoadEvent()</code> and it takes one parameter, a function to be run <code>onload</code>.</p>
<div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">></span>
<span class="cm">/* <![CDATA[ */</span>
<span class="nx">FlattrLoader</span><span class="p">.</span><span class="nx">addLoadEvent</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">alert</span><span class="p">(</span><span class="s1">'Hello world!'</span><span class="p">);</span>
<span class="p">});</span>
<span class="cm">/* ]]> */</span>
<span class="nt"></script></span>
</pre>
</div>
<h3 id="browser-support">Browser support</h3>
<p>The buttons should support all modern browsers like the latest version of Firefox, Safari and Chrome and also Internet Explorer 8 and newer. It will degrade nicely in older browsers like Internet Explorer 7 – it will just not show.</p>
</div>
<address>Visit <a href="http://flattr.com/">Flattr.com</a> to learn more about Flattr.</address>
</div>
<script src="/js/ender.js"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-13236450-6']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>