Learn about DokuWiki
Learn about DokuWiki
This plugin creates an RSS2 news feed from Dokuwiki pages that can be read in a standard news reader. It represents its news items rendered from Dokuwiki pages as HTML and should display images and media links correctly.
This plugin does not create diffs.
Sample Page: http://www.mturner.org/fckgLite/news_feed.xml
The above will present the feed as a single page, until fed through a news reader.
There are two forms of markup. At the top of a page that holds new items, you must place one of the following:
If you use the first form, then you bracket your news items with the following markup:
<news: item_title> blah blah </news> <news: another_item> blah blah </news>
The news reader will use your title for the item. Please note that the colon after
news is required.
You can omit the title:
<news:> blah blah </news>
In this case the title will default to 'News Item'
In this form, the news items are generated from material which is preceded by Dokuwiki header markup, and the headers become the titles of the news items. The <n> designates the number of equal signs that mark up your headers. The plugin will create news items from all headers greater than or equal to n. For instance:
will create items from all headers with with three or more equal signs:
=== header 1 === ==== header 2 ====
This is particularly useful if you have a page which is dedicated to news items.
See below refresh button
The primary script for generating news feeds is
newsfeed.php, which is found in news/scripts. The news feed file is named
news_feed.xml. Each of the following methods generates the xml news feed in your top level dokuwiki directory.
news_feed.xml. However, you can force a new feed to be created by method 2 or 3.
php newsfeed.php; if you have already generated a news feed using one of the other methods, then the generated news feed file (
<dokuwiki>/news_feed.xml) will be owned by the web server and you will need permission to over-write it (if you own the directory you should be able to delete
news_feed.xml). The drawback to this method is that the web server may not be able to recreate the newfeeed using method 1 or 3, unless you change the permission of news_feed.xml to allow the server write access.
Generate Feedbutton. This method by-passes the time-to-live setting and generates a new feed whenever activated.
For all of these methods, you must give the web server write permission to the topmost directory of your Dokuwiki installation. Otherwise, when the time-to-live period has expired, the new feed will fail to be created.
if You use method 1, then your news feed url is:
If you use method 2 or 3 and do not implement method 1, then your url must be:
You can generate a new feed by adding a refresh button to any page. To use this method newsfeed.php must be in your top level dokuwiki directory. Clicking this button causes newsfeed.php to run and works the same way as the
Generate Feed button in the admin panel, i.e. it by-passes the time-to-live setting and immediately re-creates a new feed.
The syntax for this button is
This syntax will be replaced on Save by the
Feed Refresh button. When using this button, you should also include on your page the ~~NOCACHE~~ directive. Doing so insures that the button appears on the page only when a registered user is logged in.
When the per-page button is clicked, it runs newsfeed.php in the wiki's root directory and outputs a page to the browser which indicates whether or not the feed has been successfully re-generated. The page will display a return link to the page from which the feed generation originated.
The refresh button will only appear on pages where the user has edit permission.
The multi-user branch of the news plugin has been merged with the original single-user version. The original implementation of the news plugin was designed to produce only one feed per Dokuwiki installation. The current version allows for multiple feeds, which can come from any single user or multiple of users. It does this by extending the syntax described above. That is, the above syntax will still work and will give you a single feed. But if you want additional feeds, then you need the new extensions.
Also, this version gives admins the option of setting additional controls over who can and cannot create newsfeeds, in addition to Dokuwiki's ACLs. For this it uses three additional configuration options. They are described under the Configuration Settings below.
The basic syntax is as described above with the addition of a unique feed name for each feed. The feed name must be lower-case, cannot contain spaces and must conform generally to Dokuwiki's naming convention. The news plugin will not normalize names that do not conform to Dokuwiki's naming convention. The syntax is as follows:
Both of the following will be assigned to the same newsfeed:
Both will both appear in the newsfeed for
department_1. You could just as easily provide newsfeeds for users:
These are the only changes to the basic syntax.
The syntax for individual news items remains the same as described above.
The basics of generating feeds remains as described above, but with changes that enable creating multiple feeds.
feed namein the query string.
Query string syntax:
Command line syntax:
php newsfeed.php feed_name
Refresh button syntax:
The resulting feed for all of these options will be output to the top-level directory of your dokuwiki installation and will have a name identified by the feed name:
If the feed fails, you probably have not given the web server write permission to the top-level directory. You can test for this by adding
&test=test to your url when accessing the feed from a browser.
ttl: Number of minutes before a new feed will be automatically generated. The default is 720 minutes (12 hours). The ttl value is used only when accessing a feed from a url in the browser. Otherwise, feeds are re-built when accessed from a “Refresh” button, from the command line in lib/exe, or from the “Generate” button of the administration panel. This makes it possible to publish news items as soon as they have been posted.
title: Feed Title
desc: Feed Description
url: Site Url (This should be set if you are going to generate feeds from lib/exe/newsfeed.php)
createtime: If true, retain the original file creation date as the publication date, instead of the date of last revision (defaults to false)
For both the Feed Title and the Feed Description fields, the default is
DokuWiki News Feed.
mgr: Name of group which has permission to create newsfeeds
adminsonly: Check this box if only adminstrators and managers can create feeds.
chkperm: Check this box to use the news plugin's permission system.
The above permissions settings have the following hierarchy:
chkpermis false, then only ACL's control access to the newsfeed.
adminsonlyhas highest precedence; when this is set the
mgrgroup is ignored
adminsonlyis not set then the
mgrgroup is checked
adminsonlyis set, then access to the newsfeed is governed by Dokuwiki's ACL's. This is the same as though
chkpermis set to false.
The news plugin permissions have control only over who can create a newsfeed and not over who can access newsfeed pages. Dokuwiki's ACL settings govern who can and cannot edit and/or create documents. So, it is possible that a user can mark up a page as a news feed, but the news plugin will not process the markup until a valid newsfeed user re-saves it. Moreover, the latter should make a small edit, even the addition of a blank line. This overcomes the possibility of a cached page not being re-processed.
Each feed has a header title and subtitle (or description). These can be individualized for each feed by modifying the file
news/scripts/newsfeed.ini. This file uses the php ini file format:
;newsfeed.ini ; use the default entry as your template ; The title will appear at the top of the feed and the description as the subtitle ; do not remove default entry [default] title = "Dokuwiki News Feed" description = "Dokuwiki News Feed" [feed_name_1] title = "Our News Feed" description = "Dokuwiki News Feed for Department One" ttl = 60
You can add as many feed name entries as required, each with its own title, description, and ttl. If there is no entry for the feed, then the default will be used. You can change the default values for title and description but you must leave a
default entry. Lacking a default, i.e. if all else fails, the plugin will try to use the title and description settings in the
There is an Admin Panel where you can delete discontinued pages and generate a new news feed. See the Admin Panel for explanations and instructions.
10 Jul 2016
$thisin 07 Jul 2016 update.
07 Jul 2016 Added per-feed optional TTL setting. Patch from https://github.com/evacomaroski
14 Apr 2016 Implemented order sorting so that latest items come before oldest. This ensures newest to oldest in newsreaders that don't do their own date ordering.
22 Jan 2016: Adjust method signatures to match parent for php 7
6-7 Dec 2013: Added facility to insert individual titles and descriptions in headers of each feed created in one of the multi branches.
5 Dec 2013: Multi-user branch with permission controls
3 Dec 2013: Implemented multi-user branch
29 Aug 2011:
3 Sep 2011: Fixed incorrect time period calculation for feed expiry
10 Sept 2011: Fixed incorrect image links
14 Sep 2011: Set guid permalink attribute to true to help prevent duplication of items.
18 Oct 2011:
19 Oct 2011:
If possible, please direct discussion to the forum.