====== XML Syndication ======

[[DokuWiki]] maakt een deel van haar data beschikbaar als XML feed via [[this>feed.php]]-bestand. De feed kan worden toegevoegd aan een [[wp>Aggregator|nieuwslezer]].

De XML Syndication functie is geïmplementeerd door de uitmuntende [[http://www.bitfolge.de/rsscreator-en.html|Feed Maker Class]] te gebruiken geprogrammeerd door Kai Blankenhorn.

===== Configuratie/URL Opties =====
Hoe de feed wordt samengesteld kan worden ingesteld door verschillende configuratieopties. Als feed.php wordt opgevraagd zonder een extra paramaters zal het deze opties gebruiken om de feed samen te stellen. Alle opties kunnen overschreven worden door parameters aan de URL toe te voegen.

==== Links ====

Elk item in de aangemaakte feed zal een link hebben; deze optie specificeert waar deze link naar wijst.

  * **Configuratieoptie:** [[config:rss_linkto]]
  * **URL-parameter:** linkto
  * **Standaard:** diff
  * **Mogelijke waarden:**

^ Waarde   ^ Linkdoel ^
| page    | de revisie van de pagina toen de feed gemaakt werd |
| current | de meest actuele versie van de pagina |
| rev     | de revisieoverzicht van de pagina |
| diff    | een [[diff]]-weergave van de paginawijzigingen |

==== Feed-inhoud ====

Wat in de itemblokken van de feed wordt weergegeven wordt met deze optie ingesteld.

  * **Configuratieoptie:** [[config:rss_content]]
  * **URL-parameter:** content
  * **Standaard:** abstract
  * **Mogelijke waarden:**

^ Waarde    ^ Iteminhoud ^
| abstract | De eerste paragraaf van een pagina |
| diff     | een kale tekst diff van de paginawijzigingen |
| htmldiff | een HTML-opgemaakte diff tabel van de paginawijzigingen |
| html     | de volledige in HTML omgezette paginainhoud |

==== Feed-formaat ====

DokuWiki kan de XML-feed samenstellen in meerdere formaten.

  * **Configuratieoptie:** [[config:rss_type]]
  * **URL-parameter:** type
  * **Standaard:** rss1
  * **Mogelijke waarden:**

^ Waarde  ^ Feed-formaat ^
| rss    | RSS 0.91 |
| rss1   | RSS 1.0  |
| rss2   | RSS 2.0  |
| atom   | ATOM 0.3 |
| atom1  | ATOM 1.0 |

==== Lijstmode ====

feed.php kan worden gebruikt voor de uitvoer van een lijst van de recente aanpassingen (standaard) maar ook voor andere lijsten. 

  * **Configuratieoptie:** none
  * **URL-parameter:** mode
  * **Standaard:** recent
  * **Mogelijke waarden:**

^ Waarde   ^ Lijstmode ^
| recent  | lijst van de meestrecente pagina's met de nieuwste bovenaan |
| list    | simpele lijst van alle pagina's van een namespace (zie hieronder voor een selecteren van welke namespace)  |
| search  | lijst van pagina's die overeenkomen met een bepaalde zoekopdracht gegeven door een extra URL-parameter ''q'' |

==== Namespacefilter ====

De feed kan worden beperkt tot het weergeven van pagina's uit één bepaalde namespace. 

  * **Configuratieoptie:** none
  * **URL-parameter:** ns
  * **Standaard:** *
  * **Mogelijke waarden:** elke geldige namespace

In [[#list mode]] ''list'', the feed will contain pages from the given namespace only, no sub namespaces.

In [[#list mode]] ''recent'', sub namespaces are included.

Namespace limitation is not directly supported for the [[#list mode]] ''search''. Instead you can give a namespace limitation in the query (using the ''@'' syntax) -- this however **will** include sub namespaces.

==== Item Limits ====

The number of pages listed in the feed can be controlled as well.

  * **Configuratieoptie:** [[config:recent]]
  * **URL-parameter:** num
  * **Standaard:** 20
  * **Mogelijke waarden:** any integer

==== Including Minor Edits ====

By default no minor edits will be shown in the feed. This can be changed by an URL argument.

  * **Configuratieoptie:** none
  * **URL-parameter:** minor
  * **Standaard:** 0
  * **Mogelijke waarden:** 0 or 1

==== Caching  ====

XML feeds are cached to reduce the load on the wiki. This option controls how long feed caches are valid.

  * **Configuratieoptie:** [[config:rss_update]]
  * **URL-parameter:** none
  * **Standaard:** 5*60
  * **Mogelijke waarden:** time in seconds

==== Summaries ====

The [[summary]] of a page change will usually be included in the feed item title. This might be unwanted sometimes and can be disabled.

  * **Configuratieoptie:** [[config:rss_show_summary]]
  * **URL-parameter:** none
  * **Standaard:** 1
  * **Mogelijke waarden:** 0 or 1

===== Examples =====

  * [[this>feed.php?type=rss2&num=5]] returns a [[http://backend.userland.com/rss|RSS 2.0]] feed of the 5 most recent changes
  * [[this>feed.php?mode=list&type=atom&linkto=page&ns=wiki]] list all pages in the wiki namespace as an [[http://intertwingly.net/wiki/pie/FrontPage|ATOM 0.3]] feed with all items linking to the page directly

===== Feeds and ACLs =====

When ACLs are enabled, read restricted pages will **not** be included in public feeds.

If you want to access feeds for restricted pages you have to pass your username and password along in the URL like this: %%''http://example.com/dokuwiki/feed.php?u=username&p=password''%%.

:!: This is not very secure and might lead to the leakage of your user credentials. When DokuWiki is running atop of ''mod_php'' passing login credentials via HTTP Basic Auth as supported by some newsreaders might work as well.

==== Approach with .htusers ====

For my configuration (dokuwiki 2008-05-05 and [[http://liferea.sourceforge.net/|Liferea]]) the HTTP Basic Auth approach did not work out of the box. It seems that the authentication was not happening because the web server did not ask for it. So I forced this by creating a .htusers file (out of the dokuwiki user information) and restrict the access to feed.php:

I used the following simple script to generate a htusers file (used by apache) out of dokuwikis user data:

  user@host# cat <<EOF > update_htusers
  #!/bin/sh
  grep -v '^#' users.auth.php |  cut -sd\: -f1,2 > .htusers
  EOF
  user@host# chmod +x update_htusers
  user@host# ./update_htusers
  

Add to your existing .htaccess in dokuwiki main folder:

<code apache>
  AuthType Basic
  AuthName "feed"
  AuthUserFile path-to-your-htusers-file
  <Files feed.php>
    Order deny,allow
    require valid-user
  </Files>
</code>

===== See also =====

  * [[rss|RSS/ATOM Feed Aggregation]] for adding external feeds to your DokuWiki pages
  * The [[plugin:feed|feed plugin]] for more ways to export your [[plugin:blog]] posts via RSS
  * Tips on [[tips:blogging#feed_setup|feed setup]] when blogging with DokuWiki
  * The [[plugin:Feedauth]] plugin sends an "authorization required" header in the feed, for some clients needed.