Daniel Werner has uploaded a new change for review.
https://gerrit.wikimedia.org/r/92422
Change subject: Some documentation updates
......................................................................
Some documentation updates
Change-Id: I67a3ea0114aed6673009dfcd0c5c3c89cf68da56
---
M ValueView/README
A ValueView/resources/jquery.valueview/README
M ValueView/resources/jquery.valueview/valueview.BifidExpert.js
M ValueView/resources/jquery.valueview/valueview.Expert.js
M ValueView/resources/jquery.valueview/valueview.ExpertFactory.js
M ValueView/resources/jquery.valueview/valueview.experts/experts.js
6 files changed, 131 insertions(+), 56 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/DataValues
refs/changes/22/92422/1
diff --git a/ValueView/README b/ValueView/README
index e26b9bd..1268320 100644
--- a/ValueView/README
+++ b/ValueView/README
@@ -1,15 +1,23 @@
-# ValueView
+= MediaWiki Extension:ValueView =
-"ValueView" introduces the jQuery.ui.widget based frontend component
jQuery.valueview which allows
-to display and edit data values defined by the "DataValues" extension. When
added as a dependency in
-a resource loader definition, the following components introduced by this
extension will be available:
+''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.
-* jQuery.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.
-* mediaWiki.ext.valueView: Object representing the "ValueView" MediaWiki
extension.
-* Support of valueview for some basic data value types. These valueview
experts can be found in
- jQuery.valueview.experts.<constructor-name>.
-* other jQuery extensions required by this library which are not available in
MediaWiki itself:
- - jQuery.eachchange
- - jQuery.inputAutoExpand
\ No newline at end of file
+
+== Components ==
+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
<code>jQuery.valueview.valueview.prototype.options.expertProvider</code>
+
+
+== jquery.valueview ==
+@see resources/jquery.valueview/README
+
+
+=== Dependencies ===
+See <code>ValueView.resources.mw.php</code> 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
<code>resources/jQuery.valueview</code>.
+
+
+== Requirements ==
+* [[Extension:DataValues|DataValues]] extension must be installed
+* [[Extension:DataTypes|DataTypes]] extension must be installed
diff --git a/ValueView/resources/jquery.valueview/README
b/ValueView/resources/jquery.valueview/README
new file mode 100644
index 0000000..bbd9e2f
--- /dev/null
+++ b/ValueView/resources/jquery.valueview/README
@@ -0,0 +1,63 @@
+= jquery.valueview =
+
+''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 <code>jQuery.valueview.Expert</code>.
+; jQuery.fn.valueview : jQuery widget bridge to instantiate a
<code>jQuery.valueview</code> 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 ==
+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:
+
+<syntaxhighlight lang="javascript">
+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 );
+
+// true because "url" data type's data value type is "string".
+// The string expert will be used as fallback.
+console.log(
+ experts.getExpert( new dv.StringValue( 'foo' ) ) === experts.getExpert(
urlDataType ) );
+
+
+experts.registerExpert( urlDataType, vv.experts.UrlType );
+
+// false because we now have a dedicated expert registered for the "url" data
type.
+console.log(
+ experts.getExpert( new dv.StringValue( 'foo' ) ) === experts.getExpert(
urlDataType ) );
+</syntaxhighlight>
+
+The ExpertFactory <code>experts</code> can now be injected into a new
jQuery.valueview which will then be able to present string data values.
+
+<syntaxhighlight lang="javascript">
+var $subject = $( '<div/>' ).appendTo( $( 'body' ).empty() );
+$subject.valueview( {
+ expertProvider: experts,
+ value: new dv.StringValue( 'text' )
+} );
+var valueView = $subject.data( 'valueview' );
+</syntaxhighlight>
+
+Creates a jQuery.valueview displaying ''text''.
<code>valueView.<memberFn></code> or alternatively <code>$subject.valueview(
'<memberFn>' )</code> will now allow to invoke member functions. For example:
+
+* ''Emptying the view:'' <code>valueView.value( null );</code>
+* ''Allowing the user to edit the value:''
<code>valueView.startEditing();</code>
+* ''Stopping the user from editing the value any further:''
<code>valueView.stopEditing();</code>
+* ''Returning the current value:'' <code>valueView.value();</code>
+
+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
<code>.value()</code> will still return the value but the user can neither see
nor edit the value.
+
+
+== Adding support for custom data value types ==
+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.
diff --git a/ValueView/resources/jquery.valueview/valueview.BifidExpert.js
b/ValueView/resources/jquery.valueview/valueview.BifidExpert.js
index 57bb979..e56b8b2 100644
--- a/ValueView/resources/jquery.valueview/valueview.BifidExpert.js
+++ b/ValueView/resources/jquery.valueview/valueview.BifidExpert.js
@@ -1,17 +1,19 @@
/**
- * @file
- * @ingroup ValueView
* @licence GNU GPL v2+
* @author Daniel Werner < [email protected] >
*/
-( function( dv, vp, $, vv ) {
+jQuery.valueview = ( function( dv, vp, $, Expert ) {
'use strict';
- var PARENT = vv.Expert;
+ var PARENT = Expert;
/**
* Abstract definition of a Valueview expert whose responsibilities are
shared by two valueview
* experts; one taking over during edit mode, one being responsible
while in static mode.
+ *
+ * TODO: Get rid of this by using value formatters in jQuery.valueview
by injecting a
+ * formatter factory. Experts will then no longer be responsible for
serving a non-edit
+ * representation of the value and there won't be any purpose for the
BifidExpert anymore.
*
* @since 0.1
*
@@ -19,7 +21,7 @@
* @constructor
* @extends jQuery.valueview.Expert
*/
- vv.BifidExpert = dv.util.inherit( PARENT, {
+ return dv.util.inherit( PARENT, {
/**
* Constructor for the valueview expert responsible during
static mode.
* @type Function
@@ -172,4 +174,4 @@
}
} );
-}( dataValues, valueParsers, jQuery, jQuery.valueview ) );
+}( dataValues, valueParsers, jQuery, jQuery.valueview.Expert ) );
diff --git a/ValueView/resources/jquery.valueview/valueview.Expert.js
b/ValueView/resources/jquery.valueview/valueview.Expert.js
index 1dd5947..d955541 100644
--- a/ValueView/resources/jquery.valueview/valueview.Expert.js
+++ b/ValueView/resources/jquery.valueview/valueview.Expert.js
@@ -1,9 +1,4 @@
/**
- * Abstract base widget for editing and representing data values and a factory
for defining
- * more concrete implementations of that widget, similar to jQuery.widget.
- *
- * @file
- * @ingroup ValueView
* @licence GNU GPL v2+
* @author Daniel Werner < [email protected] >
*/
@@ -11,12 +6,13 @@
'use strict';
/**
- * Creates a new expert definition as it is required within
jQuery.datatypes.valueview to allow
- * usage of a certain data value type or data type.
+ * Creates a new expert definition as it is required by
jQuery.datatypes.valueview.
*
- * NOTE: Just by defining a new expert here, the expert won't be
available in the valueview
- * widget automatically. The expert has to be registered in a
jQuery.valueview.ExpertFactory
- * instance which has to be used as expert provider in the
valueview widget's options.
+ * NOTE: Just by defining a new expert here, the expert won't be
available in a valueview
+ * widget automatically. The expert has to be registered in a
jQuery.valueview.ExpertFactory
+ * instance which has to be used as expert provider in the valueview
widget's options.
+ *
+ * @see jQuery.valueview.Expert
*
* @since 0.1
*
@@ -50,7 +46,11 @@
/**
* Abstract class for strategies used in jQuery.valueview.valueview for
displaying and handling
- * a certain type of data value or data values of a certain data type.
+ * a certain type of data value or data values suitable for a certain
data type.
+ * The expert itself is conceptually not dependent on data types. It
always works with data
+ * values but the way it is presenting the edit interface could be
optimized for data values
+ * suitable for a certain data type. This could for example be done by
restrictions in the
+ * edit interface by reflecting a data type's validation rules.
*
* NOTE: Consider using jQuery.valueview.expert to define a new expert
instead of inheriting
* from this base directly.
@@ -67,8 +67,8 @@
* @param {Object} [options={}]
*
* TODO: think about whether there should be a function to add multiple
notifiers for widget
- * developers or whether they should rather listen to the
valueview widget while the
- * experts can't be touched. Less performant alternative would be
to use DOM events.
+ * developers or whether they should rather listen to the valueview
widget while the experts
+ * can not be touched. Less performant alternative would be the usage
of DOM events.
*
* @constructor
* @abstract
diff --git a/ValueView/resources/jquery.valueview/valueview.ExpertFactory.js
b/ValueView/resources/jquery.valueview/valueview.ExpertFactory.js
index 5dd3131..8d69643 100644
--- a/ValueView/resources/jquery.valueview/valueview.ExpertFactory.js
+++ b/ValueView/resources/jquery.valueview/valueview.ExpertFactory.js
@@ -1,13 +1,24 @@
/**
- * @file
- * @ingroup ValueView
+ * Factory for creating jQuery.valueview.Expert instances suitable for
handling data values of a
+ * specific data value type or for handling data values suitable for a certain
data type.
+ *
+ * Experts can be registered for generic handling of a certain data value type
or for handling of
+ * data values suitable for a given data type.
+ * EXAMPLE:
+ * The String data value could be handled by a StringExpert, so this expert
would be used when
+ * asking for "getExpert( stringValue )". An url data type which is
internally using string values
+ * to represent URLs would now automatically work with that same StringExpert
when asking for
+ * "getExpert( urlDataType )". Displaying the value via the expert would
result into the URL being
+ * formatted as a string. As a solution for rendering the URL as a link, an
UrlExpert could be
+ * created and registered for the URL data type explicitly.
+ *
* @licence GNU GPL v2+
* @author Daniel Werner < [email protected] >
*/
-( function( DataValue, dt, $, vv ) {
+jQuery.valueview.ExpertFactory = ( function( DataValue, dt, $ ) {
'use strict';
- var SELF = vv.ExpertFactory = function ValueviewExpertFactory() {
+ var SELF = function ValueviewExpertFactory() {
this._expertsForDataValueTypes = {};
this._expertsForDataTypes = {};
};
@@ -214,4 +225,6 @@
}
};
-}( dataValues.DataValue, dataTypes, jQuery, jQuery.valueview ) );
+ return SELF;
+
+}( dataValues.DataValue, dataTypes, jQuery ) );
diff --git a/ValueView/resources/jquery.valueview/valueview.experts/experts.js
b/ValueView/resources/jquery.valueview/valueview.experts/experts.js
index 9c83e72..9cda08a 100644
--- a/ValueView/resources/jquery.valueview/valueview.experts/experts.js
+++ b/ValueView/resources/jquery.valueview/valueview.experts/experts.js
@@ -1,23 +1,12 @@
/**
- * @file
- * @ingroup ValueView
+ * Space for basic jQuery.valueview.Expert implementations.
+ *
+ * @since 0.1
+ *
+ * @type Object
+ *
* @licence GNU GPL v2+
* @author Daniel Werner < [email protected] >
*/
-( function( $, vv ) {
- 'use strict';
-
- /**
- * Space for jQuery.valueview.Expert implementations introduced by this
extension. A valueview
- * expert is required to handle a certain type of data value in the
valueview.
- *
- * NOTE: Expert implementations by other extensions might use a
different place for those
- * implementations constructors.
- *
- * @since 0.1
- *
- * @type Object
- */
- vv.experts = {};
-
-}( jQuery, jQuery.valueview ) );
+jQuery.valueview.experts = ( new function jQueryValueViewExperts() {
+}() );
--
To view, visit https://gerrit.wikimedia.org/r/92422
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I67a3ea0114aed6673009dfcd0c5c3c89cf68da56
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/DataValues
Gerrit-Branch: master
Gerrit-Owner: Daniel Werner <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
