-
Notifications
You must be signed in to change notification settings - Fork 0
/
README-en.html
279 lines (206 loc) · 12.7 KB
/
README-en.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
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Pubwich — Read me</title>
<style type="text/css">
html { font-size: 62.5% }
body { margin: 0; padding: 50px 70px 40px; font-family: Helvetica, Arial, sans-serif; font-size: 140%; line-height: 1.3; background: #111; color: #ccc; }
ul, ol { padding-left: 18px; }
hr { color: #111; border: none; border-bottom: 1px solid #333; height: 1px; margin: 2em 0; display: none; }
a { color: #35ADAB; }
a:hover { color: #7CCCCB; }
h1, h2, h3 { color: #fff; margin-left: -30px; }
h4 { color: #666; margin: 2em 0 1em; }
h2 { margin-top: 2.5em; margin-bottom: 0.7em; }
h3 { margin-top: 2em; color: #ddd; border-bottom: 1px solid #333; padding-bottom: 0.6em; }
code { font-size: 120%; background: #000; color: #FFFFCF; }
pre { background: #000; color: #FFFFCF; padding: 5px; }
table { border-collapse: collapse; }
table td { border: 2px solid #111; padding: 5px 7px; background: #0a0a0a; }
h1 small { font-size: 50%; color: #777; font-weight: normal; }
#footer { margin-top: 4em; padding-top: 2em; border-top: 1px solid #333; }
#footer small { color: #555; font-size: 100%; margin-left: 1em; }
</style>
</head>
<body>
<h1>Pubwich</h1>
<ol>
<li><a href="#components">Required components</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#configuration">Services configuration</a></li>
<li><a href="#theme">Theme configuration</a></li>
</ol>
<hr/>
<h2 id="components">1. Required components</h2>
<p>The following components must be installed so Pubwich can work:</p>
<ul>
<li><a href="http://apache.org">Apache</a></li>
<li><a href="http://php.net">PHP 5</a> (with <code>SimpleXML</code> & <code>cURL</code> extensions)</li>
<li><code>crontab</code> (installed on all UNIX systems)</li>
</ul>
<hr/>
<h2 id="installation">2. Installation</h2>
<ol>
<li>
<p>Duplicate <code>cfg/config.sample.php</code> to <code>cfg/config.php</code></p>
<p>(optional: if you want to use a custom theme, duplicate <code>themes/default</code> to <code>themes/your_theme_name</code> and edit the <code>PUBWICH_THEME</code> constant in <code>cfg/config.php</code> to "<code>your_theme_name</code>".</p>
</li>
<li>
<p>Edit the newly created <code>config.php</code> to fill the blank spaces with your informations (API keys, usernames, site’s URL, etc.) and to modify the arguments passed to <code>Pubwich::setServices()</code>. See the <a href="#configuration">Services configuration</a> section of this file.</p>
</li>
<li>
<p>Modify your <code>crontab</code> file (by running <code>crontab -e</code>) and add the following line:</p>
<p><code>*/<N> * * * * <PHP> -f <ABSOLUTE_PATH>/cron/cron.php</code></p>
<p>Then replace the following elements:</p>
<table>
<tr><td><code><N></code></td><td>Cache expiration (in minutes)</td></tr>
<tr><td><code><PHP></code></td><td>The path to PHP executable binary (usually <code>/usr/bin/php</code> or <code>/usr/local/bin/php</code>, use <code>which php</code> to find it)</td></tr>
<tr><td><code><ABSOLUTE_PATH></code></td><td>Absolute path to Pubwich directory</td></tr>
</table>
<p>Example:</p>
<p><code>*/10 * * * * /usr/bin/php -f /home/myusername/public_html/pubwich/trunk/cron/cron.php</code></p>
</li>
<li><p>Change the permissions on the <code>cache</code> directory to make it writeable for all (<code>$ chmod -R 0777 cache</code>).</p></li>
<li><p>Everything should be working now (when browsing to the <code>index.php</code>!).</p></li>
</ol>
<hr/>
<h2 id="configuration">3. Services configuration</h2>
<p>The <code>Pubwich</code> object has a <code>setServices</code> method which take an array as its only parameter. Each element of this array is a column (defined by an array). Each column element is a service box (see the <code>cfg/config.sample.php</code> file for more examples). The order of the boxes within the column array will be the same order used for the template. To configure a box, you must use the following syntax:</p>
<p><code>array( <service>, <variable>, <config> )</code></p>
<p>Where:</p>
<table>
<tr><td><code><service></code></td><td>the service name (<code>'Flickr'</code>, <code>'Twitter'</code>, etc.)</td></tr>
<tr><td><code><variable></code></td><td>the box’s unique name (<code>'photos'</code>, <code>'statuses'</code>, etc.)</td> </tr>
<tr><td><code><config></code></td><td>an array of <a href="#configuration-elements">configuration elements</a></td></tr>
</table>
<h3 id="configuration-elements">Common configuration elements</h3>
<p>These elements can be used in any box configuration:</p>
<table>
<tr><td><code>title</code></td><td>The box’s main title</td></tr>
<tr><td><code>description</code></td><td>The box’s short description (usually dsplayed near the title)</td></tr>
<tr><td><code>total</code></td><td>Total of elements to show for this box</td></tr>
</table>
<h3>Atom service configuration elements</h3>
<table>
<tr><td><code>url</code></td><td>Atom feed URL</td></tr>
<tr><td><code>link</code></td><td>Main website URL</td></tr>
</table>
<h3>Delicious service configuration elements</h3>
<table>
<tr><td><code>username</code></td><td>Your username</td></tr>
</table>
<h3>Facebook service configuration elements</h3>
<p>To find some informations, you will have to go to the <a href="http://www.facebook.com/notifications.php">following page</a>, and extract the <code>&id</code> and <code>&key</code> query variables from the "Your alerts" link.</p>
<table>
<tr><td><code>id</code></td><td>Your user id</td></tr>
<tr><td><code>key</code></td><td>Your personal API key</td></tr>
<tr><td><code>username</code></td><td>Your username</td></tr>
</table>
<h3>Flickr service configuration elements</h3>
<table>
<tr><td><code>method</code></td><td><code>FlickrUser</code>, <code>FlickrGroup</code> or <code>FlickrTags</code></td></tr>
<tr><td><code>key</code></td><td>Your API key</td></tr>
<tr><td><code>userid</code></td><td>Your user id (you will have to use <a href="http://idgettr.com/">http://idgettr.com</a> to find it easily)</td></tr>
<tr><td><code>username</code></td><td>Your username</td></tr>
<tr><td><code>groupid</code></td><td>Your group id</td></tr>
<tr><td><code>tags</code></td><td>Your tags (eg. <code>array('blue', 'sky')</code> or <code>'blue,sky'</code></td></tr>
<tr><td><code>row</code></td><td>The number of photos by row. Pubwich will add the class <code>derniere</code> to each end-of-row photo.</td></tr>
</table>
<h3>Lastfm service configuration elements</h3>
<table>
<tr><td><code>method</code></td><td><code>LastFMWeeklyAlbums</code> or <code>LastFMRecentTracks</code></td></tr>
<tr><td><code>key</code></td><td>Your API key (<a href="http://www.last.fm/api/account">get an API key</a>)</td></tr>
<tr><td><code>username</code></td><td>Your username</td></tr>
<tr><td><code>size</code></td><td>The width of the album covers</td></tr>
</table>
<h3>Readernaut service configuration elements</h3>
<table>
<tr><td><code>method</code></td><td><code>ReadernautBooks</code> or <code>ReadernautNotes</code></td></tr>
<tr><td><code>username</code></td><td>Your username</td></tr>
<tr><td><code>size</code></td><td>The width of the book covers</td></tr>
</table>
<h3>RSS service configuration elements</h3>
<table>
<tr><td><code>url</code></td><td>The feed URL</td></tr>
<tr><td><code>link</code></td><td>The website URL</td></tr>
</table>
<h3>Text service configuration elements</h3>
<table>
<tr><td><code>text</code></td><td>The text to put in the box</td></tr>
</table>
<h3>Twitter service configuration elements</h3>
<table>
<tr><td><code>method</code></td><td><code>TwitterUser</code> or <code>TwitterSearch</code></td></tr>
<tr><td><code>id</code></td><td>Your user id</td></tr>
<tr><td><code>username</code></td><td>Your username</td></tr>
<tr><td><code>terms</code></td><td>Your search terms</td></tr>
</table>
<h3>Vimeo service configuration elements</h3>
<table>
<tr><td><code>username</code></td><td>Your username</td></tr>
</table>
<h3>Youtube service configuration elements</h3>
<table>
<tr><td><code>username</code></td><td>Your username</td></tr>
<tr><td><code>size</code></td><td>The width of the video thumbnails</td></tr>
</table>
<hr/>
<h2 id="theme">4. Theme configuration</h2>
<p>A theme can be customized by using the <code>functions.php</code> file in the theme folder.</p>
<h3>Item template</h3>
<p>Each service has a default item template. For example, the default item template for Twitter is this:</p>
<pre><code><li class="clearfix"><span class="date"><a href="{%link%}">{%date%}</a></span>{%text%}</li></code></pre>
<p>However, it is possible to modify each service's item template, or even for a single instance of a service. To do so, you must edit the <code>functions.php</code> file and add the following function (and replacing <code>Service</code> by the actual service name):</p>
<pre><code>function Service_itemTemplate() {
return '<li><a href="{%link%}">{%title%}</a></li>';
}</code></pre>
<p>To only modify the item template of a particular service method, you must add the following line (and replacing <code>Service</code> by the service name, and <code>method</code> by the method name defined in your configuration file)</p>
<pre><code>function Service_ServiceMethod_itemTemplate() {
return '<li><a href="{%link%}">{%title%}</a></li>';
}</code></pre>
<p>To only modify the item template of a particular service instance, you must add the following line (and replacing <code>Service</code> by the service name, and <code>variable</code> by the variable name defined in your configuration file)</p>
<pre><code>function Service_variable_itemTemplate() {
return '<li><a href="{%link%}">{%title%}</a></li>';
}</code></pre>
<pre><code>function Service_ServiceMethod_variable_itemTemplate() {
return '<li><a href="{%link%}">{%title%}</a></li>';
}</code></pre>
<p>The tags (<code>{%link%}</code>, <code>{%title%}</code>, etc.) are different for each service. To get a list of available tags for a service, you must open the service file (in <code>lib/Services/</code>) and look for the <code>populateItemTemplate</code> method</p>
<h3>Box template</h3>
<p>Each theme must specify a default box template. The default theme's one is this:</p>
<pre><code><div class="boite {%class%}" id="{%id%}">
<h2><a rel="me" href="{%url%}">{%title%}</a> <span>{%description%}</span></h2>
<div class="boite-inner">
<ul class="clearfix">
{%items%}
</ul>
</div>
</div></code></pre>
<p>You can modify this function in the theme’s <code>functions.php</code> file.</p>
<p>It is also possible to modify a service box template with a function like this: (by replacing <code>Service</code> with the service name)</p>
<pre><code>function Service_boxTemplate() {
return '<div class="boite {%class%}" id="{%id%}">
<h2><a rel="me" href="{%url%}">{%title%}</a> <span>{%description%}</span></h2>
<div class="boite-inner">
<ul class="clearfix">
{%items%}
</ul>
</div>
</div>';
}</code></pre>
<p>To modify the box template of a particular service instance, you can use the same method as the item templates.</p>
<h4>Available box template tags</h4>
<table>
<tr><td><code>class</code></td><td>The box <code>class</code> HTML attribute</td></tr>
<tr><td><code>id</code></td><td>The box <code>title</code> HTML attribute</td></tr>
<tr><td><code>url</code></td><td>The service profile URL (eg. <code>http://www.twitter.com/remi/</code>)</td></tr>
<tr><td><code>title</code></td><td>The box title, as defined in the configuration file</td></tr>
<tr><td><code>description</code></td><td>The box description, defined in the configuration file</td></tr>
<tr><td><code>items</code></td><td>The items HTML code generated by Pubwich</td></tr>
</table>
<p>The tags must be used with this syntax: <code>{%tag%}</code></p>
<hr/>
<p id="footer">© Copyright Rémi Prévost 2008-2009 <small>($Date: 2009-07-20 21:19:34 -0400 (Lun, 20 jul 2009) $)</small></p>
</body>
</html>