From d76b7e16f70b7f1337f0636516c687dc02d7b77b Mon Sep 17 00:00:00 2001
From: Frederic Guillot <fred@kanboard.net>
Date: Mon, 1 Feb 2016 20:51:52 -0500
Subject: Add documentation for external links plugin API

---
 doc/plugin-external-link.markdown | 78 +++++++++++++++++++++++++++++++++++++++
 doc/plugins.markdown              |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 doc/plugin-external-link.markdown

diff --git a/doc/plugin-external-link.markdown b/doc/plugin-external-link.markdown
new file mode 100644
index 00000000..36252aff
--- /dev/null
+++ b/doc/plugin-external-link.markdown
@@ -0,0 +1,78 @@
+External Link Providers
+=======================
+
+This functionality allows you to link a task to additional items stored on another system.
+
+For example, you can link a task to:
+
+- Traditional web page
+- Attachment (PDF documents stored on the web, archive...)
+- Any ticketing system (bug tracker, customer support ticket...)
+
+Each item has a type, a URL, a dependency type and a title.
+
+By default, Kanboard includes two kinds of providers:
+
+- Web Link: You copy and paste a link and Kanboard will fetch the page title automatically
+- Attachment: Link to anything that is not a web page
+
+Workflow
+--------
+
+1. The end-user copy and paste the URL to the form and submit
+2. If the link type is "auto", Kanboard will loop through all providers registered until there is a match
+3. Then, the link provider returns a object that implements the interface `ExternalLinkInterface`
+4. A form is shown to the user with all pre-filled data before to save the link
+
+Interfaces
+----------
+
+To implement a new link provider from a plugin, you need to create 2 classes that implement those interfaces:
+
+- `Kanboard\Core\ExternalLink\ExternalLinkProviderInterface`
+- `Kanboard\Core\ExternalLink\ExternalLinkInterface`
+
+### ExternalLinkProviderInterface
+
+| Method                     | Usage                                                           |
+|----------------------------|-----------------------------------------------------------------|
+| `getName()`                | Get provider name (label)                                       |
+| `getType()`                | Get link type (will be saved in the database)                   |
+| `getDependencies()`        | Get a dictionary of supported dependency types by the provider  |
+| `setUserTextInput($input)` | Set text entered by the user                                    |
+| `match()`                  | Return true if the provider can parse correctly the user input  |
+| `getLink()`                | Get the link found with the properties                          |
+
+### ExternalLinkInterface
+
+| Method            | Usage            |
+|-------------------|------------------|
+| `getTitle()`      | Get link title   |
+| `getUrl()`        | Get link URL     |
+| `setUrl($url)`    | Set link URL     |
+
+Register a new link provider
+----------------------------
+
+In your `Plugin.php`, just call the method `register()` from the object `ExternalLinkManager`:
+
+```php
+<?php
+
+namespace Kanboard\Plugin\MyExternalLink;
+
+use Kanboard\Core\Plugin\Base;
+
+class Plugin extends Base
+{
+    public function initialize()
+    {
+        $this->externalLinkManager->register(new MyLinkProvider());
+    }
+}
+```
+
+Examples
+--------
+
+- Kanboard includes the default providers "WebLink" and "Attachment"
diff --git a/doc/plugins.markdown b/doc/plugins.markdown
index f3f922f3..55575612 100644
--- a/doc/plugins.markdown
+++ b/doc/plugins.markdown
@@ -21,6 +21,7 @@ Plugin creators should specify explicitly the compatible versions of Kanboard. I
 - [Authentication plugin registration](plugin-authentication.markdown)
 - [Authorization Architecture](plugin-authorization-architecture.markdown)
 - [Custom Group Providers](plugin-group-provider.markdown)
+- [External Link Providers](plugin-external-link.markdown)
 - [LDAP client](plugin-ldap-client.markdown)
 
 Examples of plugins
-- 
cgit v1.2.3