User:V111P/js/msgDisplay

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: 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:  while source-editing a page to insert the display there, and see the config options   and   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. 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: 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  or   instead of   and add the backlink comment as above).

Next, get a reference to a display object: 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  is   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:

returns an existing object if a display with that id had already been created (with a previous call to ) 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  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.
 * - 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  (however if you want to move the display to a new position, you have to   it before calling  ). 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 ,  , and   are removed.
 * - remove the display from the page, clears its contents, resets the help URL to the default one, and removes all event handlers added with,  , and.
 * - returns  if the display is currently being shown,   otherwise.
 * - expand the display to a predetermined height (by default several lines).
 * - collapse the display to a predetermined height (by default: 1 line).
 * - toggle expanding/collapsing the display
 * - add a function to be called when the user presses a key (while the keyboard focus is within the display).
 * - 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, the display won't be closed.
 * - 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, the display won't be closed.
 * - removes all event handlers added with,  , and.
 * - set the help URL (The button with the question mark in the menu opens this page in a new tab/window)
 * - removes all content from the display (and from the buffer). Use  instead of   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 HTML or a jQuery collection to the display buffer (need to call  later to move it to the actual display).
 * - append  to the display buffer as a text string (need to call   later to move it to the actual display). It's using , so all HTML is escaped/converted to plain text.
 * - write everything currently in the buffer (added there with  or  ) to the display. The display must be shown (with  ) to write to it, otherwise   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.
 * - the same as.
 * - the same as.
 * - 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  attribute.
 * - scroll the display to the element  (  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).
 * - get a jQuery collection with the element(s) within the display which are matched by . It first calls write before searching.
 * - 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.
 * - where  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   before   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   it only once, before the first.

Configuration properties
The config method accepts an object with the following properties:
 * - 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).
 * - 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 !
 * - 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 `
 * - 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 . If you set this, set also   to the same or a larger value.
 * - 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 . If you set this, try to set it to less than or equal to the value you give to  . If you don't set this, you can't make the display shorter than its initial height.
 * - 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 . If you don't want the display to expand on double click or in other cases (depending on the application using the display), set   to the same value as.
 * - set the background with a CSS value (which can be a color or an image url). The default is . An example value with an image:  . The image needs to be very light in color, or the text won't be readable.
 * (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  (for mw.util.$content). The default is whatever   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   value is   (the textarea) instead.
 * - "insert-relation": one of  with meanings as in jQuery (for example   means insert as a first element of the element selected with  ). The default is  . Depending on the value of , you may not be able to use some of  . For example,   and   don't make sense for a textarea. The default value is  , except if the display id is edit, in which case the default value is.