mic_none

User:Cacycle/wikEd development Source: en.wikipedia.org/wiki/User:Cacycle/wikEd_development

Please support wikEd

[edit]

Please support wikEd by helping to fix the following browser and MediaWiki issues.

  • Firefox:
    • 579763, 579760 Cursor/caret disappears (07-2010)
    • 1016372 Space lost when deleting text (05-2014)
    • 926230 Space at end of line not styled (10-2013)
    • 543204 Focus after search (01-2010)
    • 926164 Editor deletes blank before inserted block element when converting to text (10-2013)
    • 458524 Automatic syntax highlighting would interfere with undo/redo. The only reason why wikEd does not have automatic syntax highlighting. (10-2008)
  • Webkit/Chrome:
    • None.
wikEd
WikEd logo
Installation
wikEd diff
Program code
Project
Gadgets
Translations

This is the developer page and program documentation for wikEd, a full-featured in-browser text editor that adds enhanced text processing functions to Wikipedia and other MediaWiki edit pages. Please use this talk page for discussing wikEd development issues.

How it works

[edit]

wikEd replaces the classic textarea input field with an iframe in designmode. That is essentially a separate html page that can be edited. The browser's rich-text editing interface is used to manipulate the text upon clicking a wikEd button, see [1]. After pushing the Save page button the content is copied back to the hidden textarea and then submitted.

Program structure

[edit]

(Somewhat outdated)

  • Basic initialization
Built-in user interface texts
Edit-frame css rules
Main window css rules
Button image URLs
Button definitions
Toolbar definition
User customizable variables
Global variables including DOM elements
Check for updates (Ajax)
Schedules the setup routine to run after the page has been loaded
  • WikEdSetup() — the setup routine
Loads the diff script
Loads the Live Preview script
Rearranges page elements into wrapper divs
Puts the wikEd buttons on the page
Generates the combo input boxes (input with drop-down button)
Generates the iframe in design mode that replaces the classic textarea input field
Copies the textarea content to the iframe
  • Event handler definitions
Load and parse the RegExTypoFix rules using Ajax
  • WikEdAutoUpdate() — check for the latest version using Ajax, forced reload of page to update
  • WikEdLoadTypoFixRules() — load and parse the RegExTypoFix rules using Ajax
  • The button handlers:
    • WikEdButton() — for buttons that do not require nor change the text (fast)
    • WikEdEditButton() — for buttons that require or change the text (slow)
  • Helper subroutines:
    • WikEdWikifyHTML() — converts pasted html code into plain text wikicode
    • WikEdHighlightSyntax() — highlights the syntax by adding html code to the plain text
    • WikEdUpdateTextarea() - copies the frame content to the textarea, strips html formatting
    • WikEdUpdateFrame() - copies the textarea content to the frame
    • WikEdGetInnerHTML() - gets the innerHTML from a document fragment
    • Cookie management routines
    • Get recursive custom offsets:
      • WikEdGetOffsetTop() - gets the element offset relative to the window top
      • WikEdGetOffsetLeft() - gets the element offset relative to the left window border
    • WikEdParseDOM() - parses a DOM subtree and and adds the plain text into a complex data structure
    • WikEdStyleSheet() - creates a new style sheet object (cross-browser)
    • Debugging routines
    • WikedInsertTags(): overrides the insertTags function in wikibits.js, used for the standard Wikipedia toolbar buttons

Programming conventions

[edit]
  • Subroutine names start uppercase
  • Variable names start lowercase
  • Global variables have the form wikEd.xxx, global functions wikEd.Xxx (uppercased).

Greasemonkey-compatibility

