Extension:Balloons
From MediaWiki.org
|
Release status: beta |
|||
|---|---|---|---|
| Implementation | Tag, User interface | ||
| Description | Extension to add pop-up balloon tooltips. | ||
| Author(s) | Sheldon McKay | ||
| Last Version | 0.4 (2009-08-25) | ||
| License | MIT-style open source | ||
| Download | WBalloons.zip | ||
| Example | Wiki balloon demo | ||
|
|||
|
check usage (experimental) |
|||
Add balloon tooltips to your wiki!
Contents |
[edit] Purpose
- This is a MediaWiki tag extension that uses the magic tag
<balloon>to add popup balloons to wiki pages. - It is based on the same balloon.js library used in the generic popup balloon package.
[edit] Support
- This extension is maintained by Sheldon McKay.
- Document any problems on the discussion page or contact the author
[edit] Demo
A sample installation can be seen at Balloons home
[edit] Installation
[edit] Download
Download the package: WBalloons.tar.gz or WBalloons.zip
[edit] Required files
The package contains all the required components:
/balloons/balloons.php -- the MediaWiki adapter for balloon.js
/balloons/images/*.png -- the images needed to make the balloons
/balloons/js/balloon.config.js -- configuration info.
/balloons/js/balloon.js -- the library that does all the client-side work
see the documentation
/balloons/js/yahoo-dom-event.js -- part of YAHOO's user interface framework
[edit] Installation steps
1) Unpack the tarball into the extensions directory of your MediaWiki installation
tar zxvf WBalloons.tar.gz OR unzip WBalloons.zip
2) Add a line to LocalSettings.php:
require_once("$IP/extensions/balloons/balloons.php");
[edit] Note on Skins
Note: as of version 0.4 of Extension:Balloons, it is no longer necessary to change the 'balloon.parentID' instance variable according to the skin used.
The modification below only applies to earlier versions of this extension.
- This section only applies for custom skin users and developers
- MediaWiki skins change the CSS layout of the web site, which has an impact on balloon positioning.
- This extension has been tested with the built-in skins Monobook, Chick, Classic, Modern, Cologne Blue, MySkin, Nostalgia and Simple.
- The JavaScript loaded by balloons.php will detect the skin and make the necessary adjustment. However, if you are using a custom skin, it may be necessary to edit the regular expression in the section of balloons.php shown below. The balloon javascript object variable balloon.parentID will either need to 'content' (for most skins) or null, for the Modern, Simple and MySkin skins.
function addBalloonJavascript(&$out) { global $wgScriptPath; $jsPath = "${wgScriptPath}/extensions/balloons/js"; $out->addScript("\n". "<script type=\"text/javascript\" src=\"${jsPath}/yahoo-dom-event.js\"></script>\n" . "<script type=\"text/javascript\" src=\"${jsPath}/balloon.js\"></script>\n" . "<script type=\"text/javascript\">\n" . "var balloon = new Balloon;\n" . "balloon.images = '${wgScriptPath}/extensions/balloons/images';\n" . # Some skins need document.body as the parent, others use the 'content' layer # Custom skin users/developers may need to edit the regular expression below "balloon.parentID = skin.match(/simple|myskin|modern/) ? null : 'content';\n" . "</script>\n" ); return true; }
[edit] Usage
[edit] Balloons with plain text
<balloon title="Hello I am a tooltip!">Mouse over me!</balloon>
[edit] Formatted text and images inside the balloon
- Plain text can simply be added via the 'title' argument
- For formatted text, images, etc, with the "load:" sytax described below
- Note: only the HTML markup normally allowed by MediaWiki will be rendered inside the popup balloon
- embedded <script> tags and JavaScript event handlers are not allowed
This is the how the mouseover effect is created (note the "load:" syntax)
<balloon title="load:myContent">Mouse over me too!</balloon>
This is a hidden <span> element that contains the contents of the balloon
<span id="myContent" style="display:none"> <font color="red">Hello!</font> I am also a ''balloon'' tooltip </span>
This is another example with CSS attributes
<span id="myContent" style="display:none"> <div style="color:red;font-size:16pt"> <b>I am some big red text.</b> </div> <span id="myContent" style="display:none">
[edit] The Magic <balloon> Tag
[edit] Note on <balloon> element contents
- The contents of the balloon tag form the text (or image) to which the event handler for the popup balloon is attached.
- Note: the actual contents of the popup balloon are specified as attributes of the balloon tag.
- For security reasons, only plain text (no HTML or Wiki markup) is allowed, except for an <IMG> tag, if desired.
- Note: JavaScript event handlers are not supported for the image tag
<balloon title="I am a popup balloon" > roll over this text for a popup balloon </balloon>
message in the balloon mouseover text
- Use the "style" argument below to control how the mouseover text (the visible text or link that is moused over or clicked to get a popup balloon) is formatted.
- Formatting of the balloon contents is NOT affected by the style argument. To control CSS inside the balloon, see this section.
[edit] Arguments
| Argument | Description | default value |
|---|---|---|
| title (required) | The balloon contents, which can be plain text or an element id "load:myElement" | |
| sticky | Whether the balloon is sticky (with a close button) or just hovers; 0 or 1 | 0 |
| click | Whether the balloon is triggered by a mouseover (hover) or by clicking; Note: click balloons are always sticky | 0 |
| hover | If the balloon is an onclick balloon, 'hover' adds a non-sticky mouseover balloon also (eg: "click for more info...") | none |
| width | How wide should the ballon be (pixels) | dynamic |
| link | turns the <balloon> element into an <a>; the value of 'link' is the href. For non-click, non-sticky balloons only | none |
| target | If the link argument is used, this specified the target window (eg target="_NEW") | none |
| style | CSS style to apply to the <balloon> contents. (eg: style="color:red;font-size:13pt") | none |
[edit] Within templates
A possible application of balloon templates is to annotate a wiki document with editorial balloons in the right margin. Unfortunately, if you create the following template, neither of the two template parameters properly expand:
Example template:ed -- does not work
<div class="floatright"><balloon title="{{{2|?}}}">{{{1}}}</balloon></div>
However, this can be accomplished with the Bloop extension which functions as a wrapper around balloon tags.
Example template:ed -- works with Bloop version 0.1
<div class="floatright">{{#bloop:{{{2|?}}}|{{{1}}}}}</div>
In the working example, by default the balloon target shows up as a question mark floating against the right margin.
The Bloop extension hooks deeper into the MediaWiki parser and rewrites its fully expanded arguments using the same balloon tag syntax documented here, making it suitable for use within templates. Note that the expanded arguments are therefor subject to the same content restrictions imposed by balloon tags.
[edit] Source Code
[edit] balloons.php
<?php /** * This balloon tooltip package and associated files not otherwise copyrighted are distributed under the MIT-style license: * * http://opensource.org/licenses/mit-license.php * * Copyright * * 2007-2009 Sheldon McKay, Cold Spring Harbor Laboratory * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. * * This is a tag extension that uses the reserved tag <balloon> to add JavaScript ajax * popup balloons. See http://mckay.cshl.edu/wiki/index.php/MediaWiki_Balloon_Extension * for documentation. * * @ingroup Extensions * @author Sheldon Mckay (mckays@cshl.edu) * @version 0.4 * @link http://www.mediawiki.org/wiki/Extension:Balloons */ # To activate the extension, include it at the end from your LocalSettings.php # with: require_once("extensions/balloons.php"); if ( defined( 'MW_SUPPORTS_PARSERFIRSTCALLINIT' ) ) { $wgHooks['ParserFirstCallInit'][] = 'wfBalloonTooltips'; } else { $wgExtensionFunctions[] = 'wfBalloonTooltips'; } $wgHooks['OutputPageBeforeHTML'][] = 'addBalloonJavascript'; $wgExtensionCredits['parserhook'][] = array( 'name' => 'Balloons', 'version' => '0.4', 'author' => 'Sheldon McKay', 'description' => 'Balloon tooltips for wiki pages', 'url' => 'http://www.mediawiki.org/wiki/Extension:Balloons' ); function wfBalloonTooltips() { global $wgParser; $wgParser->setHook( 'balloon', 'renderBalloonSpan' ); return true; } # render span element with function renderBalloonSpan( $input, $args ) { $text = $args['title']; # strip HTML from the text inside the <balloon> element, # except for image tags # remove tag contents first $input = preg_replace('/>[^<>]+</','><',$input); $input = strip_tags($input,'<img>'); # be paranoid and remove any event handlers from image tags $input = preg_replace('/\bon[^=]+=\S+/i','',$input); # escape quotes in balloon caption $text = preg_replace('/\"/','\"',$text); $text = preg_replace('/\'/',"\'",$text); $link = isset($args['link']) ? $args['link'] : ''; $target = isset($args['target']) ? $args['target'] : ''; $sticky = isset($args['sticky']) ? $args['sticky'] : '0'; $width = isset($args['width']) ? $args['width'] : '0'; $event = isset($args['click']) && $args['click'] && !$link ? 'onclick' : 'onmouseover'; $event = "$event=\"balloon.showTooltip(event,'${text}',${sticky},${width})\""; $event2 = ' '; if (preg_match('/onclick/',$event) && $args['hover']) { $event2 = " onmouseover=\"balloon.showTooltip(event,'" . $args['hover'] . "',0,${width})\""; } $has_style = isset($args['style']) && $args['style']; $style = "style=\"" . ($has_style ? $args['style'] . ";cursor:pointer\"" : "cursor:pointer\""); $target = $target ? "target=${target}" : ''; $output = "<span ${event} ${event2} ${style}>${input}</span>"; if ($link) { $output = "<a href=\"${link}\" ${target}>${output}</a>"; } return $output; } function addBalloonJavascript(&$out) { global $wgScriptPath; $jsPath = "${wgScriptPath}/extensions/balloons/js"; $out->addScript("\n". "<script type=\"text/javascript\" src=\"${jsPath}/yahoo-dom-event.js\"></script>\n" . "<script type=\"text/javascript\" src=\"${jsPath}/balloon.config.js\"></script>\n" . "<script type=\"text/javascript\" src=\"${jsPath}/balloon.js\"></script>\n" . "<script type=\"text/javascript\">\n" . "var balloon = new Balloon;\n" . "BalloonConfig(balloon);\n" . "balloon.images = '${wgScriptPath}/extensions/balloons/images';\n" . "</script>\n" ); return true; }
[edit] balloon.js
The JavaScript source code for balloon.js can be viewed here