1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
2 |
"http://www.w3.org/TR/html4/strict.dtd"> |
3 |
<html> |
4 |
<head> |
5 |
<title>Reblog Plug-ins</title> |
6 |
<link rel="stylesheet" href="softwarestyle.css" type="text/css"> |
7 |
<style type="text/css" title="text/css"> |
8 |
<!-- |
9 |
|
10 |
dl.methods dt |
11 |
{ |
12 |
clear: left; |
13 |
} |
14 |
|
15 |
dl dt |
16 |
{ |
17 |
font-weight: bold; |
18 |
font-family: helvetica, sans-serif; |
19 |
} |
20 |
|
21 |
dl.methods dd |
22 |
{ |
23 |
margin-bottom: 2em; |
24 |
} |
25 |
|
26 |
dl.methods dd p.arguments-head |
27 |
{ |
28 |
float: left; |
29 |
width: 2em; |
30 |
margin-top: 0; |
31 |
} |
32 |
|
33 |
dl.methods dd ol.arguments |
34 |
{ |
35 |
margin-left: 2em; |
36 |
} |
37 |
|
38 |
--> |
39 |
</style> |
40 |
</head> |
41 |
<body> |
42 |
<h1>Reblog API</h1> |
43 |
<p>$Revision: 1.3 $</p> |
44 |
<div id="toc"> |
45 |
<h2>Table of Contents</h2> |
46 |
<ul> |
47 |
<li> |
48 |
<a href="#overview">Overview</a> |
49 |
</li> |
50 |
<li> |
51 |
<a href="#using">Using the API</a> |
52 |
<ul> |
53 |
<li><a href="#servercomm">Refeed.ServerComm</a></li> |
54 |
<li><a href="#jsonrpc">JSON-RPC</a></li> |
55 |
</ul> |
56 |
</li> |
57 |
<li> |
58 |
<a href="#extending">Extending the API</a> |
59 |
</li> |
60 |
<li> |
61 |
<a href="#builtin-dictionary">Method Dictionary</a> |
62 |
<ul> |
63 |
<li><a href="#method-feedPublishFormHTML">feedPublishFormHTML</a></li> |
64 |
<li><a href="#method-feedSubscriptionFormHTML">feedSubscriptionFormHTML</a></li> |
65 |
<li><a href="#method-feedTagsFormHTML">feedTagsFormHTML</a></li> |
66 |
<li><a href="#method-itemBodyHTML">itemBodyHTML</a></li> |
67 |
<li><a href="#method-itemCommentFormHTML">itemCommentFormHTML</a></li> |
68 |
<li><a href="#method-itemEditFormHTML">itemEditFormHTML</a></li> |
69 |
<li><a href="#method-itemHeadHTML">itemHeadHTML</a></li> |
70 |
<li><a href="#method-markFeedPublished">markFeedPublished</a></li> |
71 |
<li><a href="#method-markFeedRead">markFeedRead</a></li> |
72 |
<li><a href="#method-markFeedUnpublished">markFeedUnpublished</a></li> |
73 |
<li><a href="#method-markFeedUnread">markFeedUnread</a></li> |
74 |
<li><a href="#method-markItemPublished">markItemPublished</a></li> |
75 |
<li><a href="#method-markItemRead">markItemRead</a></li> |
76 |
<li><a href="#method-markItemsPublished">markItemsPublished</a></li> |
77 |
<li><a href="#method-markItemsRead">markItemsRead</a></li> |
78 |
<li><a href="#method-markItemsUnread">markItemsUnread</a></li> |
79 |
<li><a href="#method-markItemUnpublished">markItemUnpublished</a></li> |
80 |
<li><a href="#method-markItemUnread">markItemUnread</a></li> |
81 |
<li><a href="#method-postItem">postItem</a></li> |
82 |
<li><a href="#method-setFeedTags">setFeedTags</a></li> |
83 |
<li><a href="#method-setItemCommentTags">setItemCommentTags</a></li> |
84 |
<li><a href="#method-setItemLink">setItemLink</a></li> |
85 |
<li><a href="#method-setItemTags">setItemTags</a></li> |
86 |
<li><a href="#method-setItemTitleContentLink">setItemTitleContentLink</a></li> |
87 |
<li><a href="#method-setKeyboardUse">setKeyboardUse</a></li> |
88 |
</ul> |
89 |
</li> |
90 |
<li> |
91 |
<a href="#license">License</a> |
92 |
</li> |
93 |
</ul> |
94 |
</div> |
95 |
<div id="contents"> |
96 |
<h2><a name="overview"></a>Overview</h2> |
97 |
<p> |
98 |
Reblog provides a client JSON-RPC API, written to support |
99 |
AJAX-style interactions in the default interface. The API |
100 |
may be extended by plug-ins. |
101 |
</p> |
102 |
<p> |
103 |
JSON (JavaScript Object Notation) is a lightweight |
104 |
data-interchange format. It is easy for humans to read and |
105 |
write. It is easy for machines to parse and generate. It is |
106 |
based on a subset of the JavaScript Programming Language, |
107 |
Standard ECMA-262 3rd Edition - December 1999. This feature |
108 |
can also be found in Python. JSON is a text format that is |
109 |
completely language independent but uses conventions that |
110 |
are familiar to programmers of the C-family of languages, |
111 |
including C, C++, C#, Java, JavaScript, Perl, TCL, and many |
112 |
others. These properties make JSON an ideal data-interchange |
113 |
language. |
114 |
</p> |
115 |
<p> |
116 |
More information about JSON and JSON-RPC is available at |
117 |
<a href="http://json.org">json.org</a> and |
118 |
<a href="http://json-rpc.org">json-rpc.org</a>. |
119 |
</p> |
120 |
<h2><a name="using"></a>Using the API</h2> |
121 |
<h3><a name="servercomm"></a>Refeed.ServerComm</h3> |
122 |
<p> |
123 |
Reblog provides the javascript class <code>Refeed.ServerComm</code> |
124 |
to implement basic JSON-RPC interactions, defined in |
125 |
<code><a href="script/comm.js">comm.js</a></code>. |
126 |
The value <code>Refeed.ServerComm.callHREF</code> must be defined prior to |
127 |
using <code>Refeed.ServerComm.remoteCall()</code> to invoke |
128 |
server-side methods. By default, <code>Refeed.ServerComm.callHREF</code> |
129 |
is set to <code><a href="call.php">call.php</a></code>. |
130 |
</p> |
131 |
<p> |
132 |
<code>Refeed.ServerComm.remoteCall()</code> accepts four arguments: |
133 |
</p> |
134 |
<ol> |
135 |
<li> |
136 |
<p> |
137 |
<strong>String: method name</strong><br /> |
138 |
Name of remote method to call. |
139 |
</p> |
140 |
</li> |
141 |
<li> |
142 |
<p> |
143 |
<strong>Array: parameters</strong><br /> |
144 |
Parameters to remote method. These may be values of any type, |
145 |
including objects, <code>NULL</code>, and arrays. |
146 |
</p> |
147 |
<p> |
148 |
For methods that accept <code class="class">RF_Item</code>s and |
149 |
<code class="class">RF_Feed</code>s, JSON-RPC class-hinting is |
150 |
used. For example, a feed with id 3 would be passed as: |
151 |
</p> |
152 |
<blockquote> |
153 |
<code>{"jsonclass": ["RF_Feed", [{"id": 3}]]}</code>. |
154 |
</blockquote> |
155 |
<p> |
156 |
Javascript <code>Refeed.Feed</code> and <code>Refeed.Item</code> |
157 |
objects (see <code><a href="script/feed.js">feed.js</a></code>, |
158 |
<code><a href="script/item.js">item.js</a></code>) |
159 |
classes provide a <code>toClassHint()</code> method to |
160 |
generate these representations. |
161 |
</p> |
162 |
</li> |
163 |
<li> |
164 |
<p> |
165 |
<strong>Function: on-result</strong><br /> |
166 |
Javascript function object, called with response |
167 |
<code>result</code> value if defined, and no |
168 |
<code>error</code> is present. |
169 |
</p> |
170 |
</li> |
171 |
<li> |
172 |
<p> |
173 |
<strong>Function: on-error</strong><br /> |
174 |
Javascript function object, called with response |
175 |
<code>error</code> value if defined, and no |
176 |
<code>result</code> is present. |
177 |
</p> |
178 |
</li> |
179 |
</ol> |
180 |
<p> |
181 |
Methods calls are <strong>asynchronous</strong>, so no value is |
182 |
returned by <code>Refeed.ServerComm.remoteCall()</code>. |
183 |
</p> |
184 |
<p> |
185 |
The <code>id</code> value specified in <a href="#jsonrpc">JSON-RPC</a> |
186 |
(see below) is intended to correlate requests and responses, but it |
187 |
is unused by <code>Refeed.ServerComm</code> since Javascript closures |
188 |
and the callback function parameters fulfill the same requirement |
189 |
more effectively. |
190 |
</p> |
191 |
<h3><a name="jsonrpc"></a>JSON-RPC</h3> |
192 |
<p> |
193 |
JSON-RPC is a minimal remote procedure protocol defined in the |
194 |
JSON format. A detailed specification is provided at |
195 |
<a href="http://json-rpc.org">json-rpc.org</a>. |
196 |
</p> |
197 |
<p> |
198 |
Methods are called via HTTP POST requests to the JSON-RPC endpoint, |
199 |
located at <code><a href="call.php">call.php</a></code> by default. |
200 |
This is an example method call, analogous to <code>foo("bar", "baz")</code>: |
201 |
</p> |
202 |
<blockquote> |
203 |
<code> |
204 |
POST /call.php HTTP/1.1<br /> |
205 |
<br /> |
206 |
{"method":"foo","params":["bar","baz"],"id":0} |
207 |
</code> |
208 |
</blockquote> |
209 |
<p> |
210 |
An example response: |
211 |
</p> |
212 |
<blockquote> |
213 |
<code> |
214 |
HTTP/1.1 200 OK<br /> |
215 |
Content-Type: application/x-json-rpc<br /> |
216 |
<br /> |
217 |
{"result":"bar-baz","error":null,"id":0} |
218 |
</code> |
219 |
</blockquote> |
220 |
<p> |
221 |
Another example response, where an error has occurred: |
222 |
</p> |
223 |
<blockquote> |
224 |
<code> |
225 |
HTTP/1.1 200 OK<br /> |
226 |
Content-Type: application/x-json-rpc<br /> |
227 |
<br /> |
228 |
{"result":null,"error":"Something went horribly awry.","id":0} |
229 |
</code> |
230 |
</blockquote> |
231 |
<h2><a name="extending"></a>Extending the API</h2> |
232 |
<p> |
233 |
Please see the <a href="plugins/README.html">plug-ins documentation</a> |
234 |
for details on <a href="plugins/README.html#writing">writing plug-ins</a> and |
235 |
<a href="plugins/README.html#writing-instantiationinvokation">defining remote methods</a>. |
236 |
</p> |
237 |
<h2><a name="builtin-dictionary"></a>Method Dictionary</h2> |
238 |
<dl class="methods"> |
239 |
<dt><a name="method-feedPublishFormHTML"></a>feedPublishFormHTML</dt> |
240 |
<dd> |
241 |
<p>Retrieve feed publish form HTML</p> |
242 |
<p class="arguments-head">Args:</p> |
243 |
<ol class="arguments"> |
244 |
<li><code class="class">RF_Feed</code></li> |
245 |
</ol> |
246 |
<p>Return: string of HTML representing single feed publish form content</p> |
247 |
</dd> |
248 |
<dt><a name="method-feedSubscriptionFormHTML"></a>feedSubscriptionFormHTML</dt> |
249 |
<dd> |
250 |
<p>Retrieve feed subscription form HTML</p> |
251 |
<p class="arguments-head">Args:</p> |
252 |
<ol class="arguments"> |
253 |
<li><code class="class">RF_Feed</code></li> |
254 |
</ol> |
255 |
<p>Return: string of HTML representing single feed subscription form content</p> |
256 |
</dd> |
257 |
<dt><a name="method-feedTagsFormHTML"></a>feedTagsFormHTML</dt> |
258 |
<dd> |
259 |
<p>Retrieve feed tags form HTML</p> |
260 |
<p class="arguments-head">Args:</p> |
261 |
<ol class="arguments"> |
262 |
<li><code class="class">RF_Feed</code></li> |
263 |
</ol> |
264 |
<p>Return: string of HTML representing single feed tags form content</p> |
265 |
</dd> |
266 |
<dt><a name="method-itemBodyHTML"></a>itemBodyHTML</dt> |
267 |
<dd> |
268 |
<p>Retrieve item body HTML</p> |
269 |
<p class="arguments-head">Args:</p> |
270 |
<ol class="arguments"> |
271 |
<li><code class="class">RF_Item</code></li> |
272 |
</ol> |
273 |
<p>Return: string of HTML representing single item body content</p> |
274 |
</dd> |
275 |
<dt><a name="method-itemCommentFormHTML"></a>itemCommentFormHTML</dt> |
276 |
<dd> |
277 |
<p>Retrieve item comment form HTML</p> |
278 |
<p class="arguments-head">Args:</p> |
279 |
<ol class="arguments"> |
280 |
<li><code class="class">RF_Item</code></li> |
281 |
</ol> |
282 |
<p>Return: string of HTML representing single item comment form content</p> |
283 |
</dd> |
284 |
<dt><a name="method-itemEditFormHTML"></a>itemEditFormHTML</dt> |
285 |
<dd> |
286 |
<p>Retrieve item edit form HTML</p> |
287 |
<p class="arguments-head">Args:</p> |
288 |
<ol class="arguments"> |
289 |
<li><code class="class">RF_Item</code></li> |
290 |
</ol> |
291 |
<p>Return: string of HTML representing single item edit form content</p> |
292 |
</dd> |
293 |
<dt><a name="method-itemHeadHTML"></a>itemHeadHTML</dt> |
294 |
<dd> |
295 |
<p>Retrieve item head HTML</p> |
296 |
<p class="arguments-head">Args:</p> |
297 |
<ol class="arguments"> |
298 |
<li><code class="class">RF_Item</code></li> |
299 |
</ol> |
300 |
<p>Return: string of HTML representing single item head content</p> |
301 |
</dd> |
302 |
<dt><a name="method-markFeedPublished"></a>markFeedPublished</dt> |
303 |
<dd> |
304 |
<p>Mark a feed as published</p> |
305 |
<p class="arguments-head">Args:</p> |
306 |
<ol class="arguments"> |
307 |
<li><code class="class">RF_Feed</code></li> |
308 |
</ol> |
309 |
<p>Return: boolean <code>true</code> on success</p> |
310 |
</dd> |
311 |
<dt><a name="method-markFeedRead"></a>markFeedRead</dt> |
312 |
<dd> |
313 |
<p>Mark all items in a feed as read</p> |
314 |
<p class="arguments-head">Args:</p> |
315 |
<ol class="arguments"> |
316 |
<li>array of <code class="class">RF_Feed</code>s</li> |
317 |
</ol> |
318 |
<p>Return: boolean <code>true</code> on success</p> |
319 |
</dd> |
320 |
<dt><a name="method-markFeedUnpublished"></a>markFeedUnpublished</dt> |
321 |
<dd> |
322 |
<p>Mark a feed as unpublished</p> |
323 |
<p class="arguments-head">Args:</p> |
324 |
<ol class="arguments"> |
325 |
<li><code class="class">RF_Feed</code></li> |
326 |
</ol> |
327 |
<p>Return: boolean <code>true</code> on success</p> |
328 |
</dd> |
329 |
<dt><a name="method-markFeedUnread"></a>markFeedUnread</dt> |
330 |
<dd> |
331 |
<p>Mark all items in a feed as unread</p> |
332 |
<p class="arguments-head">Args:</p> |
333 |
<ol class="arguments"> |
334 |
<li>array of <code class="class">RF_Feed</code>s</li> |
335 |
</ol> |
336 |
<p>Return: boolean <code>true</code> on success</p> |
337 |
</dd> |
338 |
<dt><a name="method-markItemPublished"></a>markItemPublished</dt> |
339 |
<dd> |
340 |
<p>Mark an item as published</p> |
341 |
<p class="arguments-head">Args:</p> |
342 |
<ol class="arguments"> |
343 |
<li><code class="class">RF_Item</code></li> |
344 |
</ol> |
345 |
<p>Return: boolean <code>true</code> on success</p> |
346 |
</dd> |
347 |
<dt><a name="method-markItemRead"></a>markItemRead</dt> |
348 |
<dd> |
349 |
<p>Mark an item as read</p> |
350 |
<p class="arguments-head">Args:</p> |
351 |
<ol class="arguments"> |
352 |
<li><code class="class">RF_Item</code></li> |
353 |
</ol> |
354 |
<p>Return: boolean <code>true</code> on success</p> |
355 |
</dd> |
356 |
<dt><a name="method-markItemsPublished"></a>markItemsPublished</dt> |
357 |
<dd> |
358 |
<p>Mark several items as published</p> |
359 |
<p class="arguments-head">Args:</p> |
360 |
<ol class="arguments"> |
361 |
<li>array of <code class="class">RF_Item</code>s</li> |
362 |
</ol> |
363 |
<p>Return: boolean <code>true</code> on success</p> |
364 |
</dd> |
365 |
<dt><a name="method-markItemsRead"></a>markItemsRead</dt> |
366 |
<dd> |
367 |
<p>Mark several items as read</p> |
368 |
<p class="arguments-head">Args:</p> |
369 |
<ol class="arguments"> |
370 |
<li>array of <code class="class">RF_Item</code>s</li> |
371 |
</ol> |
372 |
<p>Return: boolean <code>true</code> on success</p> |
373 |
</dd> |
374 |
<dt><a name="method-markItemsUnread"></a>markItemsUnread</dt> |
375 |
<dd> |
376 |
<p>Mark several items as unread</p> |
377 |
<p class="arguments-head">Args:</p> |
378 |
<ol class="arguments"> |
379 |
<li>array of <code class="class">RF_Item</code>s</li> |
380 |
</ol> |
381 |
<p>Return: boolean <code>true</code> on success</p> |
382 |
</dd> |
383 |
<dt><a name="method-markItemUnpublished"></a>markItemUnpublished</dt> |
384 |
<dd> |
385 |
<p>Mark an item unas published</p> |
386 |
<p class="arguments-head">Args:</p> |
387 |
<ol class="arguments"> |
388 |
<li><code class="class">RF_Item</code></li> |
389 |
</ol> |
390 |
<p>Return: boolean <code>true</code> on success</p> |
391 |
</dd> |
392 |
<dt><a name="method-markItemUnread"></a>markItemUnread</dt> |
393 |
<dd> |
394 |
<p>Mark an item as unread</p> |
395 |
<p class="arguments-head">Args:</p> |
396 |
<ol class="arguments"> |
397 |
<li><code class="class">RF_Item</code></li> |
398 |
</ol> |
399 |
<p>Return: boolean <code>true</code> on success</p> |
400 |
</dd> |
401 |
<dt><a name="method-postItem"></a>postItem</dt> |
402 |
<dd> |
403 |
<p>Post a new item</p> |
404 |
<p class="arguments-head">Args:</p> |
405 |
<ol class="arguments"> |
406 |
<li> |
407 |
associative array of item arguments: |
408 |
<ul> |
409 |
<li><code>title</code>: Title of new item, required</li> |
410 |
<li><code>link</code>: Link for new item, required.</li> |
411 |
<li><code>content</code>: Content of new item, required.</li> |
412 |
<li><code>tags</code>: Space-delimited list of item tags, optional.</li> |
413 |
<li><code>feed_id</code>: numeric feed ID; leave this blank in almost all cases.</li> |
414 |
<li><code>modified</code>: modification timestamp; leave blank for "now".</li> |
415 |
<li><code>guid</code>: globally unique identifier; leave this blank in almost all cases.</li> |
416 |
</ul> |
417 |
</li> |
418 |
<li> |
419 |
optional array of metadata:<br /> |
420 |
Each element should be an associative array of the form:<br /> |
421 |
<code>{"label": ..., "value": ..., "format": ...}</code> |
422 |
</li> |
423 |
</ol> |
424 |
<p>Return: <code class="class">RF_Item</code></p> |
425 |
</dd> |
426 |
<dt><a name="method-setFeedTags"></a>setFeedTags</dt> |
427 |
<dd> |
428 |
<p>Set an feed's tags</p> |
429 |
<p class="arguments-head">Args:</p> |
430 |
<ol class="arguments"> |
431 |
<li><code class="class">RF_Feed</code></li> |
432 |
<li>array of strings: tags</li> |
433 |
<li>boolean: apply tags to all existing items in feed? optional, default <code>false</code></li> |
434 |
</ol> |
435 |
<p>Return: boolean <code>true</code> on success</p> |
436 |
</dd> |
437 |
<dt><a name="method-setItemCommentTags"></a>setItemCommentTags</dt> |
438 |
<dd> |
439 |
<p>Set an item's comment and tags</p> |
440 |
<p class="arguments-head">Args:</p> |
441 |
<ol class="arguments"> |
442 |
<li><code class="class">RF_Item</code></li> |
443 |
<li>string: comment</li> |
444 |
<li>array of strings: tags</li> |
445 |
</ol> |
446 |
<p>Return: boolean <code>true</code> on success</p> |
447 |
</dd> |
448 |
<dt><a name="method-setItemLink"></a>setItemLink</dt> |
449 |
<dd> |
450 |
<p>Set an item's link</p> |
451 |
<p class="arguments-head">Args:</p> |
452 |
<ol class="arguments"> |
453 |
<li><code class="class">RF_Item</code></li> |
454 |
<li>string: link</li> |
455 |
</ol> |
456 |
<p>Return: boolean <code>true</code> on success</p> |
457 |
</dd> |
458 |
<dt><a name="method-setItemTags"></a>setItemTags</dt> |
459 |
<dd> |
460 |
<p>Set an item's tags</p> |
461 |
<p class="arguments-head">Args:</p> |
462 |
<ol class="arguments"> |
463 |
<li><code class="class">RF_Item</code></li> |
464 |
<li>array of strings: tags</li> |
465 |
</ol> |
466 |
<p>Return: boolean <code>true</code> on success</p> |
467 |
</dd> |
468 |
<dt><a name="method-setItemTitleContentLink"></a>setItemTitleContentLink</dt> |
469 |
<dd> |
470 |
<p>Set an item's title, link and content</p> |
471 |
<p class="arguments-head">Args:</p> |
472 |
<ol class="arguments"> |
473 |
<li><code class="class">RF_Item</code></li> |
474 |
<li>string: title</li> |
475 |
<li>string: content</li> |
476 |
<li>string: link</li> |
477 |
</ol> |
478 |
<p>Return: boolean <code>true</code> on success</p> |
479 |
</dd> |
480 |
<dt><a name="method-setKeyboardUse"></a>setKeyboardUse</dt> |
481 |
<dd> |
482 |
<p>Toggle keyboard usage flag</p> |
483 |
<p class="arguments-head">Args:</p> |
484 |
<ol class="arguments"> |
485 |
<li><code>boolean</code>: turn keyboard usage on or off</li> |
486 |
</ol> |
487 |
<p>Return: boolean <code>true</code> on success</p> |
488 |
</dd> |
489 |
</dl> |
490 |
<h2><a name="license"></a>License</h2> |
491 |
<p> |
492 |
Reblog is distributed under the GPL (see the <a href="LICENSE">LICENSE</a> file in this directory), though some of its included libraries (in<code>./library/</code>) are not. |
493 |
</p> |
494 |
</div> |
495 |
</body> |
496 |
</html> |