====== Changes Plugin ======
 
---- plugin ----
description: List the most recently changed pages and media-files of the wiki
author     : Andreas Gohr
email      : dokuwiki@cosmocode.de
type       : syntax
lastupdate : 2023-12-14
compatible : Elenor Of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum
depends    : 
conflicts  : 
similar    : querychangelog, recent
tags       : changelog, listing

downloadurl: https://github.com/cosmocode/changes/zipball/master
bugtracker : https://github.com/cosmocode/changes/issues
sourcerepo : https://github.com/cosmocode/changes
----

This plugin allows you to embed the list of recent changes as a simple list into any page.

===== Download and Installation =====

[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ https://www.cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]

Download and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Syntax and Usage =====

The list is created using the following syntax:

  {{changes>}}

Optionally you can specify a number of parameters that control the scope of the shown changes and the way the list is rendered.

:!: The plugin always displays only the most recent change for every page / media file!

==== Allowlist/blocklist by namespace ====
By default plugin shows the changes in the entire wiki. To restrict the list of changes to a given namespace and its sub-namespaces you can specify its name either directly or using ''ns'' parameter:

  {{changes>foo}}
  {{changes>ns=foo}}

The ''ns'' parameter supports both inclusion and exclusion of the namespaces. If a namespace name starts with a minus sign that namespace will be excluded. Also you can assign a number of namespaces as a comma separated list:

  {{changes>ns = -foo}}
  {{changes>ns = foo, bar, -bar:baz}}

The first example will show the changes in all namespaces except of "foo", the second one will include "foo" and "bar" namespaces except of "bar:baz" sub-namespace.

You can also exclude specific pages:
  {{changes>foo&excludedpages=bar}}

==== Number of changes displayed ====

The number of changes that are presented in the list is controlled with ''count'' parameter (defaults to 10). The count can also be specified as just a number:

  {{changes>15}}
  {{changes>count=15}}

==== Type(s) of changes displayed ====

It is also possible to control the type of changes shown in the list. By default all types are shown but with ''type'' parameter you can restrict the shown changes to a given type. The supported types are ''create'', ''edit'', ''minor'' and ''delete''. Multiple types can be specified separated by a comma:

  {{changes>type = create}}
  {{changes>type = edit, minor}}

==== Allowlist/blocklist changes by user ====

To show only changes by particular users, the ''user'' parameter takes a comma-separated list of usernames:

  {{changes>user = rauschen}} 
  {{changes>user = rauschen, andi}}
  
Exclusion of particular users is also possible using the ''excludedusers'' parameter, which also takes a comma-separated list of usernames:

  {{changes>excludedusers = FosseWay}}
  {{changes>excludedusers = FosseWay, andi}}

==== Maximum age of change displayed ====

Filtering by age is possible, too. Just specify the maximum age in seconds. However, please note that this plugin can not display changes older than [[config:recent_days]].

  {{changes>maxage = 500}}

==== Output renderer ====

The changes can be rendered either as a simple list (default) or using [[:plugin:pagelist|Pagelist]] plugin. You have to install the Pagelist plugin separately, if it's not available the simple list is used instead. The renderer is selected with the "render" parameter:

  {{changes>render = list}}
  {{changes>render = pagelist}}

The renderers can have extra parameters (a.k.a. [[plugin:pagelist#flags]]), which can be passed within parenthesis as a comma-separated list:

  {{changes>render = list(signature)}}
  {{changes>render = pagelist(header, nouser)}}
  {{changes>ns = foo,  bar, -bar:baz&render = pagelist}}
  {{changes>type = create&render = list(dayheaders, signature, nocomments, nouser)}}

The built-in list renderer supports the following parameters:

  * ''summary'', ''nosummary'' --- show/hide the change summary.
  * ''signature'', ''nosignature'' --- show/hide user name and time of the change.
  * ''dayheaders'' --- Group changes by a heading (date of the change).
  * ''nocomments'' --- Disable comment count if [[plugin:discussion|Discussion]] is installed.
  * ''nouser'' --- do not show user column in the list.
  * ''nodesc'' --- nodescription (if you have Pagelist plugin)

By default only the summary is shown. For the list of parameters supported by Pagelist plugin refer to its [[:plugin:pagelist#flags|documentation]].

==== Multiple parameter syntax ====

If you want to pass a number of parameters to the plugin they should be separated with an ampersand, for example:

  {{changes>foo&15&type=create&user=rauschen}}

The above syntax would display the last 15 pages created by user rauschen inside the "foo" namespace. 

==== ACL compatability ====

Note: The plugin respects [[:ACL]] permissions but output is cached with the page it is in until a new change was made. If you're listing ACL dependent changes use the %%~~NOCACHE~~%% macro in the page you're using this plugin.

==== Username fallback ====

The plugin attempts to describe the user who made each change in the following order:
  - If possible, the descriptive username is displayed, e.g. ''Joanna Schmidt''
  - If descriptive username is unavailable((Under certain circumstances, some auth methods may be unable to provide descriptive username. For instance, authentication against a corporate AD server, where the AD server may return minimal details, and this is outside the control of the wiki administrator.)), login ID is displayed, e.g. ''joanna.schmidt''
  - If no user information is provided to the Changes plugin by auth, the IP address the change was made from is displayed. This will likely be the case for an anonymous edit.

===== Development =====

A public git repository is available at https://github.com/cosmocode/changes

==== Changelog ====

{{rss>https://github.com/cosmocode/changes/commits/master.atom date}}

==== Bugs and feature request ====

Please report issues in the bug tracker at https://github.com/cosmocode/changes/issues