I'm very pleased to release my first Joomla! extension! I named it "Bot link". As its name indicates, it is a plugin which automatically places links on pieces of text of your choice in your Joomla! articles. You may use it with a simple text expression or a more advanced perl regular expression. An additional nice feature is that It does not introduce links in places already containing one...

Bot link is still under heavy development and I would not qualify any version as beta, alpha, release candidate or anything. The bot is already relatively stable but requires probably too much the use of regex to be really practical for users which don't like perl regular expressions (Are there any?). My goal is to polish everything for 1.0.0. Anyway, I advise users to check regularly for new versions as Bot link will still improve in the near future...

Syntax

{%bot_link (text="text"|regex="pattern" [text="text"]) link="url" [class="class" alt="text" title="text" html="1" case="1" popup="1"]}

The "%" character after "{" is only here so that the bot is ignored on this page...

Arguments

text

If used alone, means the text to search for. Used in combination with the regex argument, means the text to replace the regular expression matches (optional).

regex

A perl-style regular expression to search for. If used, the "case" argument will be ignored.

The expression inside the delimiters has to be set in parenthesese (Have a look at the examples). If a second set of parentheses is used, only its content will be linked by the bot leaving the rest untouched. If a third set is used, the middle set delimits a text portion that will be replaced by the expression delimited by the third (and most inner set) The link will be placed around this last text portion. Any other set of parenthesis should be commented.

For deeper documentation, look at PHP manual's chapter about Pattern syntax.

link

A valid url. Internal urls are processed through the sefRelToAbs() function.

class

Specifies a class for the links markups of this specific bot. Overrides the default "class" parameter of the plugin.

alt

The alt attribute of the links markups

title

The tooltip displayed by the link

case

Optional. Ignored if the regex argument is used

0 - Case insensitive (default)

1 - Case sensitive

html

0 - The bot will ignore the HTML markups of your content and translate the HTML special characters (e.g. " will be translated to "). (default)

1 - The bot will treat the HTML markups and special characters as normal text.

In both cases, links already present in the text will not be affected by Bot link.

popup

Optional.

0 - Open link in the same window (default)

1 - Open link in a popup window

Examples

The "%" characters after "{" are only present in those examples so that the bot is ignored on this page... All the example bots are also present whithout "%" in this article. The links introduced around the example expressions are thereby genuine Bot link's links...

Use with text

{%bot_link text="Homepage" link="index.php" case="1" popup="1"}

homepage

Homepage.

Here the bot will place links around each occurences of "Homepage" but not "homepage" and the link will be opened in a new window... Note that the bot does not care about the context (quotes) of each occurence.

Use with regex

{%bot_link regex="/(whateverurl\.ext[^\/:])/i" link="http://www.whateverurl.ext/"}

whateverurl.ext?

http://www.whateverurl.ext/

http://www.whateverurl.ext:97/

In this example, using "regex" allows to select the context where whateverurl.ext is linked. Note that the question mark in whateverurl.ext? is also linked as it is part of the expression. The expression in the regex delimiter "/"needs to be put in parentheses.

Use of additional parentheses in regex

{%bot_link regex="/((otherurl\.ext)[^\/:])/i" link="http://www.otherurl.ext/"}

otherurl.ext?

http://www.otherrurl.ext/

Here the second set of parenthesis (inside the outermost parentheses) delimits the expression that will be linked by the bot. The question mark in "otherurl.ext?" will not be linked.

It is possible to use a third set of parenthesis. The best explanation is given through the following example:

{%bot_link regex="/(((yetanotherone\.ext)%l))/i" link="http://www.yetanotherone.ext/"}

yetanotherone.ext (Here "%l" has been introduced after yetanotherone.ext)

yetanotherone.ext (While here it was not)

The first set of parenthesis delimits, as in the other examples, the whole expression in the "/" regex delimiters. The second set delimits the expression that will be removed from the text and replaced by the expression inside the third set of parenthesis around which the link will be placed. In our example this results in the removal of "%l" after "yetanotherone.ext".

This allows to easily direct Bot link at specific occurences of your regular expression whithout changing the final output of your text.

Changelog

1.0.0 (My goal...)

• Error handling for regular expressions. So that everything does not crash for a tiny (yet powerful) plugin...
• User friendliness (Right now, Bot link is already user friendly. It is just very selective about who is its friend...)

0.2.0 (24/01/2008)

• Avoidance of HTML markups and special characters (activated by default and options to disable).
• Support for escaped quotes (\") in arguments.
• Implementation of the "alt" argument.
• Implementation of tooltips.
• Improved processing of the default bots.

0.1.3 (10/01/2008)

• Minor bugs fixed.

0.1.2 (10/01/2008)

• Introduction of the "class" argument.

0.1.1 (09/01/2008)

• Implementation of PHP4 unsupported functions.

0.1.0 (06/01/2008)

First release

P.S.

I hope every user will like this tiny plugin. I offer no warranty of the fitness of my code and you must use it at your own risks... Don't hesitate to contact me about whatever bug you might find or whatever improvement you think I could bring to this bit of code...