====== Mark a Paragraf ======

---- plugin ----
description: Start a paragraph with two exclamation marks, and it generates a <div class="important" /> around it.
author     : Marc Wäckerlin
email      : marc@waeckerlin.org
type       : syntax
lastupdate : 2006-01-20
compatible : 
depends    : 
conflicts  : 
similar    : importanttext
tags       : boxes style
----

===== Syntax =====

  * Starts with ''%%!!%%'' at the begin of a paragraph.
  * Ends with a single newline.
  * May be continued, if there are two spaces before the newline.
  * A class name can optionally be given:
     * Default class name is ''%%important%%''.
     * Class name is between the ''%%!!%%'' and an optional ''%%|%%''.
     * Class name must be all lower case ASCII characters.

===== Examples =====

The following:

<code>
!!This is the simplest use.
</code>

Is converted to HTML as:

<code html>
<div class="important"><div>This is the simplest use.</div></div>
</code>

The following (spaces are written as ''%%·%%'', because they are not visible otherwise):

<code>
!!classname|This is a paragraph, up to the newline··
    * This is a list item inside the important··
    * Please note the two spaces at the end of these lines··
  This is another paragraph inside the same <div class="important" />
!!marker|This is a new paragraph outside with class name "marker".
</code>

is converted to HTML as:

<code html>
<div class="classname">
  <div>
    This is a paragraph, up to the newline
  </div>
  <div>
    <ul>
      <li>This is a list item inside the important</li>
      <li>Please note the two spaces at the end of these lines</li>
  </div>
  <div>
    This is another paragraph inside the same &lt;div class="important" /&gt;
  </div>
</div>

<div class="marker">
  <div>
    This is a new paragraph outside with class name "marker".
  </div>
</div>
</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):

<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__;
}

div.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 paragraph 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_paragraf/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 Paragraf - Mark a paragraph with a class.

    Marks important paragraphs or sentences:
    
    An important paragraph starts with !!

    It is marked with &lt;div class="important" /&gt;

    A class name can be given in lower case ASCII between the !! and
    an optional |

    If you continue with a new paragraph that should still be
    important, end the line above with two spaces.
    
    It must be evaluated before the dl plugin.

    License: GPL
    */
class syntax_plugin_important_paragraf extends DokuWiki_Syntax_Plugin {

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

  function getType() {
    return 'container';
  }
   
  function getSort() {
    return 2;
  }

  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']);
      unset($this->allowedModes[array_search('preformatted',
                                             $this->allowedModes)]);
    }
    return parent::accepts($mode);
  }
    
  function connectTo($mode) {
    $this->Lexer->addEntryPattern('^ *\!\![a-z]+\|', $mode,
                                  'plugin_important_paragraf');
    $this->Lexer->addEntryPattern('^ *\!\!', $mode,
                                  'plugin_important_paragraf');
  }

  function postConnect() {
    $this->Lexer->addPattern(' (?= \n)',
                             'plugin_important_paragraf');
    $this->Lexer->addExitPattern('(?<! )\n',
                                 'plugin_important_paragraf');
  }

  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 .= '<div class="'.$class.'"><div>';
      } return true;
      case DOKU_LEXER_EXIT: {
        $renderer->doc .= '</div></div>';
      } return true;
      case DOKU_LEXER_MATCHED: {
        $renderer->doc .= '</div><div>';
        return true;
      }
      case DOKU_LEXER_UNMATCHED: {
        $renderer->doc .= htmlspecialchars($match);
      } return true;
    }
    return false;
  }
}
?>
</code>


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



==== plugin management error? ====
> 2006-05-14: I think, it doesn't work in the newest DokuWiki - Plugin Management says: //This plugin returned no information, it may be invalid.//
Seems to work for me. -- [[wonko@wonkology.org|Wonko]]

How about an example on this page, so we don't have to download and install it to see what it looks like?

Why don't you offer a package for quick installation? -- Philipp

I might host one on my github or bitbucket account, if it's a feature that is really wanted, and Marc is OK with it... -- xav0989

===== ChangeLog =====

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