• View
• Edit
• History
• Attach
• Print
• Backlinks

CSSToolTipsToGo

Questions answered by this recipe

• How can I easily add tooltip functionality ?

Description

Download csstooltipstogo.phpΔ, copy to cookbook folder and add to config.php:

CSSToolTipsToGo allows the easy definition and usage of tooltips..

Tooltips, or popups, are here defined as contents that appear when hovering determinated text areas on a page. This recipe address the creation of those text areas and his associated popup/tooltip contents.

Tooltips classes

Tooltips are grouped into classes. Each class defines the visual behaviour of the the text hovering area and his associated popup/tooltip. Tooltip individual instances of a class can also be further styled.

To define a class, use the (:tooltips ... :) markup:

All the params are optional. if no classname is specified, a default (noname) class is used. The tooltips are positioned by default relative to the hovering area.

• The class='classname' param defines the name of the class.
• The aspect='css-code' param defines the css to be applied to the text-hovering area when no in hover state.
• The hover='css-code' param defines the css to be applied to the text-hovering area in hover state.
• The popup='css-code' param defines the css to be applied to the tooltip/popup contents when made visible.
• The add='css-code' param defines extra css code to be applied to the class (for example to change links included in the text hovering area (see below)).

By default, a no name class, with minimal hide/show mechanics is always implemented. You can also change the behaviour of this class just by using (:tooltips :) without a class param.

Each tooltip class translates to an entry in the $HTMLStylesFmt variable, and gets included once in the head section of the pages (see source for internal details and explanations).

Tooltip classes can be made global to a group by declaring the (:tooltips ... :) markup in the GroupHeader pages (note that if tooltips are used to format search results, those classes must also be defined in the Site.Search page). An alternate way to declare completely global tooltips classes, is by editing your config.php file and under the include_once("$FarmD/cookbook/csstooltipstogo.php"); statement, add for every tooltip class to be defined, a call to the function CSSToolTipsToGoDefine($param), where $param is an string with the contents (params) of the corresponding (:tooltips ... :) declaration.

Tooltips instances

To create a tooltip of a given class, use the [|classname||hovering-text||popup-contents|] markup.

• classname = the name of the class of the tooltip, optionally followed by local css code (see below). Use [|||hovering-text||popup-contents|] to use the default class.
• hovering-text = defines the text area where the hovering will be activated. When the user moves the cursor upon this area, the text gets styled with the 'hover' param of the (:tooltips ...:) directive of the class, and the popup-contents is made visible.
• popup-contents = defines the contents of the tooltip. The actual content is enclosed in an html div tag, so almost any content can be used, plain text, links, PTVs (local or from other oages) or even (:include ...:) directives. The div is styled acording to the 'popup' param of the (:tooltips ...:) directive that defined the class.

Because a default class is already created, you can create tooltips even without previous (:tooltips ... :) definitions:
ie: [|||hover over this text||to make appear this tooltip|].

That will show the text to make appear this tooltip when hovering over hover over this text, not a very useful example.

(:tooltips class='MC' popup='left:2em;top:1.3em;min-width:10em;border:1px solid #000;-moz-border-radius:8px;-webkit-border-radius: 8px;padding:3px 5px;background:#00c;color: #000;font-size:100%;line-height:1.3em;':)

Defines a more interesting class; the text-hovering area is left unaffected, but the tooltip is styled in more detail. Left and top attributes defines where the popup will be show (relative to the start of the hovering area). The tooltips of that class gets also a background color, a rounded box, paddings and a minimal width.

So [|MC||hover over this text||to make appear this tooltip|] will give a better look at the tooltip.

We can also get a more interesting text for the tooltip by including whole page sections or page text variable:
[|MC||hover over this text||to make appear a section of another page = (:include yourpage#youranchor:)|] or
[|MC||hover over this text||the value of the PTVname var of page yourpage is = {yourpage$:PTVname}|]

Refining instances

You can also specify inline css for each instance of a class by adding instance-params to the classname field of the markup with the following syntax:
[|classname instance-params||hovering-text||popup-contents|].

instance-params can specify three different named clauses:

• absolute='0' / '1'. By default tooltips are created with relative positioning. By adding an absolute='1' instance param the tooltip will use absolute positioning.
• aspec='css-code'. The specified css code will be inlined to further refine the aspect of the text hovering area of the tooltip instance.
• popup='css-code'. The specified css code (tipically used to provide ad hoc position/width), will be inlined to be applied to the tooltip contents when made visible.

So [|MC absolute='1' popup='top:100px;left:300px;'||hover over this text||to make appear this tooltip|] will cause the popup to appear at the 100,300 global coordinates.

Going further

The 'add' clause of the (:tooltips ... :) markup can be used to extend the base tooltip class functionality. For example, if the text hovering area has a link, the styling provided by the 'aspect' or 'hover' clauses of the class definition, will not change the look and feel of those links, we need a different html code to do that; that's where the 'add' clause comes in. We can use it to create tooltips classes with extended functionality.

The 'add' clause has the following sintax: add[sufix]='css-code'. The 'sufix' part is only made to split long css declaration in more manageable chunks.

So to create a class of tooltips with support for links enclosed in the text hovering area, we can use the following css code:

add='span.L@CLASS@ a:visited {color: red;} span.L@CLASS@ a:link {color: red;} span.L@CLASS@ a:active {color: red;} span.L@CLASS@ a:hover {color: black; text-decoration: none;}'

or alternatively:

add='span.L@CLASS@ a:visited {color: red;}' add0='span.L@CLASS@ a:link {color: red;}' add1='span.L@CLASS@ a:active {color: red;}' add2='span.L@CLASS@ a:hover {color: black; text-decoration: none;}'

Note that the L@LCLASS@ token will be replaced by the classname. The example, define how html links (the a elements), will behave; the links will be shown in that example, always in red color and normal decorations, except when hovered, then they will turn to black text without decorations.

Note that here we have two hovering sections/estates, the global of the text hovering area, and the text of the link. Each with his own hover css styles. Of course those areas can overlap completely if the text hovering is made of s single link.

On a concrete example:

(:tooltips class=LK 

 aspect='color: #000;'
 hover='background:#ccc;'
 popup='left:2em; top:2em; border:solid; background: #fff;'

 add='span.L@CLASS@ a:visited {color: red;}'
 add0='span.L@CLASS@ a:link {color: red;}'
 add1='span.L@CLASS@ a:active {color: red;}'
 add2='span.L@CLASS@ a:hover {color: black; text-decoration: none;}' :)

Defines a class of tooltips with the hovering text area in black and the links in red; on hovering, the text gets a gray background, and the link becomes black and without decoration.
Try [|LK||Hover over this area [[Link]] Hover over this area||to show this tooltip|], to illustrate the behaviour of the two overlapped hovering areas.

The same technique could also be used for other html tags contained inside the text hovering area.

Caveats

Browser support has been only tested for Konqueror, Firefox and IE. CSS support varies wildly between browser versions, so much test is needed, as this is just an alfa version of the recipe.

For technical details about the inner works of the recipe, the source code explains the generated css/html code and code/markup structure.

Notes

Release notes

• 2011-01-01: 2011-01-01.v.02 second version released
• 2010-10-17: 2010-10-09.v.01 first version released

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

• LinkCSSToolTip (CSSToolTipsToGo has been inspired by this great recipe, thanks!)
• CSSPopups

Contributors

Comments

See discussion at CSSToolTipsToGo-Talk