User:PerfektesChaos/js/editToolStrIns/Details

This page explains data structures, formats and used terminology.

JavaScript items beginning with a period are references to the particular application object.

Glossary

 * control
 * HTML gadget, usually arranged below the edit textarea.
 * Enables selection of exaxtly one item from a list of options.
 * When touched the list or parts of it will pop up or drop down.
 * Usually it is possible to navigate directly towards a certain item by entering the first character; multiple times necessary if several items beginning with the same letter.


 * list
 * The visible list of available sets, every set appearing as one item.
 * The list is based on the current **  Array.
 * The standard list may be modified by the user: Elements may be removed, added, renamed, overwritten or presented on higher position; even replaced by  definition.
 * See .list for further details.


 * item
 * Every valid item links at least three informations:
 * id
 * title which is visible to the user
 * definition how to build the menu
 * If the user selects an item on control, the appropriate menu is displayed.
 * The evaluation of the particular definition is not performed before requested.


 * id
 * The identifier links the definition with the item on the list.
 * There are four sources of definitions, which might contain a definition with the same identifier:
 * User customization
 * Project (language) standard **
 * User language **
 * Global repository
 * The definition for an identifier is taken from the first match found.


 * definition
 * The definition is used to build a menu when an item has been selected (the first time).
 * The definition is an array. It contains an optional attributes object and at least one group, if a definition shall come into effect.
 * Instead of a definition array the single attributes object might be used to modify an existing definition.
 * See .defs for further details.


 * menu
 * The visible presentation of the token collection.
 * The menu is generated from the definition only if really needed: after the user has chosen that particular item.
 * Once the menu was created it is saved as  with the item, and will be reused if possible during the page visit.


 * token
 * Every single character or more complex sequence which can be clicked on the menu.


 * attributes
 * HTML/CSS properties like font-family, font-size or a class name which enables property inheriting.
 * A definition may be preceeded with attributes.
 * These attributes will be applied to this particular menu.
 * This may be used to adjust exotic character sets which are not readable otherwise.
 * The attributes object may be provided as  and can be omitted.
 * The attributes will be collected in cascading manner from definition in effect up to user, if attribute-only settings are present.
 * See below for further details.


 * group
 * A group is a token collection.
 * Subsequent groups within the menu will be displayed with gaps, perhaps also with separators like “•”.
 * A group is specified as an array within the definition.
 * See below for further details.


 * specification
 * A specification defines appearance and behaviour of a single token.
 * See below for further details.

Naming Convention
Identifiers are supposed to follow these rules: ISO 639 code Hyphen will be converted into underscore in object definition. Abbreviation like IPA ISO 15924 code e.g.
 * Limitation to ASCII is desired. Basically, further definitions shall be limited to  and , starting with letter. Whitespace is not permitted.
 * HTML/CSS attribute names are not permitted.
 * Two or three lowercase letters, might be followed by hyphen:
 * Two or more uppercase letters within:
 * Four letters, capitalized:
 * Mixed case otherwise:
 * Recommended for extensions not fitting into the scheme.
 * Starting with hyphen  or underscore   not permitted.
 * Starting with colon  reserved for namespace dependency.
 * Starting with slash  reserved for project dependency.
 * Starting with square bracket  reserved for message identifiers.
 * Starting with ampersand  reserved for user customization.
 * Predefined strings:
 * (zero as string) – Standard display (appears by default)
 * – Some wiki syntax elements
 * – Some XML style tags
 * – Standard templates in this project
 * or other global setting.

*.list
There is one  responsible for the appearance.
 * The  is an Array which assigns to each id an option title within the selection control.
 * Even index numbers are pointing to the ID.
 * Odd index numbers indicate the title of the preceding ID.
 * The title strings are supposed to be written in the user language.
 * The options will appear on the gadget in the same sequence they are defined in the array.
 * The following sources are searched for a * assignment, and the first match will be used:
 * user customization
 * local project
 * language
 * English as fallback position

*.defs
The definitions are collected in the  object which assigns to each id an array. Note: Values of each definition will be converted into canonical form.
 * The array contains an optional attributes object and at least one group, if a definition shall come into effect.
 * The array may consist of the attributes object only which will be taken into account when evaluating the cascade.
 * A definition with a sole group might dispense with the enclosing array.
 * The available sources are searched for a  assignment of a requested id with group definition, and the first match will be used:
 * user customization
 * local project
 * language
 * global repository
 * English as fallback position

