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
edit- 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:
- User customization
- Project (language) standard
.l10n.
**.defs
- User language
.l10n.
**.defs
- 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.
- 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
editIdentifiers 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
editJS items beginning with a period are references to the particular application object, like mw.libs.editToolStrIns
or other global setting.
Technical details
edit*.list
editThere 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:- user customization
- local project
- language
- English as fallback position
*.defs
editThe 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:- user customization
- local project
- language
- global repository
- English as fallback position
Note: Values of each definition will be converted into canonical form.
groups
editThere are several formats for a group:
- An array with a
number
as first element:1
– compressed, single character tokens in the following strings; every string is separated by group separator2
– 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 byfalse
or0
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.
- standard: An array of one or more elements, each a single specification.
false
or0
– a zero width group separator
specifications
edit- 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:
""
orfalse
, evennull
orundefined
, – but""
orfalse
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
Default: generate from insertion strings. - advanced
- omitted or
undefined
orfalse
or""
or0
ornull
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 3rd parameterassume
as corresponding replacement text. If non-empty selection currently present, replace selection by executing RegExp. Insertahead
andafter
anyway, but these may be empty.
- omitted or
- 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
edit- 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
editOnly known HTML/CSS attributes are considered for the menu:
class
lang
dir
– ltr/rtl (Default:ltr
)font-family
– style propertyfont-size
– style property
For each attribute the highest setting in cascade is used.
An attribute object assigns properties to keywords.
User defined function
editDefinition (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:
false
if nothing to doobject
for subsequentencapsulateSelection
which will be executed; possible components:pre
aheadperi
sample textpost
afterreplace
selection; boolean (Default:false
= insert)
See example.
API
editFor 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()
editA 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 componentsstart
with the selector of an existing related DOM element, andfiat
with the name of a common jQuery function likebefore
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
editSix classes are defined:
editToolStrIns
for the entire containereditToolStrIns-gadget
for the selection controleditToolStrIns-menu
for the menu, which is also affected by particular attributeseditToolStrIns-menu-
id for the menu with a certain selection ID.editToolStrIns-token
for each tokeneditToolStrIns-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
edit- enwiki simulation
- User customization