User:PerfektesChaos/js/fragmentAnchors

JavaScript gadget – check uniqueness, validity and show position of anchors in page:

  • Show a anchor symbol at any position where a visible element could be addressed.
    • The name of the identifier is shown as a temporary tooltip above the position when mouse cursor is hovering.
    • The name of the identifier is decoded and presented in human readable spelling.
    • The anchor symbol may be clicked and will permanently show below the position wikisyntax for an internal link. It is accessible for copy&paste. A second click makes the bubble vanish.
  • For faster page rendering the page is not equipped automatically.
    • In tool box (usually in left column of portal) initially only a link is provided, showing a similar anchor symbol.
    • After clicking the tool link the page will be decorated once and the trigger link is removed.
    • If page contents changes significantly the trigger link will reappear.
  • If an id has been repeated in HTML document, the subsequent targets become unreachable.
    • Any multiple id is marked by red anchor symbol on yellow background but shows similar behaviour as unique identifiers.
    • Empty id are invalid, too; they match the entire document and duplicate that.
  • If an inner link has no target in page, this will be marked by # ahead.
    • This is meaningful only in view mode of the entire page. While editing one particular section it might happen quite easily that another section is targetted.
    • If an inner link has a multiplied target (marked by red anchor symbol on yellow background) it is uncertain which target has been intended. Those links will be marked, too.
  • If a structural error has been detected a summary will be inserted into page close to the heading area, on top of content.
    • Multiplied targets will be listed preceded by their number.
    • Missing targets will be listed preceded by their number as negative count.
  • Some identifiers are working but not recommended; containing undesired characters.
    • There the anchor symbol will turn into a red one red anchor symbol but shows similar behaviour as unique identifiers.
  • By default content area is decorated only, but errors will be marked anywhere.
    • It may be configured to mark also anchors in portal environment and source text edit form.

Usage

edit
  • If your project has registered this as a gadget, just activate on your Preferences page.
  • Otherwise include the following lines into your common.js, global.js etc.:
mw.loader.load( "https://en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/fragmentAnchors/r.js&action=raw&bcache=1&maxage=604800&ctype=text/javascript",
                "text/javascript" );

User options

edit

The appearance might be changed via CSS.

The following selectors will be provided:

  • .fragmentAnchors-mark – all inserted elements
  • .error-repeated-id – multiple id
  • .fragmentAnchors-inner – detected inner link
  • .fragmentAnchors-broken – detected inner link without target
  • #fragmentAnchors-mark-errors – error message summary
  • .error – error message summary

JavaScript

edit

The following code should appear on your common.js, global.js or skin dependant JS best before an mw.loader.load() call as described in “Usage” section.

First, the application object is to be etablished:

if ( typeof mw.libs.fragmentAnchors !== "object" ) {
   mw.libs.fragmentAnchors = { };
}

After that, currently there are three options available:

mw.libs.fragmentAnchors.large = true;

This will decorate the full page and does not narrow to content area and not exclude source text edit form.

mw.libs.fragmentAnchors.launch = true;

This will trigger page decoration immediately after loading without generating a link in tool box. It is supposed that loading is limited to certain conditions.

mw.libs.fragmentAnchors.lock = true;

This will prevent from generating a link in tool box and gives opportunity to trigger decoration by any other means, calling .fetch() and .fire() methods.

After the mw.hook fragmentAnchors.ready has been triggered a function may be called. The application object is the parameter of the mw.hook callback function and should be identical with mw.libs.fragmentAnchors.

All functions are components of the application object.

.fetch()

edit

Collect all fragments in HTML document (starting with # and not decoded).

Call .fetch()
Return value
  • Array – three elements
    • [0] Array of string items – all valid fragments in focus
    • [1] Object – all multiplied fragments, else false
      • Every component is a fragment.
      • The number of occurencies is assigned.
    • [2] Object – all missing inner targets, else false
      • Every component is a fragment.
      • The number of occurencies is assigned.
  • false – not yet ready

The document wouldn’t get decorated, except on locations of detected errors.

.fire()

edit

Trigger page decoration from external command.

Call .fire()
Return value
  • true – success
  • false – not yet ready, or already executed

Should declare .lock = true; in advance if link in tool box is undesired.

Testing and experience

edit

A test page provides examples.

Internationalization

edit

Not required, symbols only.

Codes

edit
Source code
ResourceLoader
  • ext.gadget.fragmentAnchors for mw:Extension:Gadgets
  • Dependencies:
    • None required (self-completing); 1. + 2. on startup, 3. when activated
      1. user
      2. mediawiki.util
      3. oojs, oojs-ui-core, oojs-ui-widgets
Namespaces Every.
Cookies None
mw.libs fragmentAnchors
mw.hook fragmentAnchors.ready

When page has been equipped with portlet, or is ready for decoration.

MediaWiki 1.23