User:V111P/js/msgDisplay

Smart Linking using a MsgDisplay in a single line mode

Message Display (msgDisplay.js) is a script that can be used by other scripts to display messages to the MediaWiki user.

Try it right now! Open your JavaScript console, enter the code in the "How to use" section below to load the script, then wait a second and enter the following:

mw.libs.msgDisplay('yourDisplayIdHere')
.show()
.append('Some message here (double click to see more)<br/>More<br/>information<br/>here.')
.write();

The display will appear at top of the page, under the page heading (in most skins). Double click on the display and/or try resizing it by dragging its bottom edge and its right edge. You can change the position of the display. For example, I'm only using it above the textarea on editing pages (in Smart Linking). Try using the string edit as an id: mw.libs.msgDisplay('edit').show(); while source-editing a page to insert the display there, and see the config() options insertRelTo and insertRel below. Note that the position may affect the font size of the text within the display.

The script was designed to be useful for the Smart Linking tool, but with the idea that it can also be used by other tools. If you are going to be using it, it would be best to let me know and add this and the .js page to your watchlist, so you get notified of any changes.

There is a help page for end users - this is the page that opens in another browser window/tab when the users click on the [?] button in the menu when the script author hasn't set their own help URL with helpUrl(). You may also want to link to that page from your documentation, or you may include that information directly into your documentation.

You can edit this page. If I don't like or understand something you wrote, I will correct it. ;)

How to use

First, you need to load the script file.

You can simply use an ajax call to do this:

if (!mediaWiki.libs.msgDisplay)
	$.ajax({ // Backlink: [[User:V111P/js/msgDisplay.js]]
		url: '//en.wikipedia.org/w/index.php?title='
			+ 'User:V111P/js/msgDisplay.js&action=raw&ctype=text/javascript',
		dataType: 'script',
		cache: true
	});

However, if you need to detect when it loads and do something immediately, you need to do more work, which I'll explain later if somebody asks me to (check User:V111P/js/valSel for an example, but use mediaWiki.libs or mw.libs instead of $.fn and add the backlink comment as above).

Next, get a reference to a display object:

var myDisplay = mediaWiki.libs.msgDisplay(id);

where id is the unique display id of the display you want to use (use only latin letters, digits 0-9, dashes, underscores, do not use id starting with an underscore). If no id is provided, the name top will be used. The top and also the edit displays are intended to be used by many different applications and they should only be updated after a user action such as pressing a specific button, etc., otherwise you may hide information displayed there by another script before the user is able to read it.

The top display by default is displayed near the top of the page - below the main heading (at the beginning of the element pointed at by mw.util.$content, which depend on the skin). The edit display presently is only supposed to be used on source-editing pages, in which case by default it is displayed above the textarea (accounting for the Dot's Syntax Highlighter gadget, if it's being used; and also for the WikEd editor if it's being used; you get these fixes if the value of insertRelTo is #wpTextbox1 regardless of the display's id). Using the edit id also ensures that the textarea will be focused when the user clicks the [X] or [_] buttons in the menu or collapses the display with a double click. You can request this for other displays by calling:

myDisplay.onCloseOnUserAction(myDisplay.focusTextbox1)
.onCollapseOnUserAction(myDisplay.focusTextbox1);

msgDisplay(id) returns an existing object if a display with that id had already been created (with a previous call to msgDisplay) or otherwise creates a new object.

After you get a reference to a display object with the above code, you can call the methods listed below on it (and most of these methods can be chained, because they return the display object). Note that you must call show() before appending to the display, because that method clears the display and the buffer. The documentation is currently incomplete (the method parameters are not shown and described here), so you'll need to look at the source code as well.

