wikimedia / data-values-value-view

Github mirror of "data-values/value-view" - our actual code is hosted with Gerrit (please see https://www.mediawiki.org/wiki/Developer_access for contributing

ValueView

ValueView introduces the jQuery.valueview widget which may be used to display and edit data values (DataValue objects defined in the DataValues library and supported via the DataValues JavaScript package). The jQuery.valueview widget and its resources may be extended to support custom DataValue implementations.

Recent changes can be found in the release notes.

Components

jQuery.valueview

jQuery.valueview may be used to display and edit data values. While the widget's original constructor is located at jQuery.valueview.valueview, the widget should be instantiated via its bridge jQuery.valueview.

jQuery.valueview.Expert

jQuery.valueview.Experts are widgets that deal with editing DataValues. An Expert provides the functionality to edit a specific DataValue (e.g. StringValue) or a DataValue suitable for a certain DataType (e.g. the url DataType which uses the StringValue for representation; see also DataTypes library). jQuery.valueview.Expert is the base constructor for such Experts.

jQuery.valueview.ExpertExtender

jQuery.valueview.ExpertExtender may be used to provide additional information and/or input elements while interacting with the Expert. The ExpertExtender may, for example, be used to provide a preview of how the parsed value will be displayed after saving (see jQuery.ExpertExtender.Preview). Options provided by the ValueParser corresponding to the DataValue being edited may be set using jQuery.valueview.ExpertExtender.* input elements added to the ExpertExtender instance.

jQuery.valueview.ExpertStore

Experts are managed by jQuery.valueview.ExpertStore instance which provides its Experts to jQuery.valueview.

ViewState

ViewState acts as a Facade linking Experts and jQuery.valueview. ViewState allows Experts to observe certain aspects of jQuery.valueview and enables Experts to update the linked jQuery.valueview instance.

Usage

For the usage examples, it is assumed the following packages are installed:

• DataValues
• DataValues JavaScript
• DataTypes

When using jQuery.valueview for handling a DataValue, a jQuery.valueview.ExpertStore with knowledge about an Expert dedicated to the DataValue's type is required and can be set up as follows:

var dv = dataValues,
	vv = jQuery.valueview,
	dt = dataTypes,
	experts = new vv.ExpertStore();

var stringValue = new dv.StringValue( 'foo' );

// Consider this a DataType using the StringValue DataValue internally:
var urlDataType = new dt.DataType( 'url', dv.StringValue.TYPE );

experts.registerDataValueExpert( vv.experts.StringValue, dv.StringValue.TYPE );

console.log(
	experts.getExpert( stringValue.getType() )
		=== experts.getExpert( urlDataType.getDataValueType(), urlDataType.getId() )
);
// true because "url" DataType's DataValue type is "string"; The "string" DataValue's Expert will be
// used as fall-back.

Now, the jQuery.valueview.ExpertStore can be injected into a new jQuery.valueview instance enabling it to edit "string" DataValues.

var $subject = $( '<div/>' ).appendTo( $( 'body' ).empty() );

// In addition to the Expert store, a ValueParser store and two ValueFormatters need to be provided. The parser store
// features the same mechanisms as the Expert store. For this example, we just initialize the parser store with
// the "string" parser as default. The formatters will format a string as it is.
var parsers = new valueParsers.ValueParserStore( valueParsers.StringParser );

$subject.valueview( {
  expertStore: experts,
  parserStore: parsers,
  plaintextFormatter: new valueFormatters.StringFormatter(),
  htmlFormatter: new valueFormatters.StringFormatter(),
  language: 'en', // language code transmitted to Parser
  value: new dv.StringValue( 'text' )
} );

var valueView = $subject.data( 'valueview' );

Having created a jQuery.valueview displaying text, the widget's member functions may be used for interaction, for example:

• Emptying the view: valueView.value( null );
• Allowing the user to edit the value: valueView.startEditing();
• Stopping the user from editing the value: valueView.stopEditing();
• Returning the current value: valueView.value();

Setting a jQuery.valueview instance's value to a DataValue it cannot handle because no suitable Expert can be determined from the ExpertStore will result in an error notification being displayed. Calling .value() will still return the value but the user can neither see nor edit the value.

Architecture

jQuery.valueview heavily depends on ValueFormatters and ValueParsers defined via the DataValues JavaScript library. ValueFormatters are used to convert DataValue instances to DOM elements, and ValueParsers are used to convert plain strings (which may be accompanied by some options) to DataValue instances. Since Experts only are used for editing values, they are constructed when starting edit mode and destroyed after leaving edit mode. Experts have the following lifecycle:

• _init(): Load parsed, formatted and raw (text) values from the jQuery.valueview instance linked via ViewState and initialize DOM.
• Edit loop
  • (User edits)
  • Expert calls viewNotifier.notify( 'change' ) and triggers parsing and formatting.
  • rawValue(): Return the current raw (text) value.
  • (optional) preview.showSpinner(): Replace preview with a loading spinner.
  • draw(): (Re-)draw non-editable parts of the Expert using the (new) parsed and formatted value from the jQuery.valueview instance (via ViewState)
• destroy(): Destroy DOM.

Other methods an Expert needs to provide:

• valueCharacteristics()
• focus()
• blur()

Bugs on Phabricator

https://phabricator.wikimedia.org/project/view/918/