DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:tip

Tip Syntax PlugIn

Compatible with DokuWiki

2005-07-13+

plugin Use small notes/hints

Last updated on
2008-05-25
Provides
Syntax

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to alertbox, note, wrap

Tagged with boxes

You know those little yellow pieces of paper which so nicely stick all around your screen's fra­me? Lots of “note this” and “remember that” and “don't for­get to …”

Well, when starting yet another technical document I realized that it would be nice to have some­thing like that available for the pages I was going to write. After scan­ning my paperwork it seemed that I needed four kinds of tips: “hints”, “infos”, “notes” and “warnings”. Then I felt the de­sire to place them ver­ti­cal­ly (in relation to the sur­roun­ding text): centered on screen, on the left side and, er, the right side. And finally I thought it would be nice1) to have some con­trol about how to position them hori­zon­tally.

So I ended up with a tag which allows for ten different arguments …

Usage

The easiest use of a “tip” box is just

<tip> some text </tip>

This will place (by means of CSS rules) “some text” on the page's right side.

So what about the “ten different arguments” mentioned above? Here they come:

  • Orientation: “centered”, “left”, “right” (the default);
  • Position: “up”, “down” and “even” (the default);
  • Type: “hint”, “info”, “note”, “warning”, (default: none).

In other words: Each “tag” element has – beside its contents – three “pro­per­ties”: a position, a type and an orientation.

To ease your task of typing the plugin al­lows to write only the first let­ter of each optio­nal ar­gu­ment2). Just for the records, here's a list of all possible com­bi­na­tions (using one-letter shortcuts):

  • centered:c”, “c d”, “c d h”, “c d i”, “c d n”, “c d w”, “c e”, “c e h”, “c e i”, “c e n”, “c e w”, “c u”, “c u h”, “c u i”, “c u n”, “c u w”,
  • left aligned:l”, “l d”, “l d h”, “l d i”, “l d n”, “l d w”, “l e”, “l e h”, “l e i”, “l e n”, “l e w”, “l u”, “l u h”, “l u i”, “l u n”, “l u w”,
  • right aligned:r”, “r d”, “r d h”, “r d i”, “r d n”, “r d w”, “r e”, “r e h”, “r e i”, “r e n”, “r e w”, “r u”, “r u h”, “r u i”, “r u n”, “r u w

Please note, however, that the order of the respective arguments doesn't mat­ter. So in rea­lity there are a lot more possible com­bi­na­tions avail­able for you …

While I took care to make the use of this plugin as easy as possible whilst pro­vi­ding as much flexibility as reasonable feasible, there are some points you should be aware of.

Space characters (“ 3)) are to be used to delimit both the “tip” word and the opt­io­nal ar­gu­ments inside the opening tag.

Above I've grouped the possible arguments into the orientation, type and position property groups. For each property only one (the last) value is actually used. E.g. “<tip cente r>” (no­te the accidential space be­fore the “r”) would result in a right aligned tip box since the “r” ar­gu­ment overwrites the “cente”. This is nei­ther a pitfall nor a bug but is per­fectly sensible if you think about it.

While most other Wiki markup is allowed inside a tip's content4), the nesting of other “tip” boxes is not. Again, this be­ha­viour is by design. Nesting of tips in­side tips wouldn't serve the in­ten­ded pur­pose of this plugin and hence I didn't im­ple­ment it.

The tip tag creates a new block level ele­ment in the docu­ment. In con­se­quen­ce it pro­bab­ly won't work as ex­pec­ted when used in­side Wiki mark­up that doesn't sup­port nested block level ele­ments. For (un/ordered) lists please con­si­der using the Lists plugin which re­places and en­han­ces DokuWiki's built­in list parser and will allow you to place “tip” boxes5) in­side list items. The same is true for the Definition List plugin.

This plugin as such just pre­pa­res the (X)HTML markup – but the real work is done by the rea­der's brow­ser. As the visual ap­pearance of a tip's con­tent is com­ple­tely con­trol­led by sty­ling rules, a CSS con­for­mant web-browser6) is strongly re­com­men­ded.

Examples

In the following examples I'm using only the respec­tive first letter for all pro­perty va­lues. How­ever, you may very well type in the complete name for cla­rity rea­sons if you prefer a more explicit markup style.

I already stated that the easiest way to add a “tip” looks like:

<tip>
	right aligned text
</tip>

which is just the same as giving the default orien­tation (right) and posi­tion (even) pro­perty values expli­citely:

<tip r e>
	right aligned text
</tip>

To place it on the left side switch the orien­tation pro­perty to left:

<tip l>
	left aligned text
</tip>

Similiar if you'd prefer a centered text:

<tip c>
	some centered text
