====== Javadoc ======

---- plugin ----
description: Link to a Javadoc API using class/method name and a site reference
author     : Damien Coraboeuf
email      : dcoraboeuf@yahoo.fr
type       : syntax
lastupdate : 2007-09-19
compatible : 2007-10-03
depends    : 
conflicts  : 
similar    : 
tags       : java, links, html

downloadurl: http://www.doolin-guif.net/wiki/lib/exe/fetch.php?id=plugin%3Ajavadoc&cache=cache&media=plugin:plugin-javadoc-1.0.0.zip
----

===== Description =====

This plugin offers a convenient way to reference Javadoc API pages. It is particularly useful when creating Java technical documentation to reference the classes being used.

Given a class name (and a method name) and a site reference, a link is automatically generated to the corresponding Javadoc API page.


===== Usage =====

See http://www.doolin-guif.net/wiki/doku.php?id=plugin:javadoc

You will see plenty of examples of this plugin on this Wiki ([[http://www.doolin-guif.net/wiki/doku.php?id=app:application_services|here]] for example).


===== Installation =====

Get the latest version from http://www.doolin-guif.net/wiki/doku.php?id=plugin:javadoc.

It can be installed using the Plugin Manager.

Today, the only way to associate site reference to actual URL is by editing the //syntax.php// file.

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

<code php><?php
/**
 * Add Javadoc link capability to DokuWiki
 *
 * by Damien Coraboeuf <dcoraboeuf@yahoo.fr>
 * under the terms of the GNU GPL v2.
 *
 * @license    GNU_GPL_v2
 * @author     Damien Coraboeuf <dcoraboeuf@yahoo.fr>
 */
 
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');


class syntax_plugin_javadoc extends DokuWiki_Syntax_Plugin {
  
    function getInfo(){
        return array(
            'author' => 'Damien Coraboeuf',
            'email'  => 'dcoraboeuf@yahoo.fr',
            'date'   => '2007-09-19',
            'name'   => 'Javadoc Plugin 1.0.0 (Beta 01)',
            'desc'   => 'Add Javadoc link Capability',
            'url'    => 'http://doolin.x10hosting.com/wiki/doku.php?id=plugin:javadoc',
        );
    }
 
    function getType(){ return 'substition'; }
 
    function getPType(){ return 'normal'; }
    
    function getAllowedTypes() { return array('container','substition','protected','disabled','formatting','paragraphs'); }
    
    function getSort(){ return 194; }    
	
	// override default accepts() method to allow nesting 
    // - ie, to get the plugin accepts its own entry syntax
    function accepts($mode) {
        if ($mode == substr(get_class($this), 7)) return true;
 
        return parent::accepts($mode);
    }

    function connectTo($mode) {
        $this->Lexer->addEntryPattern('<javadoc.*?>(?=.*?</javadoc>)',$mode,'plugin_javadoc');
    }
    function postConnect() {
        $this->Lexer->addExitPattern('</javadoc>','plugin_javadoc');
    }
 
    function handle($match, $state, $pos, &$handler){

        switch ($state) {

          case DOKU_LEXER_ENTER : 
            $site = trim(substr($match,8,-1));
 			if (strlen($site) == 0) {
				return array($state, "jdk6");
            } else {
				return array($state, $site);
            }
 
          case DOKU_LEXER_UNMATCHED :
            return array($state, $match);
        
          default:
            return array($state);
        }
    }
 
    function render($mode, &$renderer, $indata) {
	
	    $sites = array (
		   'jdk6' => 'http://java.sun.com/javase/6/docs/api',
		   'doolin' => 'http://doolin-guif.sourceforge.net/apidocs',
		   'commons-beanutil' => 'http://commons.apache.org/beanutils/commons-beanutils-1.7.0/docs/api/'
		   );

        if($mode == 'xhtml'){

          list($state, $data) = $indata;

          switch ($state) {
            case DOKU_LEXER_ENTER :
              $prefix = $sites[$data];
              $renderer->doc .= '<a class="javadoc" target="_blank" href="'.$prefix;
              break;
  
            case DOKU_LEXER_UNMATCHED :
		// Get the token and the text, separated by an optional "|"
              	$indexOfTextSeparator = strrpos($data,"|");
		if ($indexOfTextSeparator === false) {
			$token = $data;
			$text = $renderer->_xmlEntities(str_replace("#", ".", $data));
		} else {
			$token = substr($data, 0, $indexOfTextSeparator);
			$text = substr($data, $indexOfTextSeparator + 1);
		}
		// Get the class name and the method
		$indexOfMethodSep = strrpos($token,"#");
	      	if ($indexOfMethodSep === false) {
			$url = "/".str_replace(".", "/", $token).'.html';
              	} else {
			$className = substr($token, 0, $indexOfMethodSep);
			$className = str_replace(".", "/", $className);
			$methodName = substr($token, $indexOfMethodSep + 1);
			$url = "/".$className.".html#".$methodName;
	      	}
	      	$renderer->doc .= $url.'"><code>'.$text.'<//code>';
              	break;
  
            case DOKU_LEXER_EXIT :
              $renderer->doc .= "</a>";
              break;
          }
          return true;
        }
        
        // unsupported $mode
        return false;
    } 
}
 
?>

</code>

//Note: on the code above, I have used <nowiki><//code></nowiki> instead of <nowiki></code></nowiki> in order to avoid a parsing mistake in DokuWiki.//


===== Comments =====