[edit]
  • Global variables must be declared as follows:
  • window.wikEd = {}; wikEd.variable = 123;
  • Global subroutines must be declared as follows:
    wikEd.Subroutine = function(parameter) { ... }
  • Event listeners must be registered as follows, DOM element declarations (onclick="") do not work:
    element.addEventListener('click', WikEdGlobalFunction, true);
    element.addEventListener('click', function(event, variable) { ... }, true); // uses the last value of variable
    If possible, please use the wikEd wrapper: WikEdAddEventListener(element, 'click', WikEdGlobalFunction, true)
  • Custom attributes of DOM elements:
    element.setAttribute('custom') = 123;
    var attribString = element.getAttribute('custom'); // it is always a string!
  • It is NOT possible to access functions, objects, or variables from other scripts running on the page! However, it is possible to access variable values using the function wikEd.GetGlobals().

Debugging setup

[edit]

For performance reasons it is highly recommended to test the scripts on a local copy of a Wikipedia edit page. (Outdated) 

 var wikEdAutoUpdate = false;
 var wikEdUseLocalImages = true;
 var wikEdImagePathLocal = 'file:///D:/wikEd/images/'; // the directory were you keep all wikEd button images
 var wikEdSkipBrowserTest = true; // this enables wikEd under IE and Opera
 var wikEdShowSourceButton = true;
 var wikEdDiffScriptSrc = 'file:///D:/wikEd/diff.js'; // the local diff program used for 'Show current changes below'
 var wikEdInstaViewSrc = 'file:///D:/wikEd/instaview.js'; // InstaView AJAX preview

For finally testing the code on Wikipedia, every developer should create a code page in his own user space ending with .js (e.g. User:YourUsername/wikEd_dev.js). These pages can only be edited by the owner for security reasons.

Making wikEd cross-browser compatible

[edit]

There is the new library IERange that provides DOM ranges for MS IE. This seems to work in general and has been added to wikEd. However, MSIE has no support for execCommand('inserthtml', code); and the workaround frameDocument.selection.createRange().pasteHTML(code); breaks the undo history!

wikEd API

[edit]
See also: wikEd customization - custom_buttons

wikEd has the following hooks for custom function that are executed at certain events:

  • wikEd.config.setupHook, executed after wikEd has been set up. Check wikEd.useWikEd if the classic textarea or the wikEd edit frame is in place.
  • wikEd.config.onHook, executed after wikEd has been re-enabled by logo click
  • wikEd.config.offHook, executed after wikEd has been disabled by logo click
  • wikEd.config.textareaHook, executed after classic textarea has been enabled by user
  • wikEd.config.frameHook, executed after wikEd edit frame has been enabled by user
  • wikEd.config.previewHook, executed after the local preview has been added to the page
  • wikEd.config.diffHook, executed after the local changes diff has been added to the page

The usage is as follows: 

 if (typeof(wikEd) == 'undefined') { wikEd = {}; }
 if (typeof(wikEd.config) == 'undefined') { wikEd.config = {}; }
 if (typeof(wikEd.config.setupHook ) == 'undefined') { wikEd.config.setupHook = []; }
 wikEd.config.setupHook.push(YourFunction);

Alternatively, before wikEd initializes, the following custom setting form is also available for convenience: 

 var wikEdConfig = { 'setupHook': [YourFunction] };

To find out if the classic textarea or the wikEd edit frame is in place: 

 if (wikEd.useWikEd == true)  {  } // edit frame in place
 if (wikEd.useWikEd == false) {  } // classic textarea in place

To find out it wikEd is turned off, indicated by a grey top logo wikEd disabled: 

 if (wikEd.turnedOn == true)  {  } // wikEd turned on
 if (wikEd.turnedOn == false) {  } // wikEd turned off

To insert a string at the cursor position : 

 wikEd.FrameExecCommand('inserthtml', string);

Access the plain text of the wikEd edit frame: 

 var obj = {};
 wikEd.ParseDOM(obj, wikEd.frameBody);
 var plainText = obj.plain;
 var curserPosition = obj.plainFocus;

To test a wikEd variable (e.g. wikEd.useWikEd) without throwing an error if wikEd is not loaded: 

 if (typeof wikEd != 'undefined') { if (wikEd.useWikEd == true) {  } }

Please use this discussion page if you have any questions.

[edit]