</tip>

Now let's say you'd like to push the tip a bit down (using the default right orien­tation):

<tip d>
	down text, right aligned
</tip>

Similiar if you'd like to move it up a bit:

<tip u>
	up text, right aligned
</tip>

Well, now that you know how to use the position (up, down and the default even) as well as the orien­tation pro­perty (center, left and the default right) you might like to add some gra­phi­cal indi­ca­tion about the type of your tip.

The plugin's source archive contains four small icons7) I've created to dif­feren­ti­ate your “tip” boxes fur­ther (besides posi­tion and orien­ta­tion). Those images get placed at the left/top cor­ner of the tip box if you're using the type property8).

To mark a tip as a hint (aka “see also”) set the type pro­perty to “hint” (or just “h”):

<tip h>
	right aligned hint text
</tip>

To mark a tip as additional information set the type pro­perty to “in­fo” (or just “i”):

<tip i>
	right aligned information text
</tip>

To mark a tip as a note set the type pro­perty to “note” (or just “n”):

<tip n>
	right aligned note text
</tip>

To mark a tip as a warning set the type pro­perty to “warn” (or just “w”):

<tip w>
	right aligned warning text
</tip>

You can, of course, combine this type pro­perty values with any of the po­si­tion and orien­ta­tion pro­perty values, e.g.

<tip l n d>
	left aligned note down
</tip>

The left and right aligned tip boxes will get up to 31% wide of the em­bedding pa­rent ele­ment; the cen­tered boxes will take up to 62% width9).

Hints

The tip's orientation property determines both the location where the tip box gets pla­ced10) and the text align­ment11).

Generally it's a good idea to place the tip markup in your page before12) the text which the tip should align with. – If in doubt use the preview button of Doku­Wiki's page edit form to see the actual result.

Depending on the tip's actual contents – which can be any­thing except another tip – the tip box might be­come larger (i.e. higher) than the neigh­bouring page element. In conse­quence the space occu­pied by the tip box will ex­pand into the visual area of the next page element. While this is all right in many situa­tions it could be distur­bing in others – for example if the next ele­ment is a list or table or code block where an over­lapping tip box wouldn't look that good. In such a case it can be help­ful to use Doku­Wiki's line­break markup (i.e. “\\ ”) to force the next ele­ment visually down until it gets placed below the tip box.

Although the position property allows for mo­ving the tip box up/down a bit, usu­ally the default value (i.e. “even”) is what you want. Hence you should think twice be­fore using other values.

The tip markup allows any content to be placed inside it. But having the option to do so doesn't mean that you're forced to use it. After all, the plugin's pur­pose is to allow for rela­tively small notes to be placed along the normal text. Hence you should resist the tempta­tion to put long essays, lists or tables in a tip box.

While it's easy to create funny effects by using this plugin, a page author should always be aware of the old rule: Less Is More. — In other words: Be­fore you're going to empha­sise some text by ta­king it out of the stan­dard rea­ding flow you should con­sider care­fully whe­ther it wouldn't be better – for both the page de­sign and the reader's reception – if you'd just re­phrased your words to make them part of the stan­dard flow of text.

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Plugin Source

Here comes the GPLed PHP source13) for those who'd like to scan it be­fore actu­ally in­stal­ling it:

