User:PerfektesChaos/js/editToolStrIns/Coding

Notes for developers.

noscript
By nature the script does not provide a non-JS approach. For users who have no access to JS or did not enable JS in their browser en:MediaWiki:Edittools supports a fallback solution.

JS variables

 * JS variables on global level abandoned.
 * is used to plug in an application object.

Postponed
For short response time GUI elements (menu) are built only when really visible. If created once, the particular menu is stored and will be reused.

enableForAllFields

 * en:MediaWiki:Edittools.js as of 2009 reads:
 * insertTags from the site-wide /skins-1.5/common/edit.js just inserts in the first textarea in the document. Evidently, that's not good if we have multiple textareas.
 * This has been overcome by MW 1.18 in mediawiki.action.edit.js – mw.toolbar.insertTags provides a currentFocused referencing to either #wpSummary or #wpTextbox1 at first.
 * Extended to any textarea or text input field: 31566, 31682 → 103074.

iframe
With HTML 4 and classic browsers iframe is not supposed to receive focus. An exception is made for  as known iframe.
 * With HTML < 5 iframe is not supposed to receive focus, nor does its body. However, frame document (Gecko) or window (IE) may receive click events etc.

WikEd

 * The first MW 1.18 implementation does not to recognize currentFocused by .focus binding to wpTextbox1 while WikEd works on iframe.
 * jquery.textSelection provides a  for   only. This might be extended.
 * Since WikEd edit area does not contain a plain text but a DOM structure a selection needs some analysis to detect trailing whitespace, which shall be neglected when closing tags are inserted. Offsets and containers need to be traversed through the range, since browsers will include following spaces on selection click, which is reasonable for moving words in text.

Multiple tool areas
The tool is expecting the class  where gadget and menu are established. It is assumed that this class has one member only.

Images
Glyphs not available in Unicode might be provided as miniatur images one day.

debug
For developing purposes a  subclass is introduced. It will log messages only when explicitly requested. Such code shall be removed from productive releases.

old
Known other edittools are removed from display.

spaces
Adjacent spaces in selection are changed with the inserted tags now, as WikEd already did. This is a challenge for mw.toolbar.insertTags as of MW 1.18, which calls textSelection in jquery.textSelection module. In checkSelectedText the post and pre fields are computed and will be swapped. See also 27116.

Deployment style

 * The first development is divided into independent function definitions, since they are easier to debug and exchange. Private functions and variables are also hidden from the debugger.
 * A conversion procedure is already written which turns automatically the prototype coding into deployment as follows:
 * All procedures and definitions will be combined into one single object definition expression.
 * The current  clauses will be removed. Since the terminating brackets are marked by specific comments, lines between will be left-indented.
 * Any function whose name starts with an “f” is predestined as private. Three remaining functions are designed for public access (API).
 * String literals over line breaks will be concatenated.
 * Indentation style will be changed from 3spc into tab.
 * Coming from C++, I do not appreciate 2300 lines between opening and closing bracket. However, I will dress the code according to Manual:Coding conventions.

Personal style

 * Coding conventions were already taken into account where suitable.
 * Some personal preferences are preserved during first development.
 * Line length quite short.
 * Native indentation is 3spc which can be easily converted into tabs.
 * Human readability preferred against putting everything into one single line. The author produces several 1000 lines of code per month in many fields and languages and he is not able to read his own code after two weeks otherwise.
 * Any single function and additive property gets a separate timestamp and function documentation. Control structure end clauses are commented.

Version numbers

 * Version IDs are of type.
 * Numbers < 0 indicate first development.
 * If ever adopted as official release, this will be  and further.
 * With vsn=1 adjacent experimental numbers are based on the negative value of the basic release.

behind the mirror

 * 32241

interface page

 * mw.messages.get might be used to configure and distribute pieces of code for localization in the future.
 * This development started before Extension:Gadgets was announced to the public.

subdivision

 * HTML and CSS attributes
 * defines which and whether HTML or CSS
 * Internal access only.
 * Internal access only.


 * Development support, shall be removed from deployed copies
 * Development support, shall be removed from deployed copies


 * Definitions of menus, tokens and attributes
 * To be interpreted from configuation sources.
 * Internal access only.
 * Internal access only.


 * Overall GUI issues, selection device, container
 * API:
 * API:
 * API:
 * API:
 * API:
 * API:


 * Localization definitions, mainly by local project
 * fallback
 * fallback


 * Particular menu with tokens and separators
 * API:
 * API:


 * User definitions
 * User definitions


 * top
 * Top level functionality
 * API:
 * (undefined by default)
 * (undefined by default)
 * (undefined by default)

DOM

 * .gui.$container
 * .gui.$wrapper
 * .gui.$gadget
 * (separator)
 * .gui.$menu
 * particular menu
 * tokens
 * .menu.$sep