~~NOTOC~~

====== Websvn ======

---- plugin ----
description: A convenience plugin for linking (and iframe-inlining) files in a WebSVN repository.
author     : Stefan Hechenberger
email      : foss@stefanix.net
type       : syntax
lastupdate : 2007-02-06
compatible : 2007-02-05+
depends    : 
conflicts  : 
similar    : 
tags       : svn, subversion, links, iframe
----


===== Description =====
This plugin offers a convenient way to reference files in a Subversion repository. It assumes that the repository is made web-accessible with [[http://websvn.tigris.org/|WebSVN]]. Instead of using absolute links to files in WebSVN this plugin allows you to reference them with a short path relative to a root path. This not only makes the referencing links much shorter but also makes the links less prone to breaking later. -[[http://stefanix.net|stefan]]



===== Usage =====
**Link** to a particular file in your WebSVN-served subversion repository.
<code>
<websvn repository/path/to/file>
</code>

Alternatively the file listing can be **iframe-inlined** by adding a trailing space to the path:
<code>
<websvn repository/path/to/file >
</code>



===== Installation =====
Point your Plugin Manager to this url: [[http://file.stefanix.net/websvn-plugin-2007-02-07.zip|websvn-plugin-2007-02-07.zip]]. This automatically downloads, unzips and installs the plugin. Once installed it has to be configured.

**To configure:**
  * edit lib/plugins/websvn/syntax.php
  * set the //$websvn_root_url// to the root of your WebSVN installation
  * enjoy!

===== Source Code =====
syntax.php

<code php>
<?php
/**
 * Plugin websvn: Deep-links to files in a WebSVN repository
 *                      http://websvn.tigris.org/
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Stefan Hechenberger <foss@stefanix.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');
 


//-----------------------------------CONFIGURE WEBSVN ROOT HERE---------
global $websvn_root_url;
$websvn_root_url = "http://your.websvn.root/";
//----------------------------------------------------------------------

 
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_websvn extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Stefan Hechenberger',
            'email'  => 'foss@stefanix.net',
            'date'   => '2007-02-06',
            'name'   => 'websvn Plugin',
            'desc'   => 'Generates deep links to files in a WebSVN repository.',
            'url'    => 'http://www.dokuwiki.org/plugin:websvn',
        );
    }
 
    /**
     * What kind of syntax are we?
     */
    function getType(){
        return 'substition';
    }
	
 
    /**
     * Where to sort in?
     */ 
    function getSort(){
        return 921;
    }
 
 
    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
      $this->Lexer->addSpecialPattern('<websvn .*?>',$mode, substr(get_class($this), 7));
    }

 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        $match = html_entity_decode(substr($match, 8, -1));
        if(substr($match, -1, 1) == ' ') {
            $iframe = 1;
            $match = substr($match, 0, -1);
        }else {
            $iframe = 0;
        }
        list($repository, $reppath) = explode('/', $match, 2);
        $reppath = '/'.$reppath;
        $sourcefilename = substr(strrchr($reppath, "/"), 1);
        $reppath = urlencode($reppath);
        return array($repository, $reppath, $sourcefilename, $iframe);
    }
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        global $websvn_root_url;
        list($repository, $reppath, $sourcefilename, $iframe) = $data;
        $url = $websvn_root_url."filedetails.php?repname=$repository&path=$reppath";
        if($mode == 'xhtml'){
            if($iframe) {
                $w = "100%";
                $h = "400px";
                $renderer->doc .= '<iframe title="'.$sourcefilename.'" src="'.$url.'" style="width:'.$w.'; height: '.$h.';">'.$sourcefilename.'</iframe>';                
            } else {
                $renderer->doc .= "<a href=\"".$url."\">$sourcefilename</a>";
            }
            return true;
        }
        return false;
    }
}

</code>




===== Comments =====

Works Great, just make sure the first argument in the path is the repository name -> <websvn ReposName/trunk/path/filename>\\ 
--- //???? (??-??-???? ??:??)//

Works indeed very great. Only the fact that the link doesn't have an image to recognize the "WebSVN-link" is a little inconvenient imho. Therefore I have changed some code of the plugin, and created an small (16x16) image from the WebSVN-logo which is now rendered before the link. The other thing that I found inconvenient is that the link opens in the same window. I changed the target to ''_blank'' to let it open in a new window.\\ 
\\ 
I have added a new "configure-section" to configure the image-url right below the ''CONFIGURE WEBSVN ROOT HERE''-section:
<code php>
//-----------------------------------CONFIGURE WEBSVN-LINK IMAGE HERE---------
global $websvn_image_url;
$websvn_image_url = "http://www.your.domain/path/to/button.png";
//----------------------------------------------------------------------------
</code>
After that I have defined the new global variable ''$websvn_image_url'' in the //render funtion// by adding this:
<code php>
        global $websvn_image_url;
</code>
straight below the line:
<code php>
        global $websvn_root_url;
</code>
in the //render function//.\\ 
\\ 
Finally I changed the following line from:
<code php>
                $renderer->doc .= "<a href=\"".$url."\">$sourcefilename</a>";
</code>
to:
<code php>
                $renderer->doc .= "<img src=".$websvn_image_url."><a href=\"".$url."\" target=_blank>$sourcefilename</a>";
</code>
After those changes images are displayed before the link-name (just like InterWiki-links), and the links opens in a new window. Here's an example image of how my links look rightnow:\\ 
\\ 
[[http://www.the-evil.pointclark.net/files/dw_plugins/websvn-hack/sample.png]]\\ 
\\ 
--- //[[http://www.the-evil.pointclark.net|Mischa The Evil]] (27-06-2007 02:45)//


==== Questions ====

I have been thinking about the way to link dokuwiki/subversion/...
  * Do you plan/Is it possible to allow a syntax like websvn>400 to allow either the display of all files changed (svn log -v) or all differences (svn diff) due to that version? This is usually what I would like to link to from the wiki towards svn.
  * What benefits does this plugin has compared to adding an interwiki.conf with the shortcut to the svn repository displayed via websvn as well? The main one I see is that the code can be displayed in the page itself... for an external display, the interwiki option seems more straightforward, doesn't it?
  * Regarding websvn, how popular/active is the community? I have installed and am using it... but I am wondering if using apache/mod_svn module would not be a better way to publish my repository (since at the same time it allows modifications as far as I understand)?
  * For SVN fans out there, anyone with the idea to replace the dokuwiki version control (gzipping around) by straightforward svn add/update/commit? It would look SOOO natural (and more efficient)... at least as an alternate storage/versioning option...