ZebraFeeds

Reference documentation

Installation

  1. Uncompress the package
  2. Upload the zebrafeeds directory to your web server
  3. Run the installation script. Surf to <yoursite.com>/zebrafeeds/install.php.
    ZebraFeeds implements two login mechanisms. Either:
    • server - HTTP Server Basic Auth (has limitations on several webservers such as the ones that run PHP as CGI; sends user password base64 encoded; when you logout you need to press cancel when the authentication box appears)
    • session - PHP sessions (depends on your webhost's php.ini configuration and can use cookies; sends user password in clear text)
    You may choose user login and password during the installation.
  4. Point your browser to <yoursite.com>/zebrafeeds to start using ZebraFeeds.
  5. If you need to embed the aggregated feeds on your page, check out the "Embed feeds on your site" section or open embed-demo.php in your browser or in an editor to find out how to embed ZebraFeeds on your page (short version: include zebrafeeds/embed/feeds.php). Also select a provided template, either as is or customized or make your own.

Upgrade from 1.X

On upgrading from ZebraFeeds 1.X, the configuration file - most of the settings and the admin user/password - can not be reused in ZebraFeeds 2.0
Recovering the feeds subscriptions is possible but alas requires a bit of manual work, since subscriptions are now stored in a single OPML file.
Merge each OPML file into /data/zebrafeeds.opml after the installation: From each OPML file, copy all lines starting with <outline> to the body section of /zebrafeeds/data/zebrafeeds.opml.

Embed feeds on your site

You must include the main script in the <body> section and the header script in the <head> section of the page on which the feeds are to be displayed.
The header script handles thre template's CSS and javascript, while the main script renders the aggregated feeds.
Note: if your template has no templateHeader section (that is, no style sheet), the header script may not be necessary.

Here is an example of a minimal page:
<html>
<head>
  <?php include('zebrafeeds/embed/header.php'); ?>
</head>
<body>
  <?php include('zebrafeeds/embed/feeds.php'); ?>
</body>
</html>

Features setup

Refreshing feeds

By default ZebraFeeds refreshes the feed on page generation, that is, whenever needed. In the settings, refresh mode must be set to "automatic".
This requires no extra configuration (but can severely slow down the page loading. The next section describes how to use a cron job to schedule the refresh.

Refreshing feeds via a cronjob

ZebraFeeds allows setting up an external automated task (a.k.a. cron job) in order to regularly refresh feeds, and provided a private refresh link to place in your automated task.
The private link can be found in the settings pages.
You might also want to set refresh mode to "manual".

Please note that each feed's refresh time still applies. If you configure a service to call the refresh link every 30 minutes, it means that the feeds will be checked for expiration that often. It doesn't mean that the feeds will be fetched from the publisher every 30 minutes.
The link will change whenever the admin user name or password changes.

Marking "new" items

ZebraFeeds can optionally highlight news items which are more recent that the visitor's last visit. It applies to all visitors indistinctly. It requires no additional change on your page since the time is stored in the data subdirectory. To mark new items on the generated html content, you have to use the template tag {isnew} in your template (see below).
Please note this feature does not keep track of the unread items, it just highlights the items that had not been fetched yet at the time of the last visit.
This works by means of "sessions". Sessions last by default 15 minutes (see constant named ZF_SESSION_DURATION in globals.php). After 15 minutes without any activity (access to feeds), the session expires, and all items in the cache get marked as "not new".
This is equivalent to marking all items as "read" every time you stop reading your feeds in ZebraFeeds.
How to tag new items in the template?
  • use the {isnew} template tag. This tag will be replaced by a static string if the item is new (not already seen in last refresh), by an empty string otherwise.
  • ZebraFeeds uses the value defined in the string ZF_ISNEW_STRING in globals.php. at the time of content generation
  • Default value is "newclass" intented to be placed in an element's CSS class declaration. See the example templates

Template reference

You can customize the look of the aggregated feeds by editing the templates or creating new ones.
A template is a file that contains HTML/XHTML code.
  • Templates file names have must have the html extension to be recognised.
  • File must contain delimited sections
  • Sections must use special tags

Template sections

  • templateHeader: before any channel display. use it to include javascript, css... Is included in the HEAD section of the page (if zebrafeeds/embed/header.php is included).
  • header: header before channel header. It is not parsed for any tag.
  • channel: prints the channel header. Use it to show channel logo, title...
  • channelFooter: formats the channel footer. Not parsed for any tag.
  • news: formats a news item when sorted by channel. Parsed for tags.
  • newsByDate: formats a news items when sorted by date. Parsed for tags.
  • newsDay: printed at every new day when items are sorted by date. Use {date} tag to print the date (see below).
  • newsdayFooter: formats the day footer. Not parsed for any tag.
  • article: Used when rendering a single news item in a full page. Parsed for tags.

How sections are rendered in HTML

When sorted by feed, the HTML output is generated this way:
  • header
  • For each feed
    • channel
    • for each news item
      • news
    • channelFooter
  • footer
It's a bit different when sorted by date. It's like having only one channel to display, but news are broken down by day:

  • header
  • For each day
    • newsDay
    • For each news item
      • newsByDate (or news if empty)
    • newsDayFooter
  • footer
A list of supported tags is presented below. Due to the linear way of processing templates, some tags will be relevant in certain contexts depending on the section they are included in:

The article section

The article section will be used to print the full news items in the article view.
The article view embeds the news item at the location where feeds are embedded on your site. (It shows one article where it would show the list of news and channels.) This is meant to display the news content once clicked on the title, nicely integrated in your page.
The link to view a news item in the Article view can be displayed in the news list thanks to the {articleurl} template tag.

Channel tags

  • {chanlink} is replaced with URL to the channel
  • {chandesc} is replaced with the channel description
  • {chantitle} is replaced with the channel title
  • {chanid} is replaced with an unique ID of the channel (feed) being displayed
  • {lastupdated} is replaced with the time/date when the feed was last fetched, according to date format
  • {feedurl} is replaced with the RSS feed url

News item and article tags

  • {title} is replaced with the news title
  • {link} is replaced with the URL to the news page
  • {link_encoded} is replaced with the URL to the news page, encoded to be used as parameter in an hypertext link
  • {pubdate} is replaced with the news publication date if available, formatted according to configuration
  • {relativedate} relative news item date "1h ago", "3d ago"...
  • {description} is replaced with the available news description (full-length content as provided by the source).
  • {summary} the news summary as truncated by ZebraFeeds
  • {enclosures} the list of external enclosures of the news, if any. Autodetection of audio and video content, printed with relevant icons.
  • {itemid} unique news item ID
  • {isnew} string to insert if the news hasn't been seen before (string must be changed manually in globals.php, variable ZF_ISNEWSTRING), empty otherwise (if configured in settings)
  • {articleurl} link to show the entire news item in a the article view, a full page formatted header and the article content, using the article template section
  • {download} link to fetch the full content of the article from the news item's link provided by the publisher (using FiveFilter's readability implementation). The content will be cached and presented using the article template section.

News day tags

  • {date} is replaced with the date of the news items displayed beneath.

Special tags

  • {scripturl} is replaced with the url to ZebraFeeds
  • {tag} is replaced with the name of the current feed tag, if applicable

Built-in styles

ZebraFeeds generates some output that have forced CSS attributes. Proper styling using CSS helps a seamless integration on your site.
This sections lists all CSS elements that you can add to your style sheet
  • generator CSS ID: the credit line that is added after the feeds rendering carries this ID.

API and parameters reference

Parameter Description Default Possible values
Main parameters
q query type tag
item a single new item, with article view
channel we want channel news, sorted by date
tag feeds tagged with a certain tag
subs (subs being tagged with specified tag, all if no tag specified) JSON only
tags (all tags available in subscriptions) JSON output only
download-item get full article content if possible
summary only the summary of an article
f output type html
json JSON output, and 'sort' param ignored. always by date, feeds aggregated.
html HTML output in regular page, with header section.
innerhtml HTML output, but won't output header section of template. suitable for JS calls
Additional parameters

tag: use only subscription with this tag. Default: empty. applicable only for q=subs and q=tag

id: id of the channel to deal with. Needed for q=item, q=download-item, q=channel, q=summary

itemid: the news item unique id for lookup. Needed for q=item, q=download-item, q=summary

mode: feed update mode. applicable only for q=channel

sum: if 1 then summary included in news item header, 0 no summary (default)
Applicable only when q=channel or q=tag

trim: how to shorten the number of items when getting feeds to get only news or the last hour, of the last 4 days...
valid when q=tag or q=channel

onlynew: default to 0. If 1 will show only newly fetched items. Valid for q=tag, q=channel

sort: feed or date. Only for q=tag AND for html output (f=html or q=innerhtml)

decoration: if (q=channel AND f=html) only
defaults to 0. if 1, will output channel header

Configuration file reference

This section lists the options available in config.php file as well as through the settings page.
Parameter Description
General options
ZF_LOGINTYPE server - server HTTP auth; session - PHP sessions auth
ZF_ADMINNAME admin username
ZF_ADMINPASS crypted (md5) admin password, default password is "admin".
If set to empty, the admin pages authentication is disabled, and anyone can get to the config page and save a new password. It's a way of resetting the password. Caution with that.
Feeds options
ZF_HOMETAG name of the tag of feeds to be displayed by default (taken from the subscriptions directory which holds the subscriptions data)
ZF_REFRESHMODE "automatic" to let ZebraFeeds refresh feeds upon page generation, or "request", to allow automatic refresh as well as using cron job or webpage checker service
General display options
ZF_TEMPLATE the default templates used to display the news (file name from templates directory)
ZF_DISPLAYERROR if yes then when a feed cannot be read (or has errors) formatted error message shows in {description}
Localization options
ZF_ENCODING character encoding for output. Example: UTF-8, ISO-8859-1...
ZF_LOCALE language to use for dates, system messages. Depends on your PHP installation
ZF_PUBDATEFORMAT format passed to strftime to convert dates got from feeds
ZF_DATEFORMAT format passed to strftime to display the date of the day when displaying news sorted by date
Hidden options
These options are not editable through the settings page, but directly editing globals.php
ZF_DEFAULT_NEWS_COUNT when subscribing to a new feed, default value for number of news
ZF_DEFAULT_REFRESH_TIME when subscribing to a new feed, default value for refresh time
ZF_SESSION_DURATION time in seconds before unmarking items as new (default 900)
ZF_GROUP_BY_DAY 'yes' will group items by day in non-per-channel views
ZF_SHOWCREDITS 'yes' (default) or 'no'. If no, will not append the credit line.
ZF_ISNEW_STRING string being substituted for the {isnew} template tag
ZF_DEFAULT_ADMIN_VIEW first page shown when going to the admin area if not specified. 'subscriptions' (if feeds embedded on another page, ZebraFeeds not used as feed reader) or 'feeds' (suited if ZebraFeeds used as personal feed reader)