Extension:Balloons
From MediaWiki.org
 |
WARNING: The code or configuration described here poses a major security risk.
Site administrators: You are advised against using it until this security issue is resolved. Problem: Vulnerable to Cross-site scripting attacks, because it passes user input directly to the browser. This may lead to user accounts being hijacked, among other things. Solution: strictly validate user input and/or apply escaping to all characters that have a special meaning in HTML Bawolff 21:49, 11 June 2011 (UTC) |
 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 and version matrix | |||
Add balloon tooltips to your wiki!
Balloons is a MediaWiki tag extension that uses the magic tag <balloon> to add popup text balloons to wiki pages. It is based on the same balloon.js library used in the generic popup balloon package.
Contents |
Demo [edit]
A sample installation can be seen at Balloons home
Installation [edit]
Download [edit]
Download the package: WBalloons.tar.gz or WBalloons.zip
Required files [edit]
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
Installation steps [edit]
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");
Usage [edit]
- Only the HTML markup normally allowed by MediaWiki will appear inside the popup balloon
- Embedded <script> tags and JavaScript event handlers do not work
Balloons with plain text [edit]
- Plain text can is added on the 'title=' line
<balloon title="Hello I am a tooltip!">Mouse over me!</balloon>
Formatted text and images inside the balloon [edit]
To create a mouseover effect that has formatted text, images, etc, inside the balloon, use the "load:" line. For example, add this to a page:
<balloon title="load:myContent">Mouse over me too!</balloon> |
Below this line, on the same page, add this:
<span id="myContent" style="display:none"> <font color="red">Hello!</font> I am also a ''balloon'' tooltip </span> |
The above is a hidden <span> element that contains the contents of the balloon. (screenshot)
Here is another example of a hidden <span> element, this time with CSS attributes:
<span id="myContent" style="display:none"> <span style="color:red;font-size:16pt"><b>I am some big red text.</b></span> </span> |
The Magic <balloon> Tag [edit]
<balloon> element contents [edit]
- The contents of the balloon tag create the text (or image) that the event handler for the popup balloon is attached.
- The contents of the popup balloon are added inside the balloon tag.
- For security reasons, only plain text (no HTML or Wiki markup) is allowed, except for an <IMG> tag, if desired.
- 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.
Arguments [edit]
| 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 |
Within templates [edit]
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.
UPDATE: This problem can be easily surpassed by using the standard parser fuction #tag, as it is shown below
<div class="floatright">{{#tag:balloon | {{{1}}} | title={{{2|?}}} }}</div>
Custom Skins [edit]
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; }
Source Code [edit]
balloons.php [edit]
<?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; }
balloon.js [edit]
The JavaScript source code for balloon.js can be viewed here
Support [edit]
- This extension is maintained by Sheldon McKay.
- Document any problems on the discussion page or contact the author
