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 .l10n.**.list 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 .user.list 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:

1. User customization
2. Project (language) standard .l10n.**.defs
3. User language .l10n.**.defs
4. Global repository .defs.global

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 $menu 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 null 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:

• Limitation to ASCII is desired. Basically, further definitions shall be limited to A-Z a-z 0-9 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:
  ISO 639 code
  Hyphen will be converted into underscore in object definition.
• Two or more uppercase letters within:
  Abbreviation like IPA
• Four letters, capitalized:
  ISO 15924 code
• Mixed case otherwise:
  e.g. Latin
  • 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:
  • 0 (zero as string) – Standard display (appears by default)
  • [[]] – Some wiki syntax elements
  • <> – Some XML style tags
  • {{}} – Standard templates in this project
  • ---- (four hyphens) – Separator within menu options (no insertion)

Notation

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

Technical details

*.list

There is one list responsible for the appearance.

• The list 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 *.list assignment, and the first match will be used:
  1. user customization
  2. local project
  3. language
  4. English as fallback position

*.defs

The definitions are collected in the defs object which assigns to each id an array.

• 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 defs assignment of a requested id with group definition, and the first match will be used:
  1. user customization
  2. local project
  3. language
  4. global repository
  5. English as fallback position

Note: Values of each definition will be converted into canonical form.

groups

There are several formats for a group:

1. An array with a number as first element:
   • 1 – compressed, single character tokens in the following strings; every string is separated by group separator
   • 2 – 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.
   • 3 – sequence of UCS numbers which form a single token. Subsequent tokens are separated by false or 0 code.
   • −32…−126 – compressed, ASCII code of a separating character between tokens in the following strings; every string is separated by group separator
   • figures > 159 are interpreted as UCS, processed like a single string as standard specification (4 byte UCS permitted)
   • 0 – plays a special role: following string is HTML code with fixed text to be displayed; no group separators around.
2. standard: An array of one or more elements, each a single specification.
3. false or 0 – a zero width group separator

specifications

• 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 false, even null or undefined, – but "" or false are recommended.
• The elements are (caution: reference zero-based):
  1. ahead – string or UCS number to be inserted before cursor position / selection. (4 byte UCS permitted)
  2. after – string to be inserted after cursor position / selection, or none.
  3. assume – string to be inserted if there is no selection range.
  4. about – tooltip (not appreciated in language neutral global definition).
  5. alternate – explicit label for token
     Default: generate from insertion strings.
  6. advanced
     • omitted or undefined or false or "" or 0 or null
       business as ususal
     • true
       Replace current selection, if any.
     • function
       User defined function to be executed instead of immediate string insertion.
     • string
       Regard this as a RegExp string and 3^rd parameter assume as corresponding replacement text. If non-empty selection currently present, replace selection by executing RegExp. Insert ahead and after anyway, but these may be empty.
  7. arglist – any further value which has currently no meaning.
     On their own risk users might carry further information here.
• 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 false on group level between two group arrays.
• The group separator is stored at .menu.separator which is by default composed of spacing and • mark.

attribute set

Only known HTML/CSS attributes are considered for the menu:

• class
• lang
• dir – ltr/rtl (Default: ltr)
• font-family – style property
• font-size – style property

For each attribute the highest setting in cascade is used.

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:
  1. Array with the entire specification, defining itself at [5]. This can be utilized to fork, using one function for all specifications.
  2. Current selection.
• The function is supposed to return:
  • false if nothing to do
  • object for subsequent encapsulateSelection which will be executed; possible components:
    • pre ahead
    • peri sample text
    • post after
    • replace selection; boolean (Default: false = insert)

See example.

API

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

.lang

specifies different .l10n. object

(undefined by default)

.project

specifies different .l10n. object

(undefined by default)

.off

suppress execution on load

.vsn

version number

(read-only, please)

After loading can be executed

.about_defs()

Show message box with all available definition identifiers.

.set(key, val)

Set project or user property, see below.

.update()

Rebuild entire list and model.

Configuration: *.config and .set()

A component .config may be put into a .user or .l10n.** object before the script was started. Multiple .config 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 true), or will be created if necessary when an object is provided; consisting of two components start with the selector of an existing related DOM element, and fiat with the name of a common jQuery function like before etc.

Example.

"cookieName"

storing most recent selection ID, or false if no cookie (default: no cookie)

"ellipsis"

tooltip generation; appears between start and end tag

"groupSeparator"

non-empty string or false; 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 .set() function. However, some GUI components are already built and won't change later.

CSS

Six classes are defined:

1. editToolStrIns for the entire container
2. editToolStrIns-gadget for the selection control
3. editToolStrIns-menu for the menu, which is also affected by particular attributes
4. editToolStrIns-menu-id for the menu with a certain selection ID.
5. editToolStrIns-token for each token
6. editToolStrIns-sep for separators between groups

The basic word editToolStrIns may be subject to changes, e.g. prefixed if the script is adopted by WMF. The string is defined in .gui.self assignment.

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

   .editToolStrIns-token {
      background:      #D0D0D0;
      color:           #000000;
      font-size:       100%;
      font-weight:     normal;
      text-decoration: none;
      padding:         2px;
      border-style:    solid;
      border-width:    2px;
      border-color:    #E0E0E0 #E0E0E0 #707070 #707070;
   }

Examples

• enwiki simulation
• User customization