PLUGIN.txt in Freelinking 6.3

PLUGINS FOR FREELINKING VER. 3
==============================

Freelinking ver. 3 uses a plugin system to enhance the freelinking
syntax and enable different kinds of links. Plugins can be
simple URL constructors, or can use more sophisticated methods and
have complete control over the link and target text. The output of
plugins can also be customized through various hooks and theme
functions for better integration with other modules and site design.

Having a small set of generally useful "easy-linking" plugins bundled
with the project is only the first step Freelinking takes to help
authors create links.  Freelinking also has a framework that help
developers quickly create new "easy-linking" plugins for custom
websites.

Plugins can be created in two different ways. The recommended method
is to create a new module, as a submodule of freelinking.  However,
you may also create a plugin as an "include file".


SUBMODULE
---------

By packaging your plugin as a module, you may distribute it through
Drupal.Org, make use of other modules with proper tracking of
requirements, and make use of any Drupal hook functions without
worrying about collissions with Freelinking's own behavior.

If you publish your submodule on Drupal.Org, post a message in the
Freelinking Issue Queue: http://drupal.org/project/issues/freelinking
naming your project so it can be linked to from Freelinking's project
page.

A submodule can create a Freelinking plugin by implementing
hook_freelinking() to return the definition of your plugin as an
element of an array, like so:

  function my_module_freelinking() {
    $freelinking['myplugin'] => array(
      'indicator' => '/myplugin/',
      'translate' => array(' ' => '_'),
      'replacement' => 'http://example.com/node/%1',
    );
    return $freelinking;
  }


INCLUDE FILE
------------

To create a simple freelinking plugin, just drop a ".inc" file in the
plugins/ directory under Freelinking. By convention, these should be
named "freelinking_MYPLUGIN.inc", where "MYPLUGIN" is the name of the
plugin.

Each file should at least define one indicator, where the long version
of the indicator is identical to the name of the plugin.  However, it
is possible to define multiple plugin indicators per file to denote
slightly changed semantics.  See for example freelinking_wiki.inc for
an example of this.

The only difference in structure between an include file and a
submodule is the lack of a hook_freelinking() function wrapper around
the freelinking array that defines your plugin. In an include file,
the example above would simple be:

    $freelinking['myplugin'] => array(
      'indicator' => '/myplugin/',
      'translate' => array(' ' => '_'),
      'replacement' => 'http://example.com/node/%1',
    );

This functionality primarily exists for the ease of packaging default
plugins with the Freelinking module, and to allow developers to add
custom plugins to their site without going to the trouble of wrapping
it in a module.

However, if you create a format you think others may want to use,
please create a new issue ("Contributed plugin ...") and upload the
plugin code to the project's issue queue. It will be included as a
plugin with the next release if it passes community review.


THE $freelinking ARRAY
----------------------

Your plugin's element in the $freelinking array is named after your
plugin. In the example above of a plugin called "myplugin," the
element your plugin would add to the array would be
$freelinking['myplugin']. Your element defines an array, with the
following elements:

* 'indicator' [REQUIRED]
  The indicator is a string that defines a regular expression that
  will be used to differentiate this freelink from other freelink
  types. For our example, a good indicator value might be
  '/myplugin/'. This means that freelinks for this plugin will look
  like `[[myplugin:something]]`.  Freelinking uses the colon (":") as
  the separator between the indicator and the link text. It should not
  be part of the indicator string.

