====== Tip Syntax PlugIn ======
---- plugin ----
description: Use small notes/hints
author : Matthias Watermann
email : support@mwat.de
type : syntax
lastupdate : 2008-05-25
compatible : 2005-07-13+
depends :
conflicts :
similar : note, wrap
tags : boxes
downloadurl: http://dev.mwat.de/dw/syntax_plugin_tip.zip
----
You know those little yellow pieces of paper which so nicely stick all around your screen's frame?
Lots of "note this" and "remember that" and "don't forget to ..."
Well, when starting yet another technical document I realized that it would be nice to have something like that available for the pages I was going to write.
After scanning my paperwork it seemed that I needed four kinds of tips:
"//hints//", "//infos//", "//notes//" and "//warnings//".
Then I felt the desire to place them vertically (in relation to the surrounding text):
//centered// on screen, on the //left// side and, er, the //right// side.
And finally I thought it would be nice((You know that feeling, don't you? Once you've got your super-duper-hyper-icecream your parents think you'd be happy finally. -- But you only think how nice some strawberries would be. And some chocolates. And some ...)) to have some control about how to position them horizontally.
So I ended up with a tag which allows for ten different arguments ...
===== Usage =====
The easiest use of a "''tip''" box is just
* Usage:
* The returned array holds the following fields:
*
* This method is important for correct XHTML nesting.
* It returns one of the following values:
*
* The $aState parameter gives the type of pattern
* which triggered the call to this method:
*
* The method checks for the given $aFormat and returns
* FALSE when a format isn't supported. $aRenderer
* is a reference to the renderer object which is currently
* handling the rendering. The contents of $aData is
* the return value of the handle() method.
*
syntax_plugin_tip.php - A PHP4 class that implements
* a DokuWiki plugin for small notes/tips fragments.
*
*
* <tip [c|l|r] [u|e|d] [h|i|n|w]>some text</tip>
*
* Copyright (C) 2006, 2007 M.Watermann, D-10247 Berlin, FRG
* All rights reserved
* EMail : <support@mwat.de>
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
*
* @return Array Information about this plugin class.
* @public
* @static
*/
function getInfo() {
return array(
'author' => 'Matthias Watermann',
'email' => 'support@mwat.de',
'date' => '2007-08-15',
'name' => 'Tip Syntax Plugin',
'desc' => 'Place hints &c. on a page '
. '[
*
* @return String "normal" instead of the (correct) "block"
* since otherwise the current DokuWiki parser wouldn't allow for
* nested paragraphs.
* @public
* @static
*/
function getPType() {
return 'normal';
} // getPType()
/**
* Where to sort in?
*
* @return Integer 415 (not really important here).
* @public
* @static
*/
function getSort() {
return 415;
} // getSort()
/**
* Get the type of syntax this plugin defines.
*
* @return String "container".
* @public
* @static
*/
function getType() {
return 'container';
} // getType()
/**
* Handler to prepare matched data for the rendering process.
*
*
*
* @param $aMatch String The text matched by the patterns.
* @param $aState Integer The lexer state for the match.
* @param $aPos Integer The character position of the matched text.
* @param $aHandler Object Reference to the Doku_Handler object.
* @return Array Index [0] holds the current
* $aState, index [1] the match prepared for
* the render() method.
* @public
* @see render()
* @static
*/
function handle($aMatch, $aState, $aPos, &$aHandler) {
switch ($aState) {
case DOKU_LEXER_ENTER:
$o = 'r'; // orientation, default: 'right'
$p = 'e'; // positioning, default: 'even'
$t = ''; // type, default: no image
$hits = array();
$aMatch = preg_split('|\s+|', substr($aMatch, 4),
-1, PREG_SPLIT_NO_EMPTY);
while (list($i, $arg) = each($aMatch)) {
switch ($i = strtolower($arg{0})) {
case 'c': // center
case 'l': // left
case 'r': // right
$o = $i;
break;
case 'd': // down
case 'e': // even
case 'u': // up
$p = $i;
break;
case 'h': // hint
case 'i': // info
case 'n': // note
case 'w': // warn
$t = $i;
default:
break;
} // switch
} // while
return array(DOKU_LEXER_ENTER, $o . $p . $t);
case DOKU_LEXER_UNMATCHED:
return array(DOKU_LEXER_UNMATCHED, $aMatch);
case DOKU_LEXER_EXIT:
return array(DOKU_LEXER_EXIT, '');
default:
// This state isn't used by 'render()'
// and causes it to do nothing at all:
return array(DOKU_LEXER_SPECIAL, '');
} // switch
} // handle()
/**
* Add exit pattern to lexer.
*
* @public
*/
function postConnect() {
$this->Lexer->addExitPattern('\x3C\x2Ftip\x3E', 'plugin_tip');
} // postConnect()
/**
* Handle the actual output creation.
*
*
" tags handled here are just kind // of workaround problems with the current DokuWiki renderer; it's // needed because we've to lie (in "getPType()") about the created // markup's type. // Basically they are __wrong__ here (since they are outside the // plugin's domain of responsibility) but, alas, without them // invalid HTML would be generated :-( // If and when DokuWiki becomes more stateful // the superflous tags should be removed. switch ($aData[0]) { case DOKU_LEXER_ENTER: // Since we have to use PType 'normal' we must close the // current paragraph and open a new one for our own contents. $hits = array(); if (preg_match('|\s*
\s*$|i', $aRenderer->doc, $hits)) { $aRenderer->doc = substr($aRenderer->doc, 0, -strlen($hits[0])) . '
'; } else { $aRenderer->doc .= '
'; } // if // The "tipAll" class is meant to make CSS easier. return TRUE; case DOKU_LEXER_UNMATCHED: $aRenderer->doc .= str_replace($this->_Chars, $this->_Ents, $aData[1]); return TRUE; case DOKU_LEXER_EXIT: // Since we have to use PType 'normal' we must open // a new paragraph for the following text. $aRenderer->doc = preg_replace('|\s*
\s*
\s*|', '', $aRenderer->doc) . '';
default:
return TRUE;
} // switch
} // render()
//@}
} // class syntax_plugin_tip
} // if
//Setup VIM: ex: et ts=2 enc=utf-8 :
?>
==== Presentation ====
As mentioned [[#usage|above]] the important work is done by means of CSS.
There are 45 different CSS classes in total to rule all possible combinations of optional [[#usage|arguments]] you're using in your ''tip'' markup:\\
''tipcd, tipcdh, tipcdi, tipcdn, tipcdw, tipce, tipceh, tipcei, tipcen, tipcew, tipcu, tipcuh, tipcui, tipcun, tipcuw, tipld, tipldh, tipldi, tipldn, tipldw, tiple, tipleh, tiplei, tiplen, tiplew, tiplu, tipluh, tiplui, tiplun, tipluw, tiprd, tiprdh, tiprdi, tiprdn, tiprdw, tipre, tipreh, tiprei, tipren, tiprew, tipru, tipruh, tiprui, tiprun, tipruw''.\\
However, you neither need to know nor to care about those classes:
they're created by the [[#plugin_source|plugin]] automatically and interpreted by the reader's browser using the associated styling rules.
I've listed them here just for informational purposes.
Starting with the 2007-08-06 release of this plugin a CSS class "''tipAll''" is additionally set for all ''tip'' elements.
This is mostly meant to ease the CSS styling of embedded elements such as e.g. links or paragraphs((So instead of 45 possible selectors for all kinds of tips you can use the "''tipAll''" class to catch them all.)).
\s*$|i', $aRenderer->doc, $hits)) {
$aRenderer->doc = substr($aRenderer->doc,
0, -strlen($hits[0])) . ' ';
} else {
$aRenderer->doc .= ' ';
} // if
This would make customizing so much gentler to the brain.
--- [[magnus.holmgren@millnet.se|Magnus Holmgren]]
.tipAll{font-family:"Trebuchet MS","Bitstream Vera Sans",Helvetica,sans-serif;font-size:94.4%;margin:0.6ex 0 0.4ex 0;padding:0 0.6ex 0.2ex 0.6ex;line-height:1.2;border:1px solid #999;color:#000;background-color:#ffffee;background-image:none;background-repeat:no-repeat;background-position:1px 1px;min-height:28px;min-width:25%;width:auto;max-width:31%;}
* html body .tipld,* html body .tipldh,* html body .tipldi,* html body .tipldn,* html body .tipldw,* html body .tiple,* html body .tipleh,* html body .tiplei,* html body .tiplen,* html body .tiplew,* html body .tiplu,* html body .tipluh,* html body .tiplui,* html body .tiplun,* html body .tipluw,* html body .tiprd,* html body .tiprdh,* html body .tiprdi,* html body .tiprdn,* html body .tiprdw,* html body .tipre,* html body .tipreh,* html body .tiprei,* html body .tipren,* html body .tiprew,* html body .tipru,* html body .tipruh,* html body .tiprui,* html body .tiprun,* html body .tiprw{width:30%;}
.tipAll *{font-size:99.9%;margin:0 auto;}
.tipcd,.tipcdh,.tipcdi,.tipcdn,.tipcdw,.tipce,.tipceh,.tipcei,.tipcen,.tipcew,.tipcu,.tipcuh,.tipcui,.tipcun,.tipcuw{margin-left:auto;margin-right:auto;padding-top:1ex;text-align:center;width:auto;max-width:62%;}
* html body .tipcd,* html body .tipcdh,* html body .tipcdi,* html body .tipcdn,* html body .tipcdw,* html body .tipce,* html body .tipceh,* html body .tipcei,* html body .tipcen,* html body .tipcew,* html body .tipcu,* html body .tipcuh,* html body .tipcui,* html body .tipcun,* html body .tipcuw{width:62%;}
.tipld,.tipldh,.tipldi,.tipldn,.tipldw,.tiple,.tipleh,.tiplei,.tiplen,.tiplew,.tiplu,.tipluh,.tiplui,.tiplun,.tipluw{float:left;text-align:left;margin-right:1.5ex;}
.tiprd,.tiprdh,.tiprdi,.tiprdn,.tiprdw,.tipre,.tipreh,.tiprei,.tipren,.tiprew,.tipru,.tipruh,.tiprui,.tiprun,.tipruw{float:right;text-align:right;margin-left:1.5ex;padding-right:1ex;}
.tipcd,.tipcdh,.tipcdi,.tipcdn,.tipcdw,.tipld,.tipldh,.tipldi,.tipldn,.tipldw,.tiprd,.tiprdh,.tiprdi,.tiprdn,.tiprdw{margin-top:1.2em;margin-bottom:0;}
.tipcu,.tipcuh,.tipcui,.tipcun,.tipcuw,.tiplu,.tipluh,.tiplui,.tiplun,.tipluw,.tipru,.tipruh,.tiprui,.tiprun,.tipruw{margin-top:-1ex;}
.tipcdh,.tipceh,.tipcuh,.tipldh,.tipleh,.tipluh,.tiprdh,.tipreh,.tipruh{background-image:url(img/hint.gif);}
.tipcdi,.tipcei,.tipcui,.tipldi,.tiplei,.tiplui,.tiprdi,.tiprei,.tiprui{background-image:url(img/info.gif);border-color:#060;}
.tipcdn,.tipcen,.tipcun,.tipldn,.tiplen,.tiplun,.tiprdn,.tipren,.tiprun{background-image:url(img/note.gif);border-color:#006;}
.tipcdw,.tipcew,.tipcuw,.tipldw,.tiplew,.tipluw,.tiprdw,.tiprew,.tipruw{background-image:url(img/warn.gif);border-color:#600;}
.tipcdh,.tipceh,.tipcuh,.tipldh,.tipleh,.tipluh,.tiprdh,.tipreh,.tipruh,.tipcdi,.tipcei,.tipcui,.tipldi,.tiplei,.tiplui,.tiprdi,.tiprei,.tiprui,.tipcdn,.tipcen,.tipcun,.tipldn,.tiplen,.tiplun,.tiprdn,.tipren,.tiprun,.tipcdw,.tipcew,.tipcuw,.tipldw,.tiplew,.tipluw,.tiprdw,.tiprew,.tipruw{padding-left:28px;}
Of course, you're free to modify this styles((The [[http://dev.mwat.de/dw/syntax_plugin_tip.zip|source archive]] contains a commented and indented stylesheet for your information.)) to suit your personal needs or aesthetics((Just be careful when modifying a CSS file: both the order and the selector groupings are important for CSS to work as intended/expected.)).
==== Changes ====
__2008-05-25__:\\
* CSS: removed overflow rule for elements embedded in tips;
__2007-08-15__:\\
* added GPL link and fixed some doc problems;
__2007-08-09__:\\
+ minor change in 'handle()' to allow for uppercase arguments;
__2007-08-06__:\\
+ modified 'render()' to set an additional CSS class 'tipAll' (to ease CSS styling of embedded elements);
__2006-12-31__:\\
+ initial release
//[[support@mwat.de|Matthias Watermann]] 2008-05-25//
===== See also =====
There's another plugin available which claims to perform a similar task.
Please refer to the docs of the [[plugin:note|Note]] plugin to check whether it will meet your needs.
==== Plugins by the same author ====
* [[bomfix|BOMfix Plugin]] -- ignore Byte-Order-Mark characters in your pages
* [[code2|Code Syntax Plugin]] -- use syntax highlighting of code fragments in your pages
* [[deflist|Definition List Syntax Plugin]] -- use the only complete definition lists in your pages
* [[diff|Diff Syntax Plugin]] -- use highlighting of diff files (aka "patches") in your pages((obsoleted by incorporating its ability into the [[code2|Code]] plugin))
* [[hr|HR Syntax Plugin]] -- use horizontal rules in nested block elements of your pages
* [[lang|LANGuage Syntax Plugin]] -- markup different languages in your pages
* [[lists|Lists Syntax Plugin]] -- use the only complete un-/ordered lists in your pages
* [[nbsp|NBSP Syntax Plugin]] -- use Non-Breakable-Spaces in your pages
* [[nstoc|NsToC Syntax Plugin]] -- use automatically generated namespace indices
* [[shy|Shy Syntax Plugin]] -- use soft hyphens in your pages
* [[tip|Tip Syntax Plugin]] -- add hint areas to your pages
===== Discussion =====
Hints, comments, suggestions ...
it apparently dosent work in new versions??? there is no numbering here, and the tips are showed at the right side of the page.
> Could you be a little bit more specific? What are "new versions"? What did you do, what did you expect and what did you actually get?\\ --- //[[support@mwat.de|Matthias Watermann]] 2007-07-01 15:51//
----
The tips plugin works perfectly in default form (DW 2007-06-26b version). But the **Usage** and **Examples** section above do not give clearly the syntax for using the orientation / type etc. modifiers: only the "default" mode of double parentheses surrounding the tip text is illustrated. The use of space to separate "tip" and between the modifiers is mentioned, but not a full example of a modified annotation. This may seem obvious to some, but it is not to new users, who would be grateful for more detail in this area. //Gerry Leonidas//
> Thanks for your words, anonymous. I admit you're right. -- Well, at least you //were// right: I've very much extended the [[#examples]] section above and hope it now clarifies the doubts one might have had.\\ --- //[[support@mwat.de|Matthias Watermann]] 2007-08-09 19:02//
>> Many thanks! (name added) //Gerry Leonidas//
----
Every time I use multiple lines in a tip, I get a scroll bar. Is there any way to get rid of the scroll bar?\\ --- //John A 2008-04-24 12:41//
> John, scrollbars usually are added by the browser if (a) the available screen space is smaller than the space needed for a given element and (b) the element's CSS rules have an ''overflow'' setting of either ''auto'' or ''scroll'' (as opposed to ''visible'' or ''hidden''). - Having said that: Are you sure you really want another setting? A ''hidden'' setting would just do that: hide the overflowing text. And ''visible'' would overwrite the surrounding text. So both alternatives are worse than scrollbars which at least allow your readers to see the text.\\ BTW: Which browser were you using? Possibly it's just a buggy CSS implementation? Which type of tip did you use?\\ --- //[[support@mwat.de|Matthias Watermann]] 2008/05/18 17:57//
>> After some extensive testing I was able, finally, to reproduce the problem. It occured if the element a tip was associated with happened to be smaller than the contents of the tip (i.e. a height less than the tip's height). I've adjusted the CSS rules for the tip embedded elements and haven't seen any scrollbars since. Please let me know, if you still have problems.\\ --- //[[support@mwat.de|Matthias Watermann]] 2008/05/25 11:37//
----
Hello, this plugin has proven itself to be one I cannot do without!\\ I am wondering what would need to be done to show up in print and/or [[plugin:odt]]?\\ Thanks for an extremely useful plugin!\\ //- Jeff 2008/06/19//
> Thanks for your kind words, Jeff. About your questions:\\ As far as //printing// is concerned a tip's contents should show up the same way as on screen (as you can see [[#Presentation|above]] the presentation rules are intentionally not restricted to screen). However, DokuWiki by default handles (the delivery of) CSS in a, uhm, let's say "strange" way by adding an additional application layer to the CSS files which makes it quite difficult to provide presentation rules for different media, or, as you obviously experienced, a set of rules to be used for both viewing and printing. Anyway, to make a long story short, the only way I know to work around artificially introduced problems is to bypass DokuWiki's default style handling((This involves patching DokuWiki's soruce files and providing an own style sheet with appropriate rules for the ''screen'', ''print'' and ''projection'' output media. The bottom line is you'd have to use your own "template" (in DokuWiki speech), something that's clearly outside the scope of a syntax plugin.)). Hence, I'm afraid, there's nothing the plugin can do about this issue.\\ As for //ODT// export I can just say, that's on my private ToDo list. But since I've to work for a living I can make no promise about a possible time frame. After implementing ODT support for my [[code2|Code]] syntax plugin I know that's a quite time consuming task((for both the experimental ''odt'' plugin's, er, peculiarities and the ODF's specs and reallifebehaviour)). So, please, don't hold your breath.\\ --- //[[support@mwat.de|Matthias Watermann]] 2008/06/20 14:59//
----
**45 classes**? You know that an element can be a member of several classes, so why not have just:
.tipAll{font-family:"Trebuchet MS","Bitstream Vera Sans",Helvetica,sans-serif;font-size:94.4%;margin:0.6ex 0 0.4ex 0;padding:0 0.6ex 0.2ex 0.6ex;line-height:1.2;border:1px solid #999;color:#000;background-color:#ffffee;background-image:none;background-repeat:no-repeat;background-position:1px 1px;min-height:28px;min-width:25%;width:auto;max-width:31%;}
* html body .tip-l, * html body .tip-r {width:30%;}
.tipAll *{font-size:99.9%;margin:0 auto;}
.tip-c {margin-left:auto;margin-right:auto;padding-top:1ex;text-align:center;width:auto;max-width:62%;}
* html body .tip-c {width:62%;}
.tip-l {float:left;text-align:left;margin-right:1.5ex;}
.tip-r {float:right;text-align:right;margin-left:1.5ex;padding-right:1ex;}
.tip-d {margin-top:1.2em;margin-bottom:0;}
.tip-u {margin-top:-1ex;}
.tip-h {background-image:url(img/hint.gif);}
.tip-i {background-image:url(img/info.gif);border-color:#060;}
.tip-n {background-image:url(img/note.gif);border-color:#006;}
.tip-w {background-image:url(img/warn.gif);border-color:#600;}
.tip-h,.tip-i,.tip-n,.tip-w {padding-left:28px;}
and
return array(DOKU_LEXER_ENTER, 'tip-'.$o.' tip-'.$p.(strlen($t)?' tip-'.$t));
...
if (preg_match('|\s*