Henning Snater has uploaded a new change for review. https://gerrit.wikimedia.org/r/188047
Change subject: snakview.variations*: Updated documentation ...................................................................... snakview.variations*: Updated documentation Change-Id: I5ab898aff6fbbeb1e30770d18d0c240a4f9f9aeb --- M lib/resources/jquery.wikibase/snakview/snakview.variations.NoValue.js M lib/resources/jquery.wikibase/snakview/snakview.variations.SomeValue.js M lib/resources/jquery.wikibase/snakview/snakview.variations.Value.js M lib/resources/jquery.wikibase/snakview/snakview.variations.Variation.js M lib/resources/jquery.wikibase/snakview/snakview.variations.js 5 files changed, 184 insertions(+), 186 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Wikibase refs/changes/47/188047/1 diff --git a/lib/resources/jquery.wikibase/snakview/snakview.variations.NoValue.js b/lib/resources/jquery.wikibase/snakview/snakview.variations.NoValue.js index 110b1db..534def6 100644 --- a/lib/resources/jquery.wikibase/snakview/snakview.variations.NoValue.js +++ b/lib/resources/jquery.wikibase/snakview/snakview.variations.NoValue.js @@ -1,8 +1,3 @@ -/** - * - * @licence GNU GPL v2+ - * @author Daniel Werner < [email protected] > - */ ( function( mw, wb, $ ) { 'use strict'; @@ -10,16 +5,21 @@ PARENT = MODULE.Variation; /** - * Required snakview variation for displaying and creating PropertyNoValue Snaks. Only displays - * a message, doesn't offer any additional user interface interaction. - * - * @constructor + * `snakview` `Variation` for displaying and creating `wikibase.datamodel.PropertyNoValueSnak`s. + * Only displays a message, does not offer any additional user interface interaction. + * @see jQuery.wikibase.snakview + * @see wikibase.datamodel.PropertyNoValueSnak + * @class jQuery.wikibase.snakview.variations.NoValue * @extends jQuery.wikibase.snakview.variations.Variation * @since 0.4 + * @licence GNU GPL v2+ + * @author Daniel Werner < [email protected] > + * + * @constructor */ MODULE.variation( wb.datamodel.PropertyNoValueSnak, PARENT, { /** - * @see jQuery.wikibase.snakview.variations.Variation.draw + * @inheritdoc */ draw: function() { // display same message in edit and non-edit mode! diff --git a/lib/resources/jquery.wikibase/snakview/snakview.variations.SomeValue.js b/lib/resources/jquery.wikibase/snakview/snakview.variations.SomeValue.js index a2b5d47..78fcb9c 100644 --- a/lib/resources/jquery.wikibase/snakview/snakview.variations.SomeValue.js +++ b/lib/resources/jquery.wikibase/snakview/snakview.variations.SomeValue.js @@ -1,8 +1,3 @@ -/** - * - * @licence GNU GPL v2+ - * @author Daniel Werner < [email protected] > - */ ( function( mw, wb, $ ) { 'use strict'; @@ -10,16 +5,22 @@ PARENT = MODULE.Variation; /** - * Required snakview variation for displaying and creating PropertySomeValue Snaks. Only displays - * a message, doesn't offer any additional user interface interaction. - * - * @constructor + * `snakview` `Variation` for displaying and creating + * `wikibase.datamodel.PropertySomeValueSnak`s. Only displays a message, does not offer any + * additional user interface interaction. + * @see jQuery.wikibase.snakview + * @see wikibase.datamodel.PropertySomeValueSnak + * @class jQuery.wikibase.snakview.varaiations.SomeValue * @extends jQuery.wikibase.snakview.variations.Variation * @since 0.4 + * @licence GNU GPL v2+ + * @author Daniel Werner < [email protected] > + * + * @constructor */ MODULE.variation( wb.datamodel.PropertySomeValueSnak, PARENT, { /** - * @see jQuery.wikibase.snakview.variations.Variation.draw + * @inheritdoc */ draw: function() { // display same message in edit and non-edit mode! diff --git a/lib/resources/jquery.wikibase/snakview/snakview.variations.Value.js b/lib/resources/jquery.wikibase/snakview/snakview.variations.Value.js index cf7b40b..e0ae443 100644 --- a/lib/resources/jquery.wikibase/snakview/snakview.variations.Value.js +++ b/lib/resources/jquery.wikibase/snakview/snakview.variations.Value.js @@ -1,7 +1,3 @@ -/** - * @licence GNU GPL v2+ - * @author Daniel Werner < [email protected] > - */ ( function( mw, wb, $, dv ) { 'use strict'; @@ -9,31 +5,39 @@ PARENT = MODULE.Variation; /** - * Required snakview variation for displaying and creating PropertyValueSnak Snaks. Serves a - * valueview input widget when in edit mode and uses the same to display the Snak's value in - * non-edit mode. - * - * @constructor + * `snakview` `Variation` for displaying and creating `wikibase.datamodel.PropertyValueSnak`s. + * Serves a `jQuery.valueview` widget used to display and alter the `Snak`'s value. + * @see jQuery.valueview + * @see jQuery.wikibase.snakview + * @see wikibase.datamodel.PropertyValueSnak + * @class jQuery.wikibase.snakview.variations.Value * @extends jQuery.wikibase.snakview.variations.Variation * @since 0.4 + * @licence GNU GPL v2+ + * @author Daniel Werner < [email protected] > + * + * @constructor */ MODULE.variation( wb.datamodel.PropertyValueSnak, PARENT, { /** - * The value view widget object or null if property's data type isn't supported. - * @type jQuery.valueview.Widget + * The `valueview` widget instance or `null` if the `Property`'s `DataType` is not + * supported. + * @property {jQuery.valueview|null} [_valueView=null] + * @private */ _valueView: null, /** - * The data value last set in _setValue(). This field will not be updated, it only serves - * to remember the value until draw() is called. Afterwards, it is set to false until the - * next call to _setValue(). - * @type dv.DataValue|null|false + * The `DataValue` last set in `_setValue()`. This field will not be updated, it only serves + * to remember the value until `draw()` is called. Afterwards, it is set to `false` until + * the next call to `_setValue()`. + * @property {dataValues.DataValue|null|false} [_newDataValue=null] + * @private */ _newDataValue: null, /** - * @see jQuery.wikibase.snakview.variations.Variation.destroy + * @inheritdoc */ destroy: function() { this.$viewPort.css( 'height', 'auto' ); @@ -45,7 +49,8 @@ }, /** - * @see jQuery.wikibase.snakview.variations.Variation._setValue + * @inheritdoc + * @protected */ _setValue: function( value ) { this._newDataValue = null; @@ -55,7 +60,8 @@ }, /** - * @see jQuery.wikibase.snakview.variations.Variation._getValue + * @inheritdoc + * @protected */ _getValue: function() { var dataValue = null; @@ -74,7 +80,7 @@ }, /** - * @see jQuery.wikibase.snakview.variations.Variation.draw + * @inheritdoc */ draw: function() { var self = this, @@ -205,7 +211,7 @@ }, /** - * @see jQuery.wikibase.snakview.variations.Variation.startEditing + * @inheritdoc */ startEditing: function() { if( !this._valueView || this._valueView.isInEditMode() ) { @@ -227,7 +233,7 @@ }, /** - * @see jQuery.wikibase.snakview.variations.Variation.stopEditing + * @inheritdoc */ stopEditing: function( dropValue ) { if( !this._valueView || !this._valueView.isInEditMode() ) { @@ -239,7 +245,8 @@ }, /** - * Attaches event handlers to the value view widget's element. + * Attaches event handlers to the `valueview` widget's element. + * @private */ _attachEventHandlers: function() { var self = this, @@ -298,22 +305,22 @@ }, /** - * Removes event handlers from the value view widget's element. + * Removes event handlers from the `valueview` widget's element. + * @private */ _removeEventHandlers: function() { this._valueView.element.off( '.' + this.variationBaseClass ); }, /** - * Will create and insert a new valueview, also updates the internal _valueView field. - * The previously used valueview will be destroyed. + * Creates and inserts a new `jQuery.valueview` while destroying the previously used + * `jQuery.valueview` instance. * - * @since 0.4 - * - * @param {dv.DataValue} dataValue - * @param {dataTypes.DataType} [dataType] The data type for which the given data value has - * been created. Can be omitted but might result in a less specialized valueview. - * @return {boolean} Whether a valueview has actually been created. + * @param {dataValues.DataValue} dataValue + * @param {dataTypes.DataType} [dataType] The `DataTypes` which the given `DataValue` has + * been created for. Can be omitted but might result in a less specialized + * `jQuery.valueview`. + * @return {boolean} Whether a `jQuery.valueview` has actually been instantiated. */ _createNewValueView: function( dataValue, dataType ) { var $valueViewDom; @@ -351,14 +358,14 @@ }, /* - * @see jQuery.wikibase.snakview.variations.Variation.isFocusable + * @inheritdoc */ isFocusable: function() { return true; }, /** - * @see jQuery.wikibase.snakview.variations.Variation.focus + * @inheritdoc */ focus: function() { if( this._valueView && this._viewState.isDisabled() === false ) { @@ -367,7 +374,7 @@ }, /** - * @see jQuery.wikibase.snakview.variations.Variation.blur + * @inheritdoc */ blur: function() { if( this._valueView ) { diff --git a/lib/resources/jquery.wikibase/snakview/snakview.variations.Variation.js b/lib/resources/jquery.wikibase/snakview/snakview.variations.Variation.js index b50c63a..d2d0569 100644 --- a/lib/resources/jquery.wikibase/snakview/snakview.variations.Variation.js +++ b/lib/resources/jquery.wikibase/snakview/snakview.variations.Variation.js @@ -10,30 +10,35 @@ $.wikibase.snakview.variations = $.wikibase.snakview.variations || {}; /** - * Abstract base for all kinds of variations within jQuery.snakview for representing different - * kinds of PropertySnaks. These implementations are responsible for representing parts of a - * certain kind of PropertyValue Snak and offer a factory method for building an instance of - * that kind of Snak. - * When a jQuery snakview for PropertyValue Snaks enters edit mode, it will offer a selector for - * choosing the Snak type, e.g. "No Value", "Some Value", "Value" etc. When choosing one, an - * instance of the related jQuery.wikibase.snakview.variations.Variation will be loaded, displaying - * the essential part of that kind of Snak, which makes it different from other kinds of Snaks. - * - * @constructor + * Abstract base for all kinds of `Variation`s to be used by `jQuery.wikibase.snakview` to + * represent the different types of `wikibase.datamodel.Snak` objects. + * @see wikibase.datamodel.Snak + * @class jQuery.wikibase.snakview.variations.Variation * @abstract * @since 0.4 * - * @param {$.wikibase.snakview.ViewState} viewState Information about the related - * snakview. This is required for rendering according to the view's current state. - * @param {jQuery} $viewPort A DOM node which serves as drawing surface for this variation's - * output, this is where this variation can express its current state and/or display - * input elements for user interaction. - * @param {wb.store.EntityStore} entityStore - * @param {wb.ValueViewBuilder} valueViewBuilder - * @param {dataTypes.DataTypeStore} dataTypeStore + * @constructor * - * @event afterdraw: Triggered on the Variation object after drawing the variation. - * (1) {jQuery.Event} + * @param {jQuery.wikibase.snakview.ViewState} viewState Interface that allows retrieving + * information from the related `snakview` instance as well as updating the `snakview` + * instance. + * @param {jQuery} $viewPort A DOM node which serves as drawing surface for the `Variation`'s + * output. This is where the `Variation` instance expresses its current state and/or + * displays input elements for user interaction. + * @param {wikibase.store.EntityStore} entityStore Enables the `Variation` to retrieve `Entity` + * information. + * @param {wikibase.ValueViewBuilder} valueViewBuilder Enables the `Variation` to have + * `jQuery.valueview` instances created according to particular `dataTypes.DataType` / + * `dataValues.DataValue` objects. + * @param {dataTypes.DataTypeStore} dataTypeStore Enables the `Variation` to retrieve a + * `dataTypes.DataType` instance for a particular `DataType` ID. + * + * @throws {Error} if a required parameter is not specified properly. + */ + /** + * @event afterdraw + * Triggered on the `Variation` object after drawing the `Variation`. + * @param {jQuery.Event} event */ var SELF = $.wikibase.snakview.variations.Variation = function WbSnakviewVariationsVariation( viewState, @@ -61,60 +66,59 @@ }; $.extend( SELF.prototype, { /** - * A unique class for this variation. Will be set by the variations factory when creating a - * new variation definition. - * @type String + * A unique class for this `Variation`, applied to the `Variation` DOM's `class` attribute. + * Will be set by the `Variation` factory when creating a new `Variation` definition. + * @property {string} + * @readonly */ variationBaseClass: null, /** - * The constructor of the variation's related kind of Snak. Will be set by the variations - * factory when creating a new variation definition. - * @type wb.datamodel.Snak + * The constructor of the `Snak` the `Variation` is for. Will be set by the `Variation` + * factory when creating a new `Variation` definition. + * @property {wikibase.datamodel.Snak} + * @readonly */ variationSnakConstructor: null, /** - * The DOM node which has to be updated by the draw() function. Displays current state - * and/or input elements for user interaction during snakview's edit mode. - * @type jQuery + * The DOM node displaying the `Variation`'s current state and/or input elements for user + * interaction during the `snakview`'s edit mode. The node's content has to be updated by + * the `draw()` function. + * @property {jQuery} + * @protected */ $viewPort: null, /** - * @type wb.store.EntityStore + * @property {wikibase.store.EntityStore} */ _entityStore: null, /** - * @type {wikibase.ValueViewBuilder} + * @property {wikibase.ValueViewBuilder} */ _valueViewBuilder: null, /** - * Object representing the state of the related snakview. - * @type $.wikibase.snakview.ViewState + * @property {jQuery.wikibase.snakview.ViewState} */ _viewState: null, /** - * @type {dataTypes.DataTypeStore} + * @property {dataTypes.DataTypeStore} */ _dataTypeStore: null, /** - * Will be called initially for new variation instances. - * - * @since 0.4 + * @protected */ _init: function() { this._viewState.notify( 'valid' ); }, /** - * Gets called when the snakview's destroy function is called. - * - * @since 0.4 + * Destroys the `Variation`. */ destroy: function() { this.$viewPort.removeClass( this.variationBaseClass ); @@ -123,27 +127,29 @@ }, /** - * Returns an object offering information about the related snakview's current state. + * Returns an object that offers information about the related `snakview`'s current state as + * well as allows updating the `snakview` instance. + * @see jQuery.wikibase.snakview * - * @since 0.4 - * - * @return $.wikibase.snakview.ViewState + * @return {jQuery.wikibase.snakview.ViewState} */ viewState: function() { return this._viewState; }, /** - * Will set or return the value of the variation's part of the Snak. - * - * @since 0.4 + * Sets/Gets the value of the `Variation`'s part of the `Snak` by accepting/returning an + * incomplete `Snak` serialization containing the parts of the `Snak` specific to the `Snak` + * bound to the `Variation`. Equivalent to what + * `wikibase.serialization.SnakSerializer.serialize()` returns, just without the fields + * `snaktype` and `property`. + * @see wikibase.serialization.SnakSerializer * * @param {Object} [value] - * @return {Object|undefined} Plain Object with parts of the Snak specific to the - * variation's kind of Snak. Equivalent to what the serialize() function of - * wb.serialization.SnakSerializer would return, just without the basic fields - * 'snaktype' and 'property'. - * undefined in case value() is called to set the value. + * @return {Object|undefined} Incomplete `Snak` serialization containing the parts of the + * `Snak` specific to the `Snak` bound to the `Variation`. Equivalent to what + * `wikibase.serialization.SnakSerializer.serialize()` returns, just without the + * fields `snaktype` and `property`. */ value: function( value ) { if( value === undefined ) { @@ -153,54 +159,47 @@ }, /** - * Setter for value(). Does not trigger draw() but value( value ) will trigger draw(). - * Receives an Object which holds fields of the part of the Snak the variation is handling. - * The fields are the same as wb.serialization.SnakSerializer.serialize() would provide - * them. - * The 'property' and 'snaktype' fields will not be provided, they can be received per - * viewState().property() and viewState().snakType() if necessary. A missing field implies - * that the aspect of the Snak has not been defined yet. Then, the view should display a - * useful message or, in edit-mode, show empty input forms for user interaction. + * Sets the `Variation`s value by being passed an incomplete `Snak` serialization containing + * the parts of the `Snak` specific to the `Snak` type bound to the `Variation`. Equivalent + * to what `wikibase.serialization.SnakSerializer.serialize()` returns, just without the + * fields `snaktype` and `property`. These fields may be received per + * `viewState().property()` and `viewState().snakType()`, if necessary. A missing field + * implies that the aspect of the `Snak` was not defined yet. Then, the view should display + * a useful message or, in edit-mode, show empty input forms for user interaction. + * @protected * - * @since 0.4 - * - * @param {Object} value + * @param {Object} value Incomplete `Snak` serialization. */ _setValue: function( value ) {}, /** - * Getter for value(). Should return the aspects of the Snak which the variation is taking - * care of. Should be an Object with fields as the serialize() function of - * wb.serialization.SnakSerializer would return. For aspects of the Snak not defined yet, - * the related field should hold null. + * Gets the `Variation`s value returning an incomplete `Snak` serialization containing the + * parts of the `Snak` specific to the `Snak` type bound to the `Variation`. Equivalent to + * what `wikibase.serialization.SnakSerializer.serialize()` returns, just without the fields + * `snaktype` and `property`. Attributes of the `Snak` not defined yet, should be omitted + * from the returned incomplete serialization. * - * @since 0.4 - * - * @return Object + * @return {Object} Incomplete `Snak` serialization. */ _getValue: function() { return {}; }, /** - * Will change the view to display a certain data value. If the DOM to represent a value is - * not yet inserted, this will take care of its insertion. - * - * @since 0.4 - * - * @triggers afterdraw + * Updates the `Variation` view port's content. + * @abstract */ draw: util.abstractMember, /** - * Start the variation's edit mode. + * Start the `Variation`'s edit mode. */ startEditing: function() { $( this ).triggerHandler( 'afterstartediting' ); }, /** - * Stops the variation's edit mode. + * Stops the `Variation`'s edit mode. * * @param {boolean} dropValue */ @@ -216,16 +215,12 @@ }, /** - * Will set the focus if there is some focusable input object. - * - * @since 0.4 + * Sets the focus on the `Variation`. */ focus: function() {}, /** - * Makes sure that the focus will be removed from any focusable input object. - * - * @since 0.4 + * Removes focus from the `Variation`. */ blur: function() {} } ); diff --git a/lib/resources/jquery.wikibase/snakview/snakview.variations.js b/lib/resources/jquery.wikibase/snakview/snakview.variations.js index e397514..f45946d 100644 --- a/lib/resources/jquery.wikibase/snakview/snakview.variations.js +++ b/lib/resources/jquery.wikibase/snakview/snakview.variations.js @@ -1,7 +1,3 @@ -/** - * @licence GNU GPL v2+ - * @author Daniel Werner < [email protected] > - */ ( function( $, util ) { 'use strict'; @@ -13,48 +9,55 @@ var existingVariations = $.wikibase.snakview.variations || {}; /** - * Map of snak type IDs and related variations required for representing different kinds of - * Snaks with jQuery.snakview. - * @type {jQuery.wikibase.snakview.variations.Variation[]} + * Map of `Snak` type IDs and related `Variation`s required for representing different kinds of + * `Snaks` with `jQuery.wikibase.snakview`. + * @property {Object} + * @ignore */ var variations = {}; /** - * @type Object + * Store for `jQuery.wikibase.snakview.variations.Variation` objects. + * @class jQuery.wikibase.snakview.variations + * @singleton * @since 0.4 + * @licence GNU GPL v2+ + * @author Daniel Werner < [email protected] > */ var SELF = $.wikibase.snakview.variations = { /** - * Registers a new variation definition to allow usage of a certain Snak type within - * jQuery.snakview. This is a factory similar to the jQuery widget factory. + * Registers a new `jQuery.wikibase.snakview.variations.Variation` definition to enable + * using a a specific `Snak` type within `jQuery.wikibase.snakview`. Acts like the + * `jQuery.Widget` factory. * - * @since 0.4 - * - * @param {wb.datamodel.Snak} snakConstructor The constructor of the Snak the variation is made for. - * @param {Function|String} [base] Constructor or name of the variation the new variation - * should be based on. By default this is jQuery.snakview.variations.Variation. - * @param {Object} variationDefinition of the variation. - * - * @return {jQuery.snakview.variations.Variation} the new variation constructor. + * @param {wikibase.datamodel.Snak} snakConstructor The constructor of the `Snak` the + * `Variation` applies to. + * @param {Function|string|Object} baseOrDefinition Constructor or name of the `Variation` + * the new `Variation` should be based on. The parameter may be omitted resulting in + * the it being regarded the `definition` and `base` defaulting to + * `jQuery.snakview.variations.Variation`. + * @param {Object} [definition] The new `Variation`'s definition (new members and members + * overwriting the base `Variation`s members). + * @return {jQuery.snakview.variations.Variation} The new `Variation`'s constructor. */ - variation: function( snakConstructor, base, variationDefinition ) { + variation: function( snakConstructor, baseOrDefinition, definition ) { if( !$.isFunction( snakConstructor ) || !snakConstructor.TYPE ) { throw new Error( 'Snak constructor required for registering a snakview variation' ); } - if( !variationDefinition ) { - variationDefinition = base; - base = SELF.Variation; - } else if( typeof base === 'string' ) { - base = SELF.getVariation( base ); + if( !definition ) { + definition = baseOrDefinition; + baseOrDefinition = SELF.Variation; + } else if( typeof baseOrDefinition === 'string' ) { + baseOrDefinition = SELF.getVariation( baseOrDefinition ); } var snakType = snakConstructor.TYPE, variationName = 'WbSnakviewVariations_' + snakType; // name for constructor - var Variation = util.inherit( variationName, base, $.extend( + var Variation = util.inherit( variationName, baseOrDefinition, $.extend( { variationBaseClass: 'wikibase-snakview-variation-' + snakType + 'snak' }, - variationDefinition, + definition, { // we don't want to allow to overwrite this one via the definition variationSnakConstructor: snakConstructor } @@ -66,12 +69,10 @@ }, /** - * Returns all Snak types which can be represented by the snakview since there is a - * Variation constructor for presenting them. + * Returns all `Snak` types which can be represented by the `snakview` since there is a + * `Variation` constructor for presenting them. * - * @since 0.4 - * - * @return String[] + * @return {string[]} */ getCoveredSnakTypes: function() { var types = []; @@ -85,25 +86,21 @@ }, /** - * Returns whether there is a suitable 'variation' constructor for representing a certain - * kind of Snak with a jQuery.snakview. + * Returns whether a `Variation` constructor for representing a particular kind of `Snak` + * within a `jQuery.wikibase.snakview` is registered. * - * @since 0.4 - * - * @param snakType - * @return {Boolean} + * @param {string} snakType + * @return {boolean} */ hasVariation: function( snakType ) { return snakType in variations; }, /** - * Returns the variation constructor required for representing a certain kind of Snak with a - * jQuery.snakview. + * Returns the constructor of the `Variation` used to represent a particular kind of `Snak` + * within a `jQuery.wikibase.snakview`. * - * @since 0.4 - * - * @param snakType + * @param {string} snakType * @return {jQuery.wikibase.snakview.variations.Variation|*} */ getVariation: function( snakType ) { @@ -111,15 +108,13 @@ }, /** - * Returns the variation required by a jQuery.snakview for representing a certain kind of - * Snak, takes the Snak type as criteria for choosing the related variation. + * Returns a `Variation` instance used by a `jQuery.wikibase.snakview` for representing a + * particular kind of `Snak`. * - * @since 0.4 - * - * @param {String} snakType + * @param {string} snakType * @param {jQuery.wikibase.snakview.ViewState} viewState * @param {jQuery} $variationViewPort - * @return jQuery.wikibase.snakview.variations.Variation|null + * @return {jQuery.wikibase.snakview.variations.Variation|null} */ newFromSnakType: function( snakType, viewState, $variationViewPort ) { if( typeof snakType !== 'string' ) { -- To view, visit https://gerrit.wikimedia.org/r/188047 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I5ab898aff6fbbeb1e30770d18d0c240a4f9f9aeb Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/Wikibase Gerrit-Branch: master Gerrit-Owner: Henning Snater <[email protected]> _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
