Extension:ValueView

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
ValueView

Release status: experimental

Description Provides UI components for displaying and editing data values
Author(s) Daniel Werner (Danwetalk)
Latest version 0.1.1
MediaWiki not required
PHP 5.3+
Database changes No
License GPL v2+
Download
README

Translate the ValueView extension if possible

Check usage and version matrix; code metrics

This library and its documentation can be found on GitHub.


ValueView introduces the jQuery.ui.widget based front-end component jquery.valueview which allows to display and edit data values defined by the DataValues extension.

Components[edit | edit source]

When loading the jquery.valueview resource loader definition, the following components introduced by this extension will be available:

  • jquery.valueview: Widget for displaying and editing data values.
  • mediaWiki.ext.valueView: Object representing the "ValueView" MediaWiki extension. When loaded, this will hook jQuery.valueview up to some of its basic formatters by overwriting jQuery.valueview.valueview.prototype.options.expertProvider

jquery.valueview[edit | edit source]

jquery.valueview introduces a jQuery widget for displaying and editing data values, open for extension to support custom data value implementations. It consists out of the following parts:

jQuery.valueview.valueview 
Widget definition for displaying and editing data values. Each data value which should be supported by the valueview widget has to be implemented as a jQuery.valueview.Expert.
jQuery.fn.valueview 
jQuery widget bridge to instantiate a jQuery.valueview widget in the DOM.
jQuery.valueview.Expert 
Base for strategies defining how to handle (edit/display) data values of a specific data value type or data values suitable for a certain data type.
jQuery.valueview.ExpertFactory 
Factory for creating jQuery.valueview.Expert instances.
jQuery.valueview.ViewState 
Link between experts and valueview widget in form of a facade that allows experts to observe certain aspects of a valueview.
jQuery.valueview.experts 
Expert definitions for some basic data value types.

Usage[edit | edit source]

When using the jQuery valueview widget for handling a data value of some sort, an ExpertFactory with knowledge about an Expert dedicated to the used data value type is required and can be set up as follows:

var dv = dataValues;
var vv = jQuery.valueview;
var experts = new vv.ExpertFactory();
 
// Consider this a data value using the "string" data value type internally.
var urlDataType = dataTypes.getDataType( 'url' );
 
 
experts.registerExpert( dv.StringValue, vv.experts.StringValue );
 
console.log(
  experts.getExpert( new dv.StringValue( 'foo' ) ) === experts.getExpert( urlDataType ) );
  // true because "url" data type's data value type is "string".
  // The string expert will be used as fallback.
 
 
experts.registerExpert( urlDataType, vv.experts.UrlType );
 
console.log(
  experts.getExpert( new dv.StringValue( 'foo' ) ) === experts.getExpert( urlDataType ) );
  // false because we now have a dedicated expert registered for the "url" data type.

The ExpertFactory experts can now be injected into a new jQuery.valueview which will then be able to present string data values.

var $subject = $( '<div/>' ).appendTo( $( 'body' ).empty() );
$subject.valueview( {
  expertProvider: experts,
  value: new dv.StringValue( 'text' )
} );
var valueView = $subject.data( 'valueview' );

Creates a jQuery.valueview displaying text. valueView.<memberFn> or alternatively $subject.valueview( '<memberFn>' ) will now allow to invoke member functions. For example:

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

Setting the view to a data value it can not handle because of lack of a suitable expert will result into a proper notification being displayed. Calling .value() will still return the value but the user can neither see nor edit the value.

Adding support for custom data value types[edit | edit source]

Supporting a new data value type will require implementation of a suitable jQuery.valueview.Expert as well as its registration to the jQuery.valueview.ExpertFactory instance used in the actual valueview widget.


Dependencies[edit | edit source]

See ValueView.resources.mw.php for dependencies of this library. These dependencies are shipped as part of the MediaWiki extension while the core jQuery.valueview component can be found under resources/jQuery.valueview.

Requirements[edit | edit source]


Installation[edit | edit source]

Once you have downloaded the code, place the DataValues directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file:

# DataValues
require_once( "$IP/extensions/DataValues/ValueView/ValueView.php.php" );

See also[edit | edit source]