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 (window) level abandoned.
• mw.libs 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: bugzilla:31566, bugzilla:31682 → rev:103074.

iframe

With classic browsers iframe is not supposed to receive focus. An exception is tried in mediawiki.action.edit.js for ".wikiEditor-ui-text iframe" 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 hasIframe for wikiEditor-context 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 mw-editTools 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 .debugging 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 bugzilla: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 with 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 number.
• Numbers < 0 indicate first development.
• If ever adopted as official release, this will be vsn=1 and further.
• With vsn=1 adjacent experimental numbers are based on the negative value of the basic release.

behind the mirror

• bugzilla: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.

application object

subdivision

.attr

HTML and CSS attributes

Internal access only.

.attr.names defines which and whether HTML or CSS

.debugging

Development support, shall be removed from deployed copies

.defs

Definitions of menus, tokens and attributes

To be interpreted from configuation sources.

Internal access only.

.gui

Overall GUI issues, selection device, container

Internal access only.

• .gui.$container
• .gui.$gadget
• .gui.$menu
• .gui.$wrapper
• .gui.old

.l10n

Localization definitions, mainly by local project

• .l10n.en fallback

.menu

Particular menu with tokens and separators

Internal access only.

• .menu.divide
• .menu.separator
• .menu.stick

.user

User definitions

top

Top level functionality

API:

• .lang (undefined by default)
• .project (undefined by default)
• .off
• .vsn (read-only)
• .about_defs()
• .set()
• .update()

DOM

• .gui.$container   .mw-editTools
  • .gui.$wrapper   div.editToolStrIns
    • .gui.$gadget   div.editToolStrIns-gadget
    • (separator)
    • .gui.$menu   div.editToolStrIns-menu
      • particular menu   div.editToolStrIns-menu-particular
        • tokens   span.editToolStrIns-token
        • .menu.$sep   span.editToolStrIns-sep