Base Links plugin

Author: Robert Meerman
Based on externallink by Otto Vainio

This plugin allows base-linking in DokuWiki. Links beginning with a ”/” will link relative to the server's root, so [[/downloads/manual.pdf]] will link to just that: /downloads/manual.pdf, regardless of whether your installation of dokuwiki lies within a sub folder or not.

It improves a bit on externallink by allowing media titles: [[/downloads/manual.pdf|{{big_book.jpg}}]]

Same as normal links, except link must start with a ”/” and use slashes through-out.

Examples:

[[/downloads/manual.pdf]]
[[/downloads/manual.pdf|Educate yourself!]]
[[/manual.pdf|{{big_book.gif}}]]

You can use [[:downloads:manual.pdf]] to explicitly use the normal DokuWiki link syntax.

Point your plug-in manager at http://robmeerman.co.uk/downloads/dokuwiki-plugin-baselink.tar.gz

Create the folder /lib/plugins/baselink and create syntax.php containing the following:

/lib/plugins/baselink/syntax.php:

<?php
/**
 * Plugin base links: Creates links relative to site root for all links beginning with "/"
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Robert Meerman <robert.meerman@gmail.com>
 * @based_on   "externallink" plugin by Otto Vainio <plugins@valjakko.net>
 */
 
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_baselink extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Robert Meerman, based on externallink plugin by Otto Vainio',
            'email'  => 'robert.meerman@gmail.com',
            'date'   => '2007-05-19',
            'name'   => 'baselink',
            'desc'   => 'Makes links beginning with "/" present as (always valid) internal links that point relative to your domain\'s root. Format is [[/pagename|optional title]]',
            'url'    => 'http://www.dokuwiki.org/plugin:baselink',
        );
    }
 
    /**
     * What kind of syntax are we?
     */
    function getType(){
        return 'substition';
    }
 
    // Just before build in links
    function getSort(){ return 299; }
 
    function connectTo($mode) {
		// \x2F = "/"
        $this->Lexer->addSpecialPattern('\[\[\\x2F.*?\]\]',$mode,'plugin_baselink');
    }
 
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        $match = substr($match,2,-2); //strip [[ from start and ]] from end
        $match = explode("|",$match, 2);
        if( preg_match('/^\{\{[^\}]+\}\}$/',$match[1]) ){
			// If the title is an image, convert it to an array containing the image details
			$match[1] = Doku_Handler_Parse_Media($match[1]);
		}
        return $match;
    }
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            $text=$this->_baselink($renderer, $data[0], $data[1]);
            $renderer->doc .= $text;
            return true;
        }
        return false;
    }
 
 
    function _baselink(&$renderer, $url, $name = NULL) {
        global $conf;
 
        // Media in titles ( "{{...}}" ) are presented as arrays at this stage
        if(is_array($name)){
			$name = $renderer->_getLinkTitle($name, $url, $isImage);
		}
		else{
			// Quick Fix to supress naming bug ("[[/base/link|This & That]]" --displayed-as--> "This &amp; That")
			//$name = $renderer->_xmlEntities($renderer->_getLinkTitle($name, $url, $isImage));
			$name = $renderer->_getLinkTitle($name, $url, $isImage);
		}
 
        $class='wikilink1';
        $link['target'] = $conf['target']['wiki'];
        $link['style']  = '';
        $link['pre']    = '';
        $link['suf']    = '';
        $link['more']   = '';
        $link['class']  = $class;
        $link['url']    = $url;
        $link['name']   = $name;
        $link['title']  = $renderer->_xmlEntities($url);
 
        //output formatted
        return $renderer->_formatLink($link);
    }
 
}
?>

• 2006-03-06: Initial first release
• 2006-04-19: _xmlEntities bugfix ([[/base/link|This & That]] was incorrectly rendered as “This & That”)

Does this plugin completely supersede the externallink plugin?

In terms of functionality, yes. However the difference in syntax is significant enough for the two versions to exist side-by-side. Naturally I prefer the way baselinks works, I wrote it! (Based very heavily on externallink by Otto Vainio, really I changed almost nothing). — Robert Meerman 2006-04-19 02:04

I think, the use of _xmlEntities() is not neccessary and in fact leads to problems.

Example:

[[/someurl|This & that]]

This will always render as: This & that

Why? Well - when entering such text, special characters, like ampersand or ”<” and ”>” are already stored as ”&amp;”, ”&lt;” and so on. In fact all special characters are stored in a form, which never needs any conversion. A conversion may only be neccessary, when editing the text files manually without DokuWiki - but who does this?

BTW: DokuWiki itself does it correct: A link like

[[somepage|This & that]]

will render corract as: This & that

Is there a fix for xmlEntities() ? I tried to remove those from the code but the example with the &amp; is still not working correctly.

I believe this has been fixed as of the 2006-04-19 release. — Robert Meerman 2006-04-19 02:00

Note that the JavaScript function “svchk()” no longer exists (and is now unnecessary) in Dokuwiki, and does cause JavaScript errors, so references should be removed.
– todd [at] rollerorgans [dot] com 2007-02-26

Fixed. — Robert Meerman 2007-05-19 16:45

Why is the code in _baselink() greatly simplified from the externallink plugin's _externallink() code? ie. the handling of when $name = NULL removed? — chris 2007-11-02 17:12

Fred 2008-01-23 23:32

Hi, is it possible to add a feature to change the target of the link ? Something like that :

[[/index.php>_top|Home]] to open the link in the _top frame?