/[refeed]/trunk/API.html
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /trunk/API.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2 - (show annotations)
Wed Jul 5 00:27:49 2006 UTC (17 years, 10 months ago) by dpavlin
File MIME type: text/html
File size: 23286 byte(s)
make working copy of trunk
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>

Properties

Name Value
svn:mime-type text/html

  ViewVC Help
Powered by ViewVC 1.1.26