User:PerfektesChaos/js/fragmentAnchors

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

• Show a 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 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 .
  • 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 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 ) 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 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

• 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

CSS

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

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.

API

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()

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()

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

A test page provides examples.

Internationalization

Not required, symbols only.

Codes

Source code	Java Script – for load() human readable version
ResourceLoader	ext.gadget.fragmentAnchors for mw:Extension:Gadgets Dependencies: None required (self-completing); 1. + 2. on startup, 3. when activated user mediawiki.util 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