news Plugin

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

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:

~~NEWSFEED~~
~~NEWSFEED:<n>~~

~~NEWSFEED~~

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'

~~NEWSFEED:<n>~~

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:

~~NEWSFEED:3~~

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.

~~NEWS_REFRESH~~

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.

1. place newsfeed.php in your top level dokuwiki directory and point your news reader to that script This method adheres to the ttl (time-to-live) configuration setting (see Options below) and creates a new xml file only after the ttl has expired. Until the expiry time, it reads and outputs the previously created news_feed.xml. However, you can force a new feed to be created by method 2 or 3.
2. place newsfeed.php in lib/exe and generate the feed from the command line: 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.
3. open the news admin panel and click on the Generate Feed button. This method by-passes the time-to-live setting and generates a new feed whenever activated.
4. add a per-page refresh button

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:

http:/my_web_site.org/my_dokuwiki/newsfeed.php

If you use method 2 or 3 and do not implement method 1, then your url must be:

http:/my_web_site.org/my_dokuwiki/news_feed.xml
         

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

 ~~NEWS_REFRESH~~

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.

~~NOCACHE~~

~~NEWS_REFRESH~~

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:

~~NEWSFEED:feed_name~~
~~NEWSFEED:<n>;;feed_name~~         

Both of the following will be assigned to the same newsfeed:

~~NEWSFEED:department_1~~
~~NEWSFEED:3;;department_1~~

Both will both appear in the newsfeed for department_1. You could just as easily provide newsfeeds for users:

~~NEWSFEED:jones~~

These are the only changes to the basic syntax.

The syntax for individual news items remains the same as described above.

• ~~NEWSFEED:feed_name~~ uses the syntax which marks up individual items between
  <news>. . .</news>
  tags as described under first form.
• ~~NEWSFEED:<n>;;feed_name~~ uses the header form described under second form.

The basics of generating feeds remains as described above, but with changes that enable creating multiple feeds.

1. All feeds can be generated from the administration panel, which comes with instructions. Using the administration panel you can create and update the feeds for each feed name.
2. You can use the refresh button with an extended syntax.
3. Or you can use the command line in lib/exe and pass it the feed name.
4. Or you can access the feed with a URL pointing to newsfeed.php in the top level directory. The URL requires the addition of the feed name in the query string.

Query string syntax:

http://yourdomain.com/your_wiki/newsfeed.php?feed=feed_name

Command line syntax:

php newsfeed.php feed_name

Refresh button syntax:

~~NEWS_REFRESH:feed_name~~

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:

feed_name_news.xml

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.

1. 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.
2. title: Feed Title
3. desc: Feed Description
4. url: Site Url (This should be set if you are going to generate feeds from lib/exe/newsfeed.php)
5. 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.

Permission Settings

1. mgr: Name of group which has permission to create newsfeeds
2. adminsonly: Check this box if only adminstrators and managers can create feeds.
3. chkperm: Check this box to use the news plugin's permission system.

The above permissions settings have the following hierarchy:

1. if chkperm is false, then only ACL's control access to the newsfeed.
2. adminsonly has highest precedence; when this is set the mgr group is ignored
3. mgr : if adminsonly is not set then the mgr group is checked
4. if neither the mgr group or adminsonly is set, then access to the newsfeed is governed by Dokuwiki's ACL's. This is the same as though chkperm is 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 Configuration Settings.

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:
  • Corrected for misspelled $this in 07 Jul 2016 update.
  • Convert old constructors to __construct in scripts for PHP 7
• 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:
  • Generating feed from admin panel did not pick up the feed title and feed description. This is now fixed.
  • Return DOKU_URL from feedData::news_feed_url() when the server data is not available (the case for writing out the channel).
• 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:
  • Added a per-page news feed refresh button;
  • Added German language support (with thanks to Taggic)
• 19 Oct 2011:
  • Removed newlines and spaces from button.php that caused premature header error in OS X
  • Upgraded output from per-age refresh button as described above
  • restricted per-page button to users with at least edit permission for the page where the refresh syntax appears

If possible, please direct discussion to the forum.