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 classic browsers iframe is not supposed to receive focus. An exception is tried in mediawiki.action.edit.js 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 heading and trailing whitespace. The current implementation is using WikEd API functions.

Multiple tool areas
The tool is expecting the class  where gadget and menu are established. It was assumed that this class has one member only, but currently trying to support any number of tool areas with independent instances.

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.

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
 * Internal access only.
 * defines which and whether HTML or CSS
 * defines which and whether HTML or CSS


 * 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
 * Internal access only.
 * Internal access only.


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


 * Particular menu with tokens and separators
 * Internal access only.
 * Internal access only.


 * User definitions
 * User definitions


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

DOM

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