show - insert the display on the page. But if the display is already on the page, it is collapsed and its height and background are updated if previously changed with config() (however if you want to move the display to a new position, you have to remove() it before calling show()). If the display is already on the page and its ID is top or edit, the help url is reset to the default one (the Message Display's help url), and the event handlers added with onCloseOnUserAction, onCollapseOnUserAction, and keypress are removed.
remove - remove the display from the page, clears its contents, resets the help URL to the default one, and removes all event handlers added with onCloseOnUserAction, onCollapseOnUserAction, and keypress.
isShown - returns true if the display is currently being shown, false otherwise.
expand - expand the display to a predetermined height (by default several lines).
collapse - collapse the display to a predetermined height (by default: 1 line).
expandCollapse - toggle expanding/collapsing the display
keypress - add a function to be called when the user presses a key (while the keyboard focus is within the display).
onCloseOnUserAction - add a callback function to be called when the user presses a key or clicks a button that causes the display to get closed. If any of the added functions returns false, the display won't be closed.
onCollapseOnUserAction - add a callback function to be called when the user presses a key or clicks a button that causes the display to get collapsed. If any of the added functions returns false, the display won't be closed.
removeAllEventHandlers - removes all event handlers added with onCloseOnUserAction, onCollapseOnUserAction, and keypress.
helpUrl - set the help URL (The button with the question mark in the menu opens this page in a new tab/window)
clear - removes all content from the display (and from the buffer). Use show() instead of clear() if you are using one of the special display IDs (top or edit) to ensure that the event handlers that may have been added by another application are cleared and the help page URL is reset (otherwise it may point to another application's help page if your script doesn't itself set it to point to its help page).
append - append HTML or a jQuery collection to the display buffer (need to call write() later to move it to the actual display).
appendText(str) - append str to the display buffer as a text string (need to call write() later to move it to the actual display). It's using document.createTextNode(str), so all HTML is escaped/converted to plain text.
write - write everything currently in the buffer (added there with append() or appendText()) to the display. The display must be shown (with show()) to write to it, otherwise write() has no effect. The reason there is a buffer is that DOM modification of the page is slow and it's better to modify a detached document fragment and insert it on the page only once.
appendWrite - the same as append().write().
appendTextWrite - the same as appendText().write().
focus(arg) - set the keyboard focus on an element within the display. The argument is a jQuery selector string, an HTML DOM object or a jQuery collection. Note that only certain HTML elements can get the keyboard focus, such as an anchor with a href attribute.
scrollTo(el, focusEl) - scroll the display to the element el (el can be a jQuery selector or an HTML DOM node or a jQuery collection). if focusEl is true, also focuses that element (however, only certain HTML elements can receive the focus).
find(jQuerySelector) - get a jQuery collection with the element(s) within the display which are matched by jQuerySelector. It first calls write() before searching.
focusTextbox1() - focus the textarea (wpTextbox1). See above the discussion about the display ID to see why this is convenient to be here. This method also captures and restores the page scroll position before and after the focusing, to fix an Internet Explorer bug.
config(configObj) - where configObj can have the properties described in the section below. When configuring the displays with IDs top and edit be careful because that may also affect other applications using them. When using a display with one of these IDs you should always call config() before show() to set your options again. When using another ID, it's expected that no other application will use that display and change its configurations, so you can config() it only once, before the first show().

Configuration properties

The config() method accepts an object with the following properties:

closeChar - a character which, when typed while the keyboard focus is on the display, causes the display to disappear and the keyboard focus to be returned to the textarea. The default is ^ (grave accent).
expandCollapseChar - a character which, when typed while the keyboard focus is on the display, causes the display to expand if it is not already expanded, otherwise it collapses and return the keyboard focus to the textarea. The default is !
blurChar - a character which, when typed while the keyboard focus is on the display, causes the display to collapse and returns the keyboard focus to the textarea. The default is `
height - the initial height of the display. Can be just a number (which means it's in pixels) or a string with a number and one of the CSS units. The default value is '1.4em'. If you set this, set also expandHeight to the same or a larger value.
minHeight - height in number of pixels (no CSS units allowed). You can't resize the display with the mouse to be shorter in height than that. The default is whatever value you give to height. If you set this, try to set it to less than or equal to the value you give to height. If you don't set this, you can't make the display shorter than its initial height.
expandHeight - the height to which the display will be expanded in certain cases, such as on double click. Set this to greater than or equal to height. If you don't want the display to expand on double click or in other cases (depending on the application using the display), set expandHeight to the same value as height.
background - set the background with a CSS value (which can be a color or an image url). The default is '#fed'. An example value with an image: 'url(//upload.wikimedia.org/wikipedia/commons/0/0f/Wiki_background.jpg)'. The image needs to be very light in color, or the text won't be readable.
insertRelTo (advanced) - "insert relative to": an HTML DOM element or a jQuery selector for the element before, after or within which the display is to be inserted, or 'content' (for mw.util.$content). The default is whatever mw.util.$content points to, which depends on the skin you are using, but in Vector, for example, is the area of the page starting after the article title and ending with the categories at the bottom of the page. However if the display id is edit, the default insertRelTo value is '#wpTextbox1' (the textarea) instead.
insertRel - "insert-relation": one of 'before', 'after', 'prepend', 'append' with meanings as in jQuery (for example 'prepend' means insert as a first element of the element selected with insertDisplayRelToSelector). The default is 'before'. Depending on the value of insertRelToSelector, you may not be able to use some of 'before', 'after', 'prepend', 'append'. For example, 'prepend' and 'append' don't make sense for a textarea. The default value is 'prepend', except if the display id is edit, in which case the default value is 'before'.

How to use

Configuration properties

See also