This is the ZebraFeeds documentation page.
ZebraFeeds is a web-based news (RSS/ATOM) aggregator, released under the GPL

Requirements

Installation



ZebraFeeds implements two mechanisms for login to the administration panel. You can use: The administration panel can be found at the url
ZF_URL/admin/index.php
Default user is admin, pass is admin. Change these settings as soon as possible.

Include on your page

Including ZebraFeeds on your page is easy.

PHP script integration

This section describes the integration of ZebraFeeds script in another PHP script.
Once the installation is succesfull you can include the feedsreader on your PHP page. You must include the main script in the <body> section and the header script in the <head> section. The header script handles thre template's CSS and javascript, while the main script renders the aggregated feeds.
Note: if you don't plan to use a template with a templateHeader section (that is, no style sheet), the header script may not be necessary.

Here is an example of a minimal page (must be put in the directory containing the 'newsfeeds' dir):
	<html>
	 <head>
	  <?php include ('newsfeeds/zebraheader.php'); ?>
	 </head>
	 <body>
	  <?php include ('newsfeeds/zebrafeeds.php'); ?>
	 </body>
	</html>

ZebraFeeds cookie support
If you want individual visitors to see new news items since they last visit, you need to include zebracookies.php. It must be done before any other output, since cookies are sent in the headers.
	  <?php include ('newsfeeds/zebracookies.php'); ?>
	<html>
	 <head>
	  <?php include ('newsfeeds/zebraheader.php'); ?>
	 </head>
	 <body>
	  <?php include ('newsfeeds/zebrafeeds.php'); ?>
	 </body>
	</html>
See the below the section of the documentation pertaining to marking new items.
ZebraFeeds control bar
If you want to use the ZebraFeeds control bar, include
<?php include ('newsfeeds/zebrabar.php'); ?>
somewhere in the BODY section.

The ZebraFeeds control bar features useful controls to display/manage your feeds:
It should ideally be used if you plan to use ZebraFeeds as a personal feed reader, not if you just publish feeds on your site.

The bar just makes easy the use of the URL parameters available when calling ZebraFeeds:
examples:
http://example.com/newsfeeds/page_with_zebrafeeds.php?zftemplate=logos - will show the feeds with the "logos" template
http://example.com/page_with_zebrafeeds.php?zftemplate=some&zflist=linux will show only the feeds from the linux subscription list (that you defined in ZebraFeeds subscription lists admin panel)
Of course, these parameters are meant to be used in URLs, not in PHP include statements. (Note: in this example, page_with_zebrafeeds.php refers to the PHP script including zebrafeeds.php)

Manual configuration

The other way of including ZebraFeeds is to use the manual mode. Instead of having ZebraFeeds automatically generate code in your page, you can call specialised functions that will allow more control on the way the aggregation HTML code is generated.
Manual mode is disabled by default and can be enabled by the appropriate option of the configuration page.
See the relevant section for more information on the manual mode functions. Note: if you choose not to use OPML lists, the manual mode is the only way to display anything with ZebraFeeds.

Features

Share your feeds!

ZebraFeeds allows you to republish the feeds you carefully aggregated. There are two ways to do so: exportin through RSS or using javascript. Be aware that some copyright issues may arise in case you re-publish copyrighted content.

Share using the RSS feed export

You can share the news from a subscription list via an RSS 2.0 feed of the aggregation.
The subscription list becomes a channel in itself, with a Feed URL, just like all the channels of your subscription list. The URL of the feed looks like
ZF_URL?f=rss&zflist=LIST
Where ZF_URL is the value set in the configuration page, telling at what URL ZebraFeeds is installed. and LIST is the subscription list name (possibly URL encoded).
This URL can be used to subscribe in any other online/offline news aggregator (including ZebraFeeds itself!) So that the readers of your web site can subscribe to your aggregated news.

Look at demo_rssfeed.php to see how to customize your feeds.

Share using the javascript export

You can publish ZebraFeeds aggregations on any website using the Javascript export.
Just include this line in the body of the page where you want to display your feeds
<script type="text/javascript" src="ZF_URL?f=js&zflist=LIST&zftemplate=TEMPLATE"></script> 
Where ZF_URL is the URL to the installed ZebraFeeds, LIST is the subscription list you want to include, and TEMPLATE the template to use for display.
Please note that if the template contains a style sheet in the templateHeader section, then the feed won't be displayed properly. So make sure to use a template that doesn't require a style sheet.
If the template references CSS classes from the embedding page, the feed will integrate more nicely into the page.

Take a look at demo_js.html for a concrete example.

Refresh feeds by cronjob

