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 **  object.
 * 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.
 * 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.
 * 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

Notation
JS items beginning with a period are references to the particular application object, like  or other global setting.

*.list
There is one  reponsible for the appearance.
 * The  is an object which assigns to each id an option title within the selection control.
 * 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 object.
 * 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:
 * An array with a  as first element:
 * – compressed, single character tokens in the following strings
 * – 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.
 * −32…−126 – compressed, ASCII code of a separating character between tokens in the following strings
 * figures > 159 are interpreted as UCS, processed like a single string as standard specification (4 byte UCS permitted)
 * – plays a special role: following string is HTML code with fixed text to be inserted; no group separators around. If accompanied not by a string but  applied, group separator is simply omitted between adjacent group definitions, e.g. between different compression modes.
 * In compressed mode, any further string is regarded as a further group itself, decoded as indicated by the leading number.
 * standard: An array of one or more elements, each a single specification.
 * The group separator may be changed by definition of  which is by default composed of spacing and • mark.

specifications
Default: generate from insertion strings. business as ususal Replace current selection, if any. User defined function to be executed instead of string insertion. The entire specification array will be passed as argument. Note that this function is supposed to return  to avoid focus jumps. 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.
 * 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
 * – (not yet implemented)
 * Waiting for implementation of jQuery.textSelection("getSelection")
 * arglist – any further value which has currently no meaning.
 * If both ahead and after are present, the about title (tooltip) is generated with  string between which may be modified by project customization.
 * All strings will be inserted and processed literally. HTML escaping is done internally. For display spaces within menu tokens are made non-breaking.

attribute set
Only known HTML/CSS attributes are considered for the menu:
 * – ltr/rtl
 * – style property
 * – style property
 * – style property
 * – style property

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