User:Remember the dot/Syntax highlighter

From MediaWiki.org
Jump to: navigation, search
Language: English  • català • español • Ido
Dot's Syntax Highlighter 2012-12-06.png

I've created a script that makes syntax stand out colorfully in the edit box. Unlike other syntax highlighter scripts such as wikEd and AceWikiEditor, this one:

  • Updates the highlighting automatically as you type.
  • Does not break the Undo and Redo buttons.
  • Does not break spellcheck.
  • Is compatible with most other scripts that affect the edit box.

Installation[edit | edit source]

Please be sure to read the "Known issues" section below before installing the script.

For end user if installed on wiki[edit | edit source]

If the syntax highlighter is available as a gadget on your wiki, go to your preferences and enable it.

For end user if not installed on wiki[edit | edit source]

If installation as a gadget is not available, add these lines to your common.js page:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

For example, if the English Wikipedia did not provide the syntax highlighter as a gadget, you would add it to

https://en.wikipedia.org/wiki/User:YourUsername/common.js

For administrators of Wikimedia sites[edit | edit source]

On your wiki create the page MediaWiki:Gadget-DotsSyntaxHighlighter.js‎ with the code

mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

Then add to the page MediaWiki:Gadgets-definition‎ a new line

*DotsSyntaxHighlighter[ResourceLoader|default]|DotsSyntaxHighlighter.js

and create the page MediaWiki:Gadget-DotsSyntaxHighlighter‎ with the text

Make syntax stand out colourfully in the edit box.

For administrators of non-Wikimedia sites[edit | edit source]

MediaWiki 1.22 or later[edit | edit source]

On your wiki create the page MediaWiki:Gadget-DotsSyntaxHighlighter.js‎ and copy the source code from User:Remember the dot/Syntax highlighter.js into it. Then add to the page MediaWiki:Gadgets-definition‎ a new line

*DotsSyntaxHighlighter[ResourceLoader|default]|DotsSyntaxHighlighter.js

and create page MediaWiki:Gadget-DotsSyntaxHighlighter‎ with the text

Make syntax stand out colourfully in the edit box.

MediaWiki 1.21 or earlier[edit | edit source]

In addition to the steps for MediaWiki 1.22, add the following to MediaWiki:common.js:

if (!((wgNamespaceNumber == 2 || wgNamespaceNumber == 8) && /\.(?:css|js)$/.test(wgTitle)))
{
    wgPageContentModel = "wikitext";
}

Make sure to remove this code after upgrading to MediaWiki 1.22 or later.

Known issues[edit | edit source]

Compatibility[edit | edit source]

  1. The highlighter works best in the latest version of Firefox.
  2. The highlighter works almost all of the time in the latest versions of Chrome and Opera, but does not work right with text written in certain scripts, notably Thai and Tibetan.
  3. I was not able to test Safari. I would expect it to work the same as Chrome but slower.
  4. The highlighter does not work in Internet Explorer (its bugs are too severe).
  5. The highlighter might mess up if used in combination with any browser's page zoom feature.
  6. The highlighter is not compatible with certain scripts that affect the edit box.

Parsing[edit | edit source]

  1. For performance reasons, the highlighter requires all tags to be valid XML. For example, make sure that if you start a <p> tag you end it with </p>, and use <br/> instead of <br>.
  2. For performance reasons, the syntax highlighter can't handle '''apostrophe italic'' or ''italic apostrophe'''—it considers them invalid syntax. I suggest using '<i>apostrophe italic</i> and <i>italic apostrophe'</i> instead.
  3. A <pre> tag created by putting a space at the beginning of a line will not be highlighted. This is because the highlighter is not smart enough to tell when a space at the beginning of a line counts as whitespace inside a template.
  4. __NOTOC__ etc. are not highlighted.

Miscellaneous[edit | edit source]

  1. The highlighter does not perform well when editing long articles and will automatically disable itself if it delays more than 100ms.
  2. The highlighter does not work when uploading files.
  3. The highlighter may override your user styles related to the editing textbox.
  4. The colors I chose may not be very appealing. Feedback from a graphic designer would be appreciated ;-)

Customizing[edit | edit source]

It's easy to change the highlighter to use different colors or to not highlight certain syntaxes. See the #Color list section below for the available settings. For example, to make wikilinks cyan and external links orange you could use:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');
 
syntaxHighlighterConfig = {
    externalLinkColor: "#FFCC66", //orange
    wikilinkColor: "#E6FFFF", //cyan
}

If you installed the highlighter as a gadget, the first two lines are not necessary.

To not highlight a syntax, set its color to "". For example, to disable external link highlighting:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');
 
syntaxHighlighterConfig = {
    externalLinkColor: "",
}

To not highlight any syntax except those you explicitly want, set defaultColor to "" and set the color of each syntax you want to highlight. If you just want the usual color, set the color to "normal". For example, to only highlight tags:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');
 
syntaxHighlighterConfig = {
    defaultColor: "",
    tagColor: "normal",
}

Furthermore, you can specify a timeout that replaces the default 100ms timeout. For example:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');
 
syntaxHighlighterConfig = {
    timeout: 150, //disable highlighting if it takes more than 150ms
}

Color list[edit | edit source]

The following customizations are available:

defaultColor for recognized syntax elements that don't have a specific color defined
boldOrItalicColor '''bold''' ''italic''
wikilinkColor [[wikilink]]
externalLinkColor [http:// named external link], http://bare-external-link.com
headingColor ==Heading==, ;Small heading
listOrIndentColor * unordered list, # ordered list, : indent
signatureColor ~~~~
tableColor {| table |}
templateColor {{template}}
parameterColor {{{template parameter}}}
hrColor ----
tagColor <tag>...</tag>, <tag/>
commentColor <!-- comment -->
entityColor &entity;

Reporting bugs[edit | edit source]

Note: Remember to check whether the bug you want to report is already a known issue.

When reporting bugs to me, please include:

Source code[edit | edit source]

To reduce download time and because the ResourceLoader does not automatically minify scripts imported from other wikis, MediaWiki:Gadget-DotsSyntaxHighlighter.js itself is kept in minified form. The actual source code is available at User:Remember the dot/Syntax highlighter.js.

Overview of approach[edit | edit source]

This script creates a background div, named wpTextbox0, that is inserted behind wpTextbox1, the editing textbox. wpTextbox0 and wpTextbox1 are synchronized in style, and the background of wpTextbox1 is made transparent so that wpTextbox0 shows through. Then, blocks of text are added to wpTextbox0 as span elements. The text on the blocks is transparent, but the backgrounds of the blocks are colored. By using the same text in wpTextbox0 as wpTextbox1, any positioning anomalies from dynamically composed characters are eliminated. Because wpTextbox0 and wpTextbox1 are (theoretically) perfectly synchronized, the colored backgrounds appear to the user as though they have been added directly to wpTextbox1.

The text in wpTextbox0 is not actually added to the textContents of the span elements. Instead, it is added to the :before and :after pseudo-elements of each span using a dynamically generated CSS stylesheet. This avoids problems when trying to use the browser's find-in-page feature, because if textContent were used instead of CSS content, the browser would perceive both the real text in wpTextbox1 and the transparent text in wpTextbox0 to be on the page.