See the configuration page of the Administration panel to set up "On request" feed refresh mode.
After selecting this option and saving the config, you'll be provided with a link whose url must be fetched at regular intervals in order to refresh the newsfeeds

Two aspects to take into account:
This feature requires to setup an admin user and password, therefore, the link will change whenever the admin name or password changes.

Mark new items

ZebraFeeds can optionally highlight news items which are more recent that the visitor's last visit.
To achieve this, it must record the time of last visits of visitors. This can be done in 2 ways To mark new items on the generated html content, you have to include the template tag {isnew} in your template (see below).

Manual mode

By default, feeds are displayed where zebrafeeds.php is included. If you enable the manual mode, the feed rendering only happens where (and if) you make use of the ZebraFeeds public functions.
Manual mode allows full control of Note: if you choose not to use OPML lists, the manual mode is the only way to display anything with ZebraFeeds.
Feeds selection
These functions configure what feeds to aggregate.
News filtering
Rendering and presentation
By default, ZebraFeeds presents the news sorted by channel using the template defined in the admin panel, unless you call: Finally, call
zf_renderView
to render the aggregated newsfeeds. It must be called after all the others.
If you want to generate another aggregation block on your page, call
zf_reset
to restart from scratch. See the demo_manual.php script for more details and examples. See includes/controller.php script for a detailed list of functions and their parameters.

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 with special tags, in sections to be interpreted by ZebraFeeds. Templates file names have must have the html extension to be recognised.
Sections should contain tags so that the parser can format the actual data into them.

Template sections

How sections are rendered

When sorted by feed, the output is generated this way:
  • header
  • For each feed
    • channel
    • for each news item
      • news
    • channelFooter
    • between
  • 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
  • listHeader (with list name taken as channel name)
  • For each day
    • newsDay
    • For each news item
      • newsByDate (or news if empty)
    • newsDayFooter
  • listFooter
  • footer
The following tags are supported in the sections. 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 zebrafeeds.php is included on your page. (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 embedded in the news list thanks to the {articleurl} template tag.

Channel tags

News item and article tags

News day tags

Special tags

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

Special feature : dynamic browsing

To take advantage of AJAX to dynamically fetch news from your site as you want to read them, and not get all of them sent every time you load the page, you can use this kind of code in the "news" section of the template.
 <span onClick="showItem('{feedurl}','{itemid}');">{title}</span>
See the infojunkie,twopane and newsflow, templates for details and examples.

Configuration file reference

This sections lists the options available in config.php file as well as through the administration interface.

General options

ZF_LOGINTYPE: server - server HTTP auth; session - PHP sessions auth
ZF_HOMEURL: URL to your website. It'll be used to as publisher link in RSS feeds that ZebraFeeds generates.
ZF_URL: URL to ZebraFeeds directory installation. Very important
ZF_ADMINNAME: admin username
ZF_ADMINPASS: crypted (md5) admin password, default is "admin". If set to empty, the admin pages authentication is disabled, and one 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_USEOPML: if yes the subscription file will be used, else use the manual feed configuration
ZF_HOMELIST: name of the feed list to be displayed by default (taken from the subscriptions directory which holds the subscriptions data)
ZF_REFRESHMODE: "automatic" to let ZebraFeeds manage this, or "request", to disable automatic refresh and use a 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 yoyur 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

Advanced options

ZF_NEWITEMS: No: doesn't highlight new items, client: highlights new items for each visitor (cookie based). server: highlights new items since last refresh (common to all users) ZF_RENDERMODE: "automatic" to have ZebraFeeds spontaneously display aggregated news, or "manual", to disable automatic refresh and use the manual functions
ZF_NOFUTURE: if yes then ZebraFeeds will silently discard news carrying a date in the future
ZF_OWNERNAME: owner name which will appear in the OPML file. Used in title of exported RSS feed, so put your web site address here (optional)
ZF_OWNEREMAIL: owner email which will appear in the OPML file (optional)

Hidden options

These options are not settable through the admin page, but directly editing init.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_DYNAMICNEWSLENGTH: news longer than this (in characters) will be dynamically obtained using AJAX. 0 to disable. Requires compatible templates.
ZF_SESSION_DURATION: time in seconds before unmarking items as new (default 900)
ZF_VISITOR_COOKIE_EXPIRATION: expiration time of cookie set to visitors to trace down last visit
ZF_FORCE_ENCODED_CONTENT: only for magpieRSS 'yes' (default) or 'no', if yes, displays the encoded version of the news (usually with images) if the feed contains it.
Stored in cache. if this is changed, it will be active only after cache is refreshed.
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_RSSEXPORTSIZE: number of items to export in the RSS feed