User:Cacycle/wikEd development

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
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. After pushing the Save page button the content is copied back to the hidden textarea and then submitted.

Program structure
(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

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

Greasemonkey-compatibility

 * Global variables must be declared as follows:


 * Global subroutines must be declared as follows:
 * Event listeners must be registered as follows, DOM element declarations (onclick="") do not work:
 * If possible, please use the wikEd wrapper:
 * Custom attributes of DOM elements:
 * 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.
 * If possible, please use the wikEd wrapper:
 * Custom attributes of DOM elements:
 * 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.
 * 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.
 * 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.
 * 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
For performance reasons it is highly recommended to test the scripts on a local copy of a Wikipedia edit page. (Outdated)


 * Copy the whole wikEd program code from the page wikEd.js to D:\wikEd\wiked.js
 * Copy the whole diff program code from the page diff.js to D:\wikEd\diff.js
 * Copy the whole InstaView code from the page instaview.js to D:\wikEd\instaview.js
 * Do the same for: http://en.wikipedia.org/w/skins-1.5/common/wikibits.js (wikibits.js), http://en.wikipedia.org/w/index.php?title=-&action=raw&smaxage=0&gen=js&useskin=monobook (site.js), http://en.wikipedia.org/w/index.php?title=MediaWiki:Monobook.css&action=raw&ctype=text/css (monobook.css), http://en.wikipedia.org/w/index.php?title=MediaWiki:Common.css&action=raw&ctype=text/css (common.css), http://en.wikipedia.org/w/skins-1.5/common/ajax.js (ajax.js), http://en.wikipedia.org/w/skins-1.5/common/ajaxwatch.js (ajaxwatch.css), http://en.wikipedia.org/w/index.php?title=-&action=raw&gen=css (site.css), http://en.wikipedia.org/w/skins-1.5/common/shared.css (shared.css), http://en.wikipedia.org/skins-1.5/common/main.css (main.css)
 * Save a Wikipedia edit page of your choice to D:\wikEd\test.html
 * Open the page in your text editor and change all addresses of scripts, css files, and images their respective local copies. All other relative links starting with "/ have to be preceded with "http://en.wikipedia.org".
 * Download the user interface images here, rename the extension to ".zip", and extract them
 * Set the following configuration variables in the header JavaScript of the edit page:

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
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  and the workaround   breaks the undo history!

wikEd API

 * 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:

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

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

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

To insert a string at the cursor position :

Access the plain text of the wikEd edit frame:

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

Please use this discussion page if you have any questions.