<?php
if (! class_exists('syntax_plugin_tip')) {
  if (! defined('DOKU_PLUGIN')) {
    if (! defined('DOKU_INC')) {
      define('DOKU_INC', realpath(dirname(__FILE__) . '/../../') . '/');
    } // if
    define('DOKU_PLUGIN', DOKU_INC . 'lib/plugins/');
  } // if
  // Include parent class:
  require_once(DOKU_PLUGIN . 'syntax.php');
 
/**
 * <tt>syntax_plugin_tip.php </tt>- A PHP4 class that implements
 * a <tt>DokuWiki</tt> plugin for <tt>small notes/tips fragments</tt>.
 *
 * <p>
 * Usage:<br>
 * <tt>&lt;tip [c|l|r] [u|e|d] [h|i|n|w]&gt;some text&lt;/tip&gt;</tt>
 * </p><pre>
 *  Copyright (C) 2006, 2007  M.Watermann, D-10247 Berlin, FRG
 *      All rights reserved
 *    EMail : &lt;support@mwat.de&gt;
 * </pre><div class="disclaimer">
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either
 * <a href="http://www.gnu.org/licenses/gpl.html">version 3</a> of the
 * License, or (at your option) any later version.<br>
 * 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.
 * </div>
 * @author <a href="mailto:support@mwat.de">Matthias Watermann</a>
 * @version <tt>$Id: syntax_plugin_tip.php,v 1.5 2007/08/15 12:36:19 matthias Exp $</tt>
 * @since created 02-Dec-2006
 */
class syntax_plugin_tip extends DokuWiki_Syntax_Plugin {
 
  /**
   * @privatesection
   */
  //@{
 
  /**
   * HTML special characters to replace in <tt>render()</tt>.
   *
   * @private
   * @see render()
   */
  var $_Chars = array('&', '<', '>');
 
  /**
   * Entity replacements for HTML special characters.
   *
   * @private
   * @see render()
   */
  var $_Ents = array('&#38;', '&#60;', '&#62;');
 
  //@}
  /**
   * @publicsection
   */
  //@{
 
  /**
   * Tell the parser whether the plugin accepts syntax mode
   * <tt>$aMode</tt> within its own markup.
   *
   * @param $aMode String The requested syntaxmode.
   * @return Boolean <tt>TRUE</tt> unless <tt>$aMode</tt> is
   * <tt>'plugin_tip'</tt> (which would result in a <tt>FALSE</tt>
   * method result).
   * @public
   * @see getAllowedTypes()
   */
  function accepts($aMode) {
    return ('plugin_tip' != $aMode);
  } // accepts()
 
  /**
   * Connect lookup pattern to lexer.
   *
   * @param $aMode String The desired rendermode.
   * @public
   * @see render()
   */
  function connectTo($aMode) {
    $this->Lexer->addEntryPattern(
      '\x3Ctip(?:\s+[a-z ]*\s*)*\x3E(?=.*?\x3C\x2Ftip\x3E)',
      $aMode, 'plugin_tip');
  } // connectTo()
 
  /**
   * Get an array of mode types that may be nested within the
   * plugin's own markup.
   *
   * @return Array Allowed nested types (i.e. all known types).
   * @public
   * @see accepts()
   * @static
   */
  function getAllowedTypes() {
    return array(
      'container',
      'baseonly',
      'formatting',
      'substition', // sic! should be __substitution__
      'protected',
      'disabled',
      'paragraphs');
  } // getAllowedTypes()
 
  /**
   * Get an associative array with plugin info.
   *
   * <p>
   * The returned array holds the following fields:
   * <dl>
   * <dt>author</dt><dd>Author of the plugin</dd>
   * <dt>email</dt><dd>Email address to contact the author</dd>
   * <dt>date</dt><dd>Last modified date of the plugin in
   * <tt>YYYY-MM-DD</tt> format</dd>
   * <dt>name</dt><dd>Name of the plugin</dd>
   * <dt>desc</dt><dd>Short description of the plugin (Text only)</dd>
   * <dt>url</dt><dd>Website with more information on the plugin
   * (eg. syntax description)</dd>
   * </dl>
   * @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 '
        . '[<tip [c|l|r] [u|e|d] [h|i|n|w]> ... </tip>]',
      'url' =>  'http://www.dokuwiki.org/plugin:tip');
  } // getInfo()
 
  /**
   * Define how this plugin is handled regarding paragraphs.
   *
   * <p>
   * This method is important for correct XHTML nesting.
   * It returns one of the following values:
   * </p>
   * <dl>
   * <dt>normal</dt><dd>The plugin can be used inside paragraphs.</dd>
   * <dt>block</dt><dd>Open paragraphs need to be closed before
   * plugin output.</dd>
   * <dt>stack</dt><dd>Special case: Plugin wraps other paragraphs.</dd>
   * </dl>
   * @return String <tt>"normal"</tt> 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 <tt>415</tt> (not really important here).
   * @public
   * @static
   */
  function getSort() {
    return 415;
  } // getSort()
 
  /**
   * Get the type of syntax this plugin defines.
   *
   * @return String <tt>"container"</tt>.
   * @public
   * @static
   */
  function getType() {
    return 'container';
  } // getType()
 
  /**
   * Handler to prepare matched data for the rendering process.
   *
   * <p>
   * The <tt>$aState</tt> parameter gives the type of pattern
   * which triggered the call to this method:
   * </p>
   * <dl>
   * <dt>DOKU_LEXER_ENTER</dt>
   * <dd>a pattern set by <tt>addEntryPattern()</tt></dd>
   * <dt>DOKU_LEXER_EXIT</dt>
   * <dd> a pattern set by <tt>addExitPattern()</tt></dd>
   * <dt>DOKU_LEXER_UNMATCHED</dt>
   * <dd>ordinary text encountered within the plugin's syntax mode
   * which doesn't match any pattern.</dd>
   * </dl>
   * @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 <tt>[0]</tt> holds the current
   * <tt>$aState</tt>, index <tt>[1]</tt> the match prepared for
   * the <tt>render()</tt> 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.
   *
   * <p>
   * The method checks for the given <tt>$aFormat</tt> and returns
   * <tt>FALSE</tt> when a format isn't supported. <tt>$aRenderer</tt>
   * is a reference to the renderer object which is currently
   * handling the rendering. The contents of <tt>$aData</tt> is
   * the return value of the <tt>handle()</tt> method.
   * </p>
   * @param $aFormat String The output format to generate.
   * @param $aRenderer Object A reference to the renderer object.
   * @param $aData Array The data created/returned by the
   * <tt>handle()</tt> method.
   * @return Boolean <tt>TRUE</tt> if rendered successfully,
   * or <tt>FALSE</tt> otherwise.
   * @public
   * @see handle()
   */
  function render($aFormat, &$aRenderer, &$aData) {
    if ('xhtml' != $aFormat) {
      return FALSE;
    } // if
    // XXX: All those "</p>" and "<p>" 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*<p>\s*$|i', $aRenderer->doc, $hits)) {
          $aRenderer->doc = substr($aRenderer->doc,
            0, -strlen($hits[0])) . '<div class="tipAll tip'
              . $aData[1] . '"><p>';
        } else {
          $aRenderer->doc .= '</p><div class="tipAll tip'
            . $aData[1] . '"><p>';
        } // 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*<p>\s*</p>\s*|', '',
          $aRenderer->doc) . '</p></div><p>';
      default:
        return TRUE;
    } // switch
  } // render()
 
  //@}
} // class syntax_plugin_tip
} // if
//Setup VIM: ex: et ts=2 enc=utf-8 :
?>