groups
There are several formats for a group:
 * 1) An array with a   as first element:
 * 2) *  – compressed, single character tokens in the following strings; every string is separated by group separator
 * 3) *  – pairs, range of UCS number tuples to be displayed. The next two items are numbers with first and last UCS value, which will be all converted into tokens. For rtl purposes the numbers may appear in reverse order. This may be repeated as often as needed within the same group.
 * 4) *  – sequence of UCS numbers which form a single token. Subsequent tokens are separated by   or   code.
 * 5) * −32…−126 – compressed, ASCII code of a separating character between tokens in the following strings; every string is separated by group separator
 * 6) * figures > 159 are interpreted as UCS, processed like a single string as standard specification (4 byte UCS permitted)
 * 7) *  – plays a special role: following string is HTML code with fixed text to be displayed; no group separators around.
 * 8) standard: An array of one or more elements, each a single specification.
 * 9)   or   – a zero width group separator

specifications
Default: generate from insertion strings. business as ususal Replace current selection, if any. User defined function to be executed instead of immediate string insertion. Regard this as a RegExp string and 3rd parameter  as corresponding replacement text. If non-empty selection currently present, replace selection by executing RegExp. Insert  and   anyway, but these may be empty. On their own risk users might carry further information here.
 * Every specification defines a single insertion token.
 * Basically, each specification is an array.
 * If the specification is of type string or number, this is regarded as an abbreviation of Array(1).
 * The specification array may have any non-zero length.
 * There exists a default action for each missing or empty element. Empty elements are:  or , even   or  , – but   or   are recommended.
 * The elements are (caution: reference zero-based):
 * ahead – string or UCS number to be inserted before cursor position / selection. (4 byte UCS permitted)
 * after – string to be inserted after cursor position / selection, or none.
 * assume – string to be inserted if there is no selection range.
 * about – tooltip (not appreciated in language neutral global definition).
 * alternate – explicit label for token
 * advanced
 * omitted or  or   or   or   or
 * arglist – any further value which has currently no meaning.
 * If both ahead and after are present, the about title (tooltip) is generated with a string between which may be modified by customization.
 * All strings will be inserted and processed literally. HTML escaping is done internally. For display spaces within menu tokens are made non-breaking.

group separator

 * The group separator is a gap or something like a • mark.
 * The group separator is set between group definitions.
 * A zero width group separator may be used to combine adjacent group definitions, e.g. between different compression modes. It can be defined by placing a simple  on group level between two group arrays.
 * The group separator is stored at  which is by default composed of spacing and • mark.

attribute set
Only known HTML/CSS attributes are considered for the menu: For each attribute the highest setting in cascade is used.
 * – ltr/rtl (Default: )
 * – style property
 * – style property
 * – style property
 * – style property

An attribute object assigns properties to keywords.

User defined function
Definition (named or anonymous) of a function which will be executed.
 * The function gets two parameters:
 * Array with the entire specification, defining itself at [5]. This can be utilized to fork, using one function for all specifications.
 * Current selection.
 * The function is supposed to return:
 * if nothing to do
 * for subsequent  which will be executed; possible components:
 * ahead
 * sample text
 * after
 * selection; boolean (Default:  = insert)

See example.

API
For customization the following object components may be written ahead or read:


 * specifies different  object
 * (undefined by default)


 * specifies different  object
 * (undefined by default)


 * suppress execution on load


 * version number
 * (read-only, please)

After loading can be executed


 * Show message box with all available definition identifiers.


 * Set project or user property, see below.


 * Rebuild entire list and model.

Configuration: *.config and .set
A component  may be put into a   or  ** object before the script was started. Multiple  entries will be evaluated in cascading style, giving precedence to the user.

"container"
 * The gadget may be inserted anywhere. Default location (usually below textarea element) may be overridden by explicit specifiation.
 * Configured by an object where each component is addressed by a single id or class selector.
 * DOM elements might be supposed to exist already (component set to ), or will be created if necessary when an object is provided; consisting of two components   with the selector of an existing related DOM element, and   with the name of a common jQuery function like   etc.
 * Example.

"cookieName"
 * storing most recent selection ID, or  if no cookie (default: no cookie)

"ellipsis"
 * tooltip generation; appears between start and end tag

"groupSeparator"
 * non-empty string or ; appears on menu between groups

"groupSeparatorCSS"
 * attribute object with arbitrary CSS assignments, styling the group separator

"hintList"
 * tooltip for gadget selection

"hintMenu"
 * tooltip for all menus

"old"
 * selector for other edittools, or false

"selection"
 * gadget shift; activate this ID

The same settings may be done after the script has been loaded by  function. However, some GUI components are already built and won't change later.

CSS
Six classes are defined: The basic word  may be subject to changes, e.g. prefixed if the script is adopted by WMF. The string is defined in  assignment.
 * 1)   for the entire container
 * 2)   for the selection control
 * 3)   for the menu, which is also affected by particular attributes
 * 4)  id for the menu with a certain selection ID.
 * 5)   for each token
 * 6)   for separators between groups

For those who acquired a taste for button style tokens the following declaration might help:

Examples

 * enwiki simulation
 * User customization