-----------------------------------------------------------------------------------------------
|||||||||||||||||||||||||||||| AUTOLINK DEVELOPER DOCUMENTATION |||||||||||||||||||||||||||||||
-----------------------------------------------------------------------------------------------

Autolink 2.x provides a new framework for extending the Autolink application. Developers may
now provide plugins to control the activity of the linking process with great accuracy. The new
object-oriented design opens up possibilities for extending Autolink functions with few limits.
Links can be generated in nodes or text during hook_nodeapi() operations as well as filter ops.
Additionally, a rewrite of how Autolink handles link types allows developers to further extend
functionality by manipulating the relationship between Autolink and its links. Following is
documentation on how to work with plugins and link types in Autolink. For examples of how to use
Autolink hooks, classes, and methods, consult autolink.api.php in the module folder or view
the three plugin modules that come with the Autolink package.


---------------------------
||||| GETTING STARTED |||||
---------------------------

Providing information to Autolink:
---------------------------------
Similar to many Drupal modules, Autolink uses info hooks to retrieve information from modules.
Information hooks should be placed either in the MYMODULE.module file or MYMODULE.autolink.inc.
*.autolink.inc files will be lazy-loaded by Autolink when it is gathering information about
plugins and link types.

Processors:
----------
Additional processors can be provided to Autolink by implementing hook_autolink_processor_info().
Processors enable developers to provide different methods of processing data. Autolink module
currently is packaged with a node processor and a text processor, for example. Once defined,
processors may be retrieved and used by calling autolink($processor). Processors will
always make use of the currently enabled plugin to assist with processing by accomplishing
tasks like providing fields, link types, regular expressions, and link attributes. Alternatively,
Autolink's own processors may be expanded upon by extending the classes (they are not final).

Plugins:
-------------
Autolink plugins can be defined as a collection of settings and classes that manipulate the
link placement process performed by Autolink module. Plugins can define regular additional
properties of the regular expression used by Autolink, limit which link types are supported,
set a limit on how many links are generated per keyword or per node, or define a global
settings form, among other things. An example use for a plugin could be linking node ID numbers
similar to the drupal.org website [#12345] through regular expressions or by supporting specific
link types.

Link types:
----------------
Link types are collections of settings and classes that define how a certain type of data
should be handled by Autolink. Collectively, the collection is referred to as a link type
because it essentially forms a new link format based on settings forms, attributes, and unique
class and method implementations. A link type can provide a form to be used when identifying
a new link. Autolink can store any amount of data from the form, and it can be referred to
during the link placement process. Additionally, abstract link types may be defined. Abstract
link types have no settings forms, but rather are collections of links that are provided to
Autolink at run-time. An example of abstract link types can be found in the Autolink Automatic
Links module, where existing node titles, taxonomy terms, and user names are provided to
Autolink for automatic linking, rather than linking pre-defined keywords.


--------------------------------
||||| APPLICATION WORKFLOW |||||
--------------------------------

autolink():
1. During certain hook_nodeapi() and hook_filter() operations, Autolink invokes associated
node and filter hooks if found in the defining module of the currently enabled plugin.
2. Hooks should be used to call autolink() (though autolink() may be called
from other areas as well).
3. When autolink() is called, Autolink loads the specified processor and populates
it with the current plugin object.

load():
1. The AutolinkProcessor::load() method should then be called to load necessary data for
processing.
2. What data is loaded depends on the processor being used. For example, the node processor
requires only a node object, while the text processor requires an associated node and text.

update():
1. When the AutolinkProcessor::update() method is called, Autolink gathers link objects.
Links are gathered by first querying the plugin for supported link types. Data for definable
link types is retrieved from the database and relavant objects are created based on the
link type class. Non-definable link types are loaded by instantiating the link type's provider
object and retrieving an array of link data from which relavant link objects are created.
2. Autolink passes the links back to the child processor's process() method for processing.
3. The child processor invokes the processText() method on whatever text needs to have links,
passing links and limits.
4. Autolink loops through each link, building a regular expression by invoking the plugin's
getExpression() method and adding expression parts to the default expression.
5. When keywords are located, Autolink calls the AutolinkPlugin::buildReplacement() method.
6. During link building, the plugin class builds link attributes and text by invoking
the necessary plugin methods.

clear():
1. When the AutolinkProcessor::clear() method is called, the child processor object's
clear() method is invoked, not the abstract parent class.
2. The processor object passes relevant text to textClear(). A single AutolinkLink object
may be passed to remove only a single link.


Definable link type forms:
1. Definable link types must define a configuration class.
2. When a user visits the 'add link' page in Autolink administration, Autolink queries
the Autolink configuration object to determine what link types are both supported by the
currently enabled plugin and have been enabled by the user on the settings page.
3. A select list of available link types are displayed.
4. When a user selects a link type, Autolink determines whether the link type defines
more than one form.
5. If the link type defines only one form class, an object is instantiated and the form()
method is invoked.
6. If the link type defines more than one form class, Autolink displays a second select
list of options to allow the user to select which definition form to use. Once that option
is selected, Autolink loads the object and calls the form() method.
7. When a user submits the form, the form data is merged into a single array and passed
to the form object's validate() method.
8. Upon passing validation, the data is processed to set important values like keyword
and path by calling the form object's setKeyword() and setPath() methods.
9. An AutolinkLink object is created from the data and the object is saved to the database.

Theoratically, the Autolink API can be used to perform any type of search and replace
operation. Plugins can extend the buildReplacement() method to return any type of
replacement necessary. For more information on ways to use Autolink module, keep an
eye out for a tutorial.

Developed and maintained by:
Jordan Halterman
jordan.halterman@gmail.com
