Extension:JsonConfig

The JsonConfig extension allows other extensions to store their configuration data as a JSON blob in a wiki page.

Available Features and Usage Patterns
You may use JsonConfig to store data in a number of ways:
 * A single page configuration, e.g. a number of settings for your extension -- Config:MyExtSettings (Config is the default namespace associated with the JsonConfig extension)
 * A set of pages with similar structure residing in its own namespace, e.g. IP addresses of the known proxies or event log schemas, e.g. Proxy:Opera, Schema:AccountCreation
 * To avoid polluting wiki with additional namespaces, you can use "sub-namespaces", e.g. Config:Proxy:Opera
 * You may provide a content class to do data validation and normalization
 * You may provide a view class to customize HTML generation
 * Data can be stored as "one-per-wiki", "one-per-cluster", or even one per some "family" (different structure of the caching key for shared memcached).
 * Data can be stored in a public or private wiki and accessed with credentials
 * Data can be stored in a separate cluster, and do remote notification when changed

Hello World
Simplest case - a single configuration page without any validation, stored locally on each wiki. We don't even need to have any real code - just add these settings to LocalSettings.php

Adding above settings enables namespace "Config" on the local wiki, but will only allow "Config:MySettings" page to be created, not any other page in that namespace. Any well-formed JSON data will be accepted. To get it in PHP, use TitleValue object:

Multiple configs shared in a cluster
Lets say we decide to store the trusted proxies' IPs as Config:Proxy: pages on the Meta wiki and share it with the cluster.

If instead you want to dedicate a separate namespace to proxies, the parameters would change to:

Validation
Most of the time we would also want a custom content class with its own validation. JSON pages are handled by the content classes which derive from JCContent. They are responsible for parsing and validating raw text. JCContent does not do any validation except for JSON parsing, but you may choose to derive from it and override JCContent::validate. Better yet, you may derive from the JCObjContent class which provides a number of validation primitives, and only handle JCObjContent::validateContent.

For the sake of this documentation, lets presume that the proxy config page describing Opera Mini servers has this format: Here is the content class to validate that data.

Customizing Storage Wiki
You may also want to customize viewing and page creation on the storage (e.g. META) wiki. There are two ways to do it - inside your JCContent-derived class, or via a separate "view" class that derives from JCContentView. The second approach is preferable as it keeps things cleanly separated architecturally and allows view class to only exist in the wiki that handles storing (e.g. META), not on all the ones that use it.

To override default value in JCContent</tt>-derived class, override the constructor and set the $text value to the new default if it came in as NULL before passing it to the parent constructor. To override the HTML generation, override JCContent::getHtml</tt>.

With the recommended way, create a view class that derives from JCContentView</tt> or a more feature-rich JCDefaultContentView</tt>. For JCContentView</tt>, you will need to implement valueToHtml</tt> and getDefault</tt>. By default, the view is implemented by the JCDefaultContentView</tt> class, which can also be used as a customizable base if you just need minor adjustments to the way it looks.

Best Practices
Extension should add configurations to the $wgJsonConfigs and $wgJsonConfigModels in the main extension file. In case the config data is shared among multiple wikis, the key used in $wgJsonConfigs['key'] should be documented, and the 'store' / 'remote' section should be initialized in LocalSettings.php (of course your extension could introduce a number of global variables that duplicate that functionality, but why?

$wgJsonConfigs
This variable defines profiles for each type of configuration pages. $wgJsonConfigs is an associative array of arrays, with each sub-array having zero or more of the following parameters. By default, the string key is treated as the model ID that this profile represents, but in case you need more than one profile for the same model Id, you can override it with the 'model' parameter.

$wgJsonConfigModels
This variable defines which custom content class will handle which Model ID. More than one Model ID may be handled by the same content class. All content classes must derive from \JsonConfig\JCContent class. If the modelID is mapped to null</tt>, the default JCContent class will be used.

Example:

In case when a separate class should do HTML rendering, the value could be specified as an array:

Implemented Features

 * JSON parsing converts JSON text into either an array or an object
 * Visualization shows JSON as an easy to view table rather than code, with some extra highlighting. For example if the value is not provided and a default is used, it is shown in gray, or when the value is the same as default, it shows as purple. For example, see this and this.
 * Code Editor simplifies JSON editing
 * Custom Validation performs complex checks such as checking that the value is in the proper format or that a user ID exists.
 * MemCached caching stores json blobs in memcached under custom keys and expiration policies, and resets them on save.
 * Flagged Revisions support allows configurations to be marked as "reviewed" before going into production
 * Localization of most basic interface elements has been done in many languages, and it would reduce translation work if most common messages would be done just once in one place.

Unimplemented Nice-To-Haves
These features would be desirable to more than one type of configs:
 * Schema validator - Validate against JSON Schema, as most extensions might not need complex validation rules, or might want to combine schema plus extra validation.
 * Custom editor - Zero team has been thinking about implementing a more complex editor, possibly based on JSON Schema.
 * API query support - Allow config pages to be returned as regular API results in all formats - json/xml/... instead of text blobs:
 * api.php ? action=query & titles=Config:Proxy:Opera & prop=jsonconfig</tt>
 * Localization - it would be good to be able to show localized descriptions for each configuration key

External Access
The stored configuration data may frequently be needed by some external agent such as JavaScript, bot, or other programs. JavaScript could use either JSONP to access needed data by calling standard action=query&rvprop=content</tt> API, or we could develop a forwarding service if CORS is unavailable. Extension authors may choose to add their own API modules to provide domain-specific information. Lastly, the rvprop=jcddata</tt> Query API parameter would return JSON data as part of the API result, not as a text blob that rvprop=content</tt> would return.