161 lines
5.9 KiB
Plaintext
161 lines
5.9 KiB
Plaintext
Installing Planet
|
|
-----------------
|
|
|
|
You'll need at least Python 2.2 installed on your system, we recommend
|
|
Python 2.4 though as there may be bugs with the earlier libraries.
|
|
|
|
Everything Pythonesque Planet needs should be included in the
|
|
distribution.
|
|
|
|
i.
|
|
First you'll need to extract the files into a folder somewhere.
|
|
I expect you've already done this, after all, you're reading this
|
|
file. You can place this wherever you like, ~/planet is a good
|
|
choice, but so's anywhere else you prefer.
|
|
|
|
ii.
|
|
This is very important: from within that directory, type the following
|
|
command:
|
|
|
|
python runtests.py
|
|
|
|
This should take anywhere from a half a second to ten seconds to execute.
|
|
No network connection is required, and it cleans up after itself. If it
|
|
completes with an "OK", you are good to go. Otherwise stopping here and
|
|
inquiring on the mailing list is a good idea as it can save you lots of
|
|
frustration down the road.
|
|
|
|
iii.
|
|
Make a copy of one of the 'ini' the files in the 'examples' subdirectory,
|
|
and put them wherever you like; I like to use the Planet's name (so
|
|
~/planet/debian), but it's really up to you.
|
|
|
|
iv.
|
|
Edit the config.ini file in this directory to taste, it's pretty
|
|
well documented so you shouldn't have any problems here. Pay
|
|
particular attention to the 'output_dir' option, which should be
|
|
readable by your web server. If the directory you specify in your
|
|
'cache_dir' exists, make sure that it is empty.
|
|
|
|
v.
|
|
Run it: python planet.py pathto/config.ini
|
|
|
|
You'll want to add this to cron, make sure you run it from the
|
|
right directory.
|
|
|
|
vi. (Optional)
|
|
Tell us about it! We'd love to link to you on planetplanet.org :-)
|
|
|
|
vii. (Optional)
|
|
Build your own themes, templates, or filters! And share!
|
|
|
|
|
|
Template files
|
|
--------------
|
|
|
|
The template files used are given as a whitespace separated list in the
|
|
'template_files' option in config.ini. The extension at the end of the
|
|
file name indicates what processor to use. Templates may be implemented
|
|
using htmltmpl, xslt, or any programming language.
|
|
|
|
The final extension is removed to form the name of the file placed in the
|
|
output directory.
|
|
|
|
HtmlTmpl files
|
|
--------------
|
|
|
|
Reading through the example templates is recommended, they're designed to
|
|
pretty much drop straight into your site with little modification
|
|
anyway.
|
|
|
|
Inside these template files, <TMPL_VAR xxx> is replaced with the content
|
|
of the 'xxx' variable. The variables available are:
|
|
|
|
name .... } the value of the equivalent options
|
|
link .... } from the [Planet] section of your
|
|
owner_name . } Planet's config.ini file
|
|
owner_email }
|
|
|
|
url .... link with the output filename appended
|
|
generator .. version of planet being used
|
|
|
|
date .... { your date format
|
|
date_iso ... current date and time in { ISO date format
|
|
date_822 ... { RFC822 date format
|
|
|
|
|
|
There are also two loops, 'Items' and 'Channels'. All of the lines of
|
|
the template and variable substitutions are available for each item or
|
|
channel. Loops are created using <TMPL_LOOP LoopName>...</TMPL_LOOP>
|
|
and may be used as many times as you wish.
|
|
|
|
The 'Channels' loop iterates all of the channels (feeds) defined in the
|
|
configuration file, within it the following variables are available:
|
|
|
|
name .... value of the 'name' option in config.ini, or title
|
|
title .... title retreived from the channel's feed
|
|
tagline .... description retreived from the channel's feed
|
|
link .... link for the human-readable content (from the feed)
|
|
url .... url of the channel's feed itself
|
|
|
|
Additionally the value of any other option specified in config.ini
|
|
for the feed, or in the [DEFAULT] section, is available as a
|
|
variable of the same name.
|
|
|
|
Depending on the feed, there may be a huge variety of other
|
|
variables may be available; the best way to find out what you
|
|
have is using the 'planet-cache' tool to examine your cache files.
|
|
|
|
The 'Items' loop iterates all of the blog entries from all of the channels,
|
|
you do not place it inside a 'Channels' loop. Within it, the following
|
|
variables are available:
|
|
|
|
id .... unique id for this entry (sometimes just the link)
|
|
link .... link to a human-readable version at the origin site
|
|
|
|
title .... title of the entry
|
|
summary .... a short "first page" summary
|
|
content .... the full content of the entry
|
|
|
|
date .... { your date format
|
|
date_iso ... date and time of the entry in { ISO date format
|
|
date_822 ... { RFC822 date format
|
|
|
|
If the entry takes place on a date that has no prior entry has
|
|
taken place on, the 'new_date' variable is set to that date.
|
|
This allows you to break up the page by day.
|
|
|
|
If the entry is from a different channel to the previous entry,
|
|
or is the first entry from this channel on this day
|
|
the 'new_channel' variable is set to the same value as the
|
|
'channel_url' variable. This allows you to collate multiple
|
|
entries from the same person under the same banner.
|
|
|
|
Additionally the value of any variable that would be defined
|
|
for the channel is available, with 'channel_' prepended to the
|
|
name (e.g. 'channel_name' and 'channel_link').
|
|
|
|
Depending on the feed, there may be a huge variety of other
|
|
variables may be available; the best way to find out what you
|
|
have is using the 'planet-cache' tool to examine your cache files.
|
|
|
|
|
|
There are also a couple of other special things you can do in a template.
|
|
|
|
- If you want HTML escaping applied to the value of a variable, use the
|
|
<TMPL_VAR xxx ESCAPE="HTML"> form.
|
|
|
|
- If you want URI escaping applied to the value of a variable, use the
|
|
<TMPL_VAR xxx ESCAPE="URI"> form.
|
|
|
|
- To only include a section of the template if the variable has a
|
|
non-empty value, you can use <TMPL_IF xxx>....</TMPL_IF>. e.g.
|
|
|
|
<TMPL_IF new_date>
|
|
<h1><TMPL_VAR new_date></h1>
|
|
</TMPL_IF>
|
|
|
|
You may place a <TMPL_ELSE> within this block to specify an
|
|
alternative, or may use <TMPL_UNLESS xxx>...</TMPL_UNLESS> to
|
|
perform the opposite.
|