* 'translate' [OPTIONAL]
  This is an array of characters that can be used to translate
  characters in the link text to other characters that will be used in
  the URL. The primary use case for this is to translate spaces into
  underscores or dashes as different systems require. In the example
  of our "mike" plugin, the website uses dashes instead of spaces, so
  we'll use a value for 'translate' of `array(' ' => '-')`. For
  reference, this array will be run through the PHP function
  [strtr()](http://http://us.php.net/manual/en/function.strtr.php).

* 'replacement' [REQUIRED (unless 'callback' exists)]
  For simple URL replacement freelinks, the 'replacement' is a string
  for the URL, where the special string '%1' gets replaced by the link
  text in the freelink. For our example, if we're going to
  http://example.com/mike/something, we'd use the replacement string
  "http://example.com/mike/%1" and our freelink text would be put in
  place of the %1. If you are using a URL replacement style of
  freelink, the 'replacement' string is *required*.

* 'callback' [REQUIRED (unless 'replacement' exists)]
  More complex plugins can use a callback element in their array to
  define a php function that will be used to come up with the
  link. This function will be passed the entire match array of the
  freelink as $target, with the target portion of the freelink in
  `$target[1]`. This function is expected to return an html fragment
  (most likely a link, but it wouldn't have to be a link). If your
  plugin is not using 'replacement,' then the 'callback' element is
  *required.*

* 'settings' [OPTIONAL]
  The specified callback function for Freelinking settings. The
  settings function should return an array of Form API elements under
  the index of the plugin name.

* 'html' [OPTIONAL]
  If set explicitly to FALSE, the plugin will not accept HTML as link
  text.

* 'tip' [OPTIONAL]
  A short (1-2 sentence) description of the plugin. It should be run
  through t() for localization as demonstrated below. This is used in
  the extended filter tips, and the default plugin's description is
  added to the short tips.

* 'weight' [OPTIONAL]
  Specify the weight to determine sort order. Otherwise counts as "0".

* 'enabled' [OPTIONAL]
  If set to FALSE, the indicator for the plugin will be ignored. As
  such, syntax in the text will not activate the plugin. (Though
  failover will still be able to.)

* 'failover' [OPTIONAL]
  If this is set to an array, a select form will be built so the site
  administrator can determine a preferred failover action. This does
  nothing unless the developer follows up with
  variable_get('freelinking_pluginname_failover', 'none') in the
  callback code. If you set it to a single value, that value will be
  displayed in a disabled textfield in the configuration of the
  plugin.

So, a simple freelinking plugin only needs to include this
array. Here's an entire plugin one might see in a very simple .inc
file to link to a wiki page and some specific site:

  $freelinking['myplugin'] => array(
    'indicator' => '/my(plugin)/',
    'translate' => array(' ' => '-'),
    'replacement' => 'http://example.org/wiki/%1',
    'tip' => t('Link to a wiki page at example.org.'),
  );


MORE COMPLEX PLUGINS
--------------------

The 'callback' element of your $freelinking['plugin'] array can define
a PHP function that will be used to create the link. This function
will get the target value for the link, and is expected to return a
link.  Freelinking will make the substition based on the return value
of this function.

By default, the target value passed to the callback function looks like so:

  Array(
    'target' => ,
    'dest' => ,
  );

However, if the text uses pipes ("|"), it will interpret that somewhat
further. This is the expanded usage:

  Array(
    'target' => ,
    'dest' => ,
    'text' => ,
    'tooltip' => ,
    'other' => array(),
  );

The syntax is:

    [[indicator:target|title|tooltip|arg1|arg2|...]]

Two plugins that ship with freelinking use the callback, which you can
use as examples.

* freelinking_dev.inc
  This plugin turns freelinks like [[drupalorg:17570]] into links to
  nodes at "Drupal.org" by nid. This plugin uses the callback function
  to do a `drupal_http_request` to find the title of the page.
  Therefore, this plugin can be used as an example to manipulate the
  link text. This plugin also demonstrates a settings callback in
  which you can toggle whether this http_request is submitted.

* freelinking_nodetitle.inc
  This plugin mimics the behavior of previous versions of freelinking.
  It attempts to find a node on the system with the same title as the
  target, and either creates a link to that content, or a link to a node
  creation form to create that content. This plugin can be used as an
  example to manipulate the link target.


Failover
--------

Your plugin callback may specify a "failover" or fallback action in
the event they choke. Quick example: The specified node title cannot
be found in the database, so a link to create a node with that title
is put in place.

Plugins specify failover by returning array('plugin' => 'failover
plugin'). The failover plugin is then triggered to take over trying to
process the target. You can pass a modified target in this way by just
adding 'target' => $target to the return array. You may also specify
array('error' => 'error message') to provide an array message.

You can use variable_get('freelinking_pluginname_failover', 'none') to
get the preferred failover for your plugin. This is based on the
failover element in the plugin definition or on creating a form
element by that name in your settings.


Settings
--------

If your plugin will require some settings, they can be defined in a
"freelinking__settings" function in your include file, or
explicitly using the 'settings' element of the plugin's freelinking
array (necessary for modules). This function should return a Drupal
FormAPI array of the various settings your plugin will need. The
freelinking module will add these form controls to the settings page
(admin/settings/freelinking). Your plugin can use these settings in
the $freelinking array, or the callback function, as necessary.

A simple example of how to use settings is part of the wiki plugins
(freelinking_wiki.inc). It uses one setting to control the language
code that the URL to Wikipedia should use. The setting is used in the
$freelinking['wikipedia']['replacement'] element, using the language
code as part of the URL.

The freelinking_nodetitle.inc plugin also uses the settings
array. This plugin has settings to control what happens when a link
cannot be found, and is able to restrict the lookup of content to
certain content types.  This is an example of using settings within
the callback function.


THE FREELINKING API
-------------------

The Freelinking API allows you to customize freelinking plugins you
create specfically for your site.


hook_freelink_alter()
---------------------

By implementing this function, you can adjust the elements of the link
array before it is rendered into an HTML link. For example:

  function my_module_freelink_alter(&$link, $target, $plugin_name, $plugin) {
    static $count;
    $link[2]['attributes']['name'] = 'freelink-' . $count++;
  }

This function will alter every link created by freelinking to insert
the number of links found in the filtered text as an anchor. You might
also make a more targeted alteration:

  function my_module_freelink_alter(&$link, $target, $plugin_name, $plugin) {
    if ($plugin_name == 'google') {
      $link[2]['attributes']['title'] .= ' Isn't Google nifty?';
    }
  }

For documentation on the structure of the $link array here, read up on
on the API entry for the l() function:
http://api.drupal.org/api/search/6/l


Theme functions
---------------

theme('freelink', $plugin, $link);

This is the function that renders the $link array we "altered" above
into HTML. You can override this, like any theme function.

theme('freelink_error', $plugin, $message);

This function renders an error message provided by a plugin for
display in the page.