-----------------------------------------------------------------------------------------------
|||||||||||||||||||||||||||||| AUTOGEN DEVELOPER DOCUMENTATION |||||||||||||||||||||||||||||||
-----------------------------------------------------------------------------------------------

Autogen 3.x provides a new framework for extending the Autogen 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 Autogen functions with few limits.
Items are always generated in content via the Autolink plugin filter. Link types have been
deprecated in favor of offering more control and flexibility to plugin defining modules.
Additionally, much of the module code has been streamlined to be significantly more efficient
and easier to work with.


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

Providing information to Autogen:
---------------------------------
Similar to most Drupal APIs, Autogen uses info hooks to retrieve information from modules.
For most modules, it will be sufficient to implement hook_autolink_plugin_info() to define
your plugin. If you would like to include other files use hook_autolink_file_info() to
identify those files to the Autolink API so they can be lazy-loaded at the time of processing.

Plugins:
-------------
Autogen plugins can be defined as a collection of callbacks that can control almost any
aspect of the link generation process. Plugin callbacks are consulted throughout the process,
and plugins can provide custom configuration forms while Autolink will keep track of those
settings without additional coding. For help on creating an Autolink plugin please contact
me in the Autolink module issue queue at http://drupal.org/project/autolink or drop a line
if you have any suggestions/request on how to expand support for plugins.

Processors:
----------
At their core, Autolink plugins use specific processor to do the dirty work. Autolink
currently defines two processors that affor plugins significant control over the process.
Currrent processor are the 'keyword' and 'pattern' processor. Each processor takes a unique
approach to locating matches within text, each method being a significant philosophy of
various linking modules around Drupal. To define your own processor or to extend an existing
one, modules can implement hook_autolink_processor_info() or hook_autolink_processor_info_alter().

Link types:
----------------
As mentioned, link types have been deprecated in the current version of Autolink. It is now
the responsibility of plugin defining modules to handle any additional interfaces beyond
the basic plugin configuration interface provided by Autolink.


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

The Autolink filter:
-------------------
1. At the start of Autolink's filter operations, the module retrieves currently enabled
   plugins and sorts them in ascending order by user configured weights.
2. Once sorted, each plugin is put through a loop.
3. During the loop, the plugin's settings are loaded before the plugin itself is loaded
   into its related processor object.
4. The plugin's preprocess callback is then called (if it exists) to allow the plugin to
   alter the newly loaded processor.
5. Upon completion of the preprocess callback, the Autolink filter checks to ensure that
   the plugin did not halt the processing for the current loop.
6. As long as processing has not halted, the processor's core execute() method is called,
   which locates matches within the text being filtered.
7. For each match, the processor calls the current plugin's replace callback via a magic
   __call() method within the plugin class.
8. Once the match is retrieved, the processor replaces the matched text with the replacement.
9. Upon completion of the AutolinkProcessor::execute() method, the loop through plugins
   continues.

Theoratically, the Autogen API can be used to perform any type of search and replace
operation. *Plugins may return any type of text during the replace callback.* Linking
is in no way mandatory, nor is it checked within processors.

See autolink.api.php for more information on Autolink API hooks and core functions.

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