====== Linkback Plugin ======


===== Description =====

The linkback plugin adds [[wp>Trackback]] and [[wp>Pingback]] support to DokuWiki. This includes autodiscovery of track- and pingback-URLs on websites linked via an external or internal link and then sending the actual linkback as well as receiving and displaying received linkbacks. An expandable spamfilter provides protection from trackback and pingback spam. Currently, this includes
  * a check whether the count of links in the excerpt exceeds a configurable amount,
  * a check of the excerpt against the DokuWiki wordblock list,
  * a check whether the ip of the linking page is equal to that of the submitter (moderation instead of instant deletion is enabled by default for this check, you should keep it like that),
  * a check whether the linking page includes a link to the linked page in case of a trackback (where this check is not part of the protocol as compared to pingbacks) and
  * support for using the [[http://www.akismet.com|Akismet]] webservice to check linkbacks for spam (disabled by default, you need an Akismet API key to use this feature. You can get one by registering for a blog at [[http://www.wordpress.com|Wordpress.com]]).

<note classic>It should be noted that the badbehaviour library which is incorporated into the [[http://wiki.splitbrain.org/plugin:badbehaviour|badbehaviour]] plugin does not seem to be very friendly to anything remotely resembling a trackback or a pingback((HTTP Range headers for probing for ping URLs are prohibited/forced into omitting the first byte, most of the user agents used by blog software is prohibited, ...)) and thus will probably lead to the linkback plugin not working as intended. I'll try to look into it though.</note>

In case you come across any bugs, please don't hesitate to [[http://flyspray.foosel.net/index.php?tasks=all&project=6|report them]].

The Darcs repository of the plugin can be found [[http://devel.foosel.org/darcsweb/darcsweb.cgi?r=dokuwiki/linkback;a=summary|here]].

===== Updates =====

  * 2008/04/06
    * Fixed: 
      * Akismet plugin was not called properly
      * Don't allow usage of syntax in comments
      * Minor cosmetic bugs
    * Added:
      * Logging system to log processing of incoming linkbacks. Antispam plugins can add own processing information via event-data
      * Additional antispam plugin to check if incoming trackbacks contain a link back to page  
      * Option for displaying trackback URL for manual trackbacks
      * Admin component for bulk moderating linkbacks
      * URL of pinged page is now included in notification mail
    * ''exe/trackback.php'', ''exe/pingback.php'' and ''action/display.php'' now use the pluginutils to load the ''tools'' plugin
    * Use strftime() instead of date()
    * Change to new form handling in Dokuwiki
  * 2007/04/12:
    * Receiving and displaying of received linkbacks added, sending improved
  * 2007/04/07:
    * Initial release of the first prototype


===== Installation =====

You need version 2008-05-05 for this plugin to work.

==== With plugin manager ====

Let the manager do the dirty work, just give him this link to eat: {{plugin-linkback.tar.gz}}

==== Without plugin manager ====

  - Download the plugin: {{plugin-linkback.tar.gz}}
  - Extract it into your dokuwiki plugin folder (eg ''lib/plugins'')

===== Usage =====

In order to send linkbacks from a wiki node, activate the corresponding checkbox in the editform.

The receiving and display of received linkbacks is handled by the syntax plugin. The following commands are recognized:
  * **''~~LINKBACK~~''**: Receive and display linkbacks.
  * **''~~LINKBACK:closed~~''**: Display already received linkbacks but don't receive new ones.
  * **''~~LINKBACK:off~~''**: Neither receive nor display linkbacks. Use this to disable linkback support in an already linkback-enabled wiki node.

===== Adding new spamfilters =====

==== Events ====

The linkback plugin introduces three new events to allow for extension of it's antispam-mechanisms by action plugins. These events are:

=== ACTION_LINKBACK_RECEIVED ===

^ Name | ACTION_LINKBACK_RECEIVED |
^ Data | <code>
$data['linkback'] -- The linkback data as documented below
$data['page']     -- The html source as fetched from the pinging site
$data['target']   -- The wiki page that got pinged
$data['show']     -- Whether to show the linkback, defaults to true and can 
                     be set in action plugins to moderate the linkback
$data['log']      -- An array of lines that make up the linkback log of the 
                     received linkback. Antispam plugins can add their own 
                     logging output by appending lines to this array.
</code> |
^ Action | Sets the ''show'' property of the received linkback to the value defined in the event's ''data'' and then saves the linkback. |
^ Preventable  | yes |
^ Signalled | by ''exe/trackback.php'' and ''exe/pingback.php'' before saving the new linkback |

Action plugins can register for this event to filter incoming linkbacks using both the actual linkback data as well as the source of the pinging page.

=== ACTION_LINKBACK_HAM ===

^ Name | ACTION_LINKBACK_HAM |
^ Data | the linkback data |
^ Action | none |
^ Preventable  | no |
^ Signalled | by the handler of the ''Report as Ham'' button of the linkback-listing (''action/display.php'') |

In order to report a linkback as ham (e.g. to antispam plugins using classifiers), action plugins can register for this event.

=== ACTION_LINKBACK_SPAM ===

^ Name | ACTION_LINKBACK_SPAM |
^ Data | the linkback data |
^ Action | none |
^ Preventable  | no |
^ Signalled | by the handler of the ''Report as Spam'' button of the linkback-listing (''action/display.php'') |

In order to report a linkback as spam (e.g. to antispam plugins using classifiers), action plugins can register for this event.

==== Linkback data ====

Each linkback item is represented as a hash which stores the following properties:

  * **''lid''** -- internal id of the linkback
  * **''title''** -- title
  * **''url''** -- url
  * **''raw_excerpt''** -- small excerpt of the linking page (exactly as received in the linkback)
  * **''excerpt''** -- small excerpt of the linking page (html tags stripped)
  * **''blog_name''** -- name of the linking page
  * **''favicon''** -- url of the linking page's [[wp>Favicon|favicon]], or false if none could be found
  * **''received''** -- timestamp of the date the linkback was received
  * **''submitter_ip''** -- ip of the submitter
  * **''submitter_useragent''** -- useragent of the submitter
  * **''submitter_referer''** -- referer of the submitter
  * **''type''** -- type of the linkback, can be either ''trackback'' or ''pingback''
  * **''show''** -- true if the linkback should be visible to everyone, false if it should be visible only to admins. Antispam plugins can set this to false in order to moderate a suspicious linkback.

~~DISCUSSION~~
~~LINKBACK~~