====== Mark a Text ======

---- plugin ----
description: Enclose a text within hashes and it generates a <span class="important" /> around it.
author     : Marc Wäckerlin
email      : marc@waeckerlin.org
type       : syntax
lastupdate : 
compatible : 
depends    : 
conflicts  : 
similar    : important_paragraf
tags       : highlight
----

===== Syntax =====

  * Starts with ''%%##%%''.
  * Ends with ''%%##%%''
  * A class name can optionally be given:
     * Default class name is ''%%important%%''.
     * Class name is between the starting ''%%##%%'' and an optional ''%%|%%''.
     * Class name must be all lower case ASCII characters.

===== Examples =====

The following:

<code>
This is a text with ##an important## part.
</code>

Is converted to HTML as:

<code html>
<p>This is a text with <span class="important">an important</span> part.</p>
</code>

The following:

<code>
This is a ##marker|marked## word.
</code>

is converts to HTML as:

<code html>
<p>This is a <span class="marker">marked</span> word.</p>
</code>

===== Installation =====

==== Optional CSS Definition ====

For the look and feel, optionally add the following code to your template's ''design.css'' file (if the name of your template is ''default'', then it is in ''lib/tpl/default/design.css'', also copy it to ''lib/tpl/default/print.css'' for the printing):

Tip: you can also create a CSS file in lib/plugins/important_text/style.css

<code css>
.important {
  background-color: __light__;
  border: 1px solid __dark__;
}

div.important {
  margin: 0.75em 0 1em 0;
  padding: 0.2em;
}

div.important div {
  padding:0;
  margin: 0;
}

div.important > div + div {
  padding:0;
  margin: 0.5em 0 0 0;
}

.important > .important {
  background-color: __dark__;
  border: 1px solid __black__;
}

span.marker {
  border-left: 1em solid yellow;
}
</code>

The "marker" class in the last section marks a text like marked with a yellow text-marker, if you write:

<code>
##marker|This text is like marked with a yellow text-marker.##
</code>

==== The Template's PHP Code ====

To install the functionality, copy the following code into a new file named ''lib/plugins/important_text/syntax.php'':

<code php>
<?php
    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');

/** Important Text - Mark a text with a class.

    Marks important text:
    
    An important text is enclosed by with ##text##.

    It is marked with
    &lt;span&nbsp;class="important"&nbsp;/&gt;
    
    If you want to mark it as
    &lt;span&nbsp;class="anything"&nbsp;/&gt;, mark your
    text as:
    ##anything|This&nbsp;is&nbsp;the&nbsp;Text##

    License: GPL
    */
class syntax_plugin_important_text extends DokuWiki_Syntax_Plugin {

  function getInfo() {
    return array('author' => 'Marc Wäckerlin',
                 'email'  => 'marc [at] waeckerlin [dot-org]',
                 'name'   => 'Important Text',
                 'desc'   => 'mark: !!!!This is important!!!!',
                 'url'    => 'http://marc.waeckerlin.org');
  }

  function getType() {
    return 'substition';
  }
   
  function getSort() {
    return 1;
  }

  function accepts($mode) {
    if (!count($this->allowedModes)) {
      global $PARSER_MODES;
      $this->allowedModes = array_merge($PARSER_MODES['container'],
                                        $PARSER_MODES['baseonly'],
                                        $PARSER_MODES['formatting'],
                                        $PARSER_MODES['substition'],
                                        $PARSER_MODES['protected'],
                                        $PARSER_MODES['disabled'],
                                        $PARSER_MODES['paragraphs']);
    }
    return parent::accepts($mode);
  }
    
  function connectTo($mode) {
    $this->Lexer->addEntryPattern('##[a-z]+\|(?=[^\n]*##)', $mode,
                                  'plugin_important_text');
    $this->Lexer->addEntryPattern('##(?=[^\n]*##)', $mode,
                                  'plugin_important_text');
  }

  function postConnect() {
    $this->Lexer->addExitPattern('##',
                                 'plugin_important_text');
  }

  function handle($match, $state, $pos, &$handler) {
    return array($match, $state);
  }

  function render($format, &$renderer, $data) {
    list($match, $state) = $data;
    switch ($state) {
      case DOKU_LEXER_ENTER: {
        if (strlen($match)>3)
          $class=substr($match, 2, strlen($match)-3);
        else
          $class='important';
        $renderer->doc .= '<span class="'.$class.'">';
      } return true;
      case DOKU_LEXER_EXIT: {
        for ($i=0; $i<strlen($match)-4; ++$i) $renderer->doc .=
          $match[$i];
        $renderer->doc .= '</span>';
      } return true;
      case DOKU_LEXER_MATCHED: return true;
      case DOKU_LEXER_UNMATCHED: {
        $renderer->doc .= htmlspecialchars($match);
      } return true;
    }
    return false;
  }
}
?>
</code>

===== Known Bugs =====

==== plugin incompatibility ====

The [[plugin:divalign|divalign's]] //justify// markup is broken by this plugin (due to formatting between %%###...###%%).
-- [[wonko@wonkology.org|Wonko]]

===== ChangeLog =====

  * //2006-01-20 mrw//
    * initial release