User:PerfektesChaos/js/editToolStrIns/Project Customization

This page describes how sysops might configure the entire local project.

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

Localization

Projects might create their own .l10n. object, or reuse another localization, accessed by similar language code.

Instead of the standard project identity the configuration variables .lang and .project may be used to access another .l10n. explicitly.

If not defined by setting, the algorithm tries to guess appropriate localization objects, falling back to English if failure.

Create a particular localization

If you are not happy with the existing localization objects, a sysop might provide a new one.

Please share with other WMF projects, if successful and meaningful for reusing.

• Create a .l10n. object, named by a particular identifier as described below under naming convention.
• Provide one until four elements as described below.

Note: Create objects with string identifiers; some browsers would not find them otherwise.

Naming Convention

Consider rules when assigning an identifier.

• Lowercase ASCII only to identify project and language.
• Language: Use ISO 639 code
  If subclassed by hyphen, use underscore _ instead, like en_us.
• Project: wgDBname project identifier
  e.g. plwikisource
• Project type
  e.g. wikinews.
• subclass distinct versions by underscore
  e.g. ar_1

If you made your choice for example, the object is created as

   .l10n["example"] = { };

Elements

One to four elements may be declared:

   .l10n.example["list"] = { "0": "Standard" };

• This needs to be an object describing which titles appear as items in the control, in which order, and which definitions are linked to the items.
• Details explains more about the list element.

In most cases it is meaningful to declare some specific definitions, e.g. compose the standard menu:

   .l10n.example["defs"] = { "0": ... };

See Details.

Language oriented objects should provide

   .l10n.example["config"] = { "hintList": "Select a language", 
                               "hintMenu": "Select a character or string to be inserted" };

Additional configuration items may be set.

   .l10n.example.config["cookieName"] = "editToolStrIns";

Standard items

Some items are supposed to be accessed by standard identifiers:

• 0 (zero as string) – Standard display (appears by default)
• [[]] – Some wiki syntax elements
• {{}} – Standard templates
• ---- – Separator between options in gadget

Their content will be project and language specific and should be adapted.

Namespace dependency

• :6 – specific to file description pages which may need insertion of information and license templates.

Code location

Usually JS code for the entire project is written into the project Mediawiki: namespace. The global script will be imported by mw.loader.load(); before or after load call the application object may be created and populated.

Another way is to resign updates and insert a copy of the global script. This gives the opportunity to cut off some definitions and make the code a bit smaller, but is not recommended.

Project environment is supposed to limit loading on wgAction values of edit or submit.

Customization variables

Two variables may be defined in order to override the project DB and language:

• .project will be used instead of wgDBname
• .lang will be used instead of wgContentLanguage

Further standard project settings are available through configuration:

• "cookieName" enables memorising a charset selection from previous page edits, see below.
• "groupSeparator" permits redefinition of separator between groups
  • "groupSeparatorCSS" is an object defining style properties of this separator.
• "hintList" redefines tooltip for gadget selection
• "hintMenu" redefines tooltip for all menus
• "ellipsis" permits redefinition of ellipsis between enclosing strings when generating tooltips

Resolving algorithm

The standard token definitions are taken always from an appropriate project type and project language. Therefore the inserted strings will be compliant with the project environment.

The GUI elements (hints, choice) are taken with respect to the user language, where possible. This shall provide a familiar appearance, and readability if the user even cannot read the script of a project visited as a guest.

Cookie

If .cookie is set to a non-empty string a session cookie (currently: sessionStorage) will be created which shows the most recent selection of a subset on previous pages.

• In 2010/2011 the English Wikipedia uses a edittoolscharsubset cookie for this purpose.

By default no cookies are used. If requested, set to name string:

   .l10n.example["config"] = { "cookieName": "editToolStrIns" };

Prerequisites

Editable

It is assumed that code loading is executed if and only if the page could be edited:

• wgAction is supposed to be either "edit" or "submit".
• wgRestrictionEdit does permit editing.

For performance reasons the script won’t check this. mw.toolbar.insertTags() will fail at last if there is no enabled input field.

Error checking

For performance reasons there is no error check done with external definitions. Please check yourself carefully whether your declarations appear as expected.

CSS

Decorative styles are to be assigned on project definition level. The global script does not apply particular style information. See Details.

Removing unnecessary stuff

• For the sake of smaller code a sysop may remove .l10n. projects from a local copy of the script which cannot be assigned ever.
• Language oriented definitions could be maintained; they help users with particular language skills. English is the fallback position and should not be discarded.
• Character sets should be supported even if not referenced by the current project standard offer. Users working on exotic issues might want to access them by personal configuration.

Examples

• enwiki simulation