Presentation

As mentioned above the important work is done by means of CSS.

There are 45 different CSS classes in total to rule all pos­sible com­bi­na­tions of op­tional 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 clas­ses: they're crea­ted by the plugin auto­ma­ti­cally and in­ter­pre­ted by the rea­der's brow­ser using the asso­cia­ted sty­ling rules. I've listed them here just for infor­ma­tio­nal pur­poses.

Starting with the 2007-08-06 release of this plugin a CSS class “tipAll” is addi­tio­nally set for all tip ele­ments. This is mostly meant to ease the CSS sty­ling of em­bedded ele­ments such as e.g. links or para­graphs14).

.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 styles15) to suit your personal needs or aesthe­tics16).

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

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 Note plugin to check whether it will meet your needs.

Plugins by the same author

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?
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.
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?
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.
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 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 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 handling18). 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 Code syntax plugin I know that's a quite time consuming task19). So, please, don't hold your breath.
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*<p>\s*$|i', $aRenderer->doc, $hits)) {
          $aRenderer->doc = substr($aRenderer->doc,
            0, -strlen($hits[0])) . '<div class="tipAll '
              . $aData[1] . '"><p>';
        } else {
          $aRenderer->doc .= '</p><div class="tipAll '
            . $aData[1] . '"><p>';
        } // if
 
 

This would make customizing so much gentler to the brain. — Magnus Holmgren

1)
You know that feeling, don't you? Once you've got your super-duper-hyper-ice­cream your pa­rents think you'd be happy finally. – But you only think how nice some straw­berries would be. And some chocolates. And some …
2)
In fact, the plugin only uses the arguments' first letter. So you could for example write “<tip let newbies dance>” which would result in a left aligned note moved down a bit.
3)
space: ASCII char #32 — not to be confused with blanks, ASCII char #255
4)
i.e. the text bet­ween the ope­ning and closing tip tags
5)
and, of course, other block level ele­ments as well …
6)
such as Firefox or Opera
7)
of 24×24 pixels size each in GIF89a format
8)
by default no image is used
9)
assuming you don't change the settings of the provided CSS rules
10)
by means of CSS float
11)
by means of CSS text-align
12)
i.e. in front of
13)
The comments within the source file are suitable for the OSS doxygen tool, a do­cu­men­ta­tion sy­stem for C++, C, Java, Ob­jec­tive-C, Python, IDL and to some extent PHP, C#, and D. — Since I'm working with dif­fe­rent pro­gram­ming lan­gua­ges it's a great ease to have one tool that handles the docs for all of them.
14)
So instead of 45 possible selectors for all kinds of tips you can use the “tipAll” class to catch them all.
15)
The source archive contains a commented and indented stylesheet for your in­for­ma­tion.
16)
Just be careful when modifying a CSS file: both the order and the selector grou­pings are im­por­tant for CSS to work as intended/expected.
17)
obsoleted by incorporating its ability into the Code plugin
18)
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.
19)
for both the experimental odt plugin's, er, peculiarities and the ODF's specs and reallifebehaviour
plugin/tip.txt · Last modified: 2018-08-02 08:23 by Aleksandr

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki