Commit b6ed6e74 authored by webchick's avatar webchick

Issue #2530764 by eiriksm: JSDoc quickedit module

parent 95757077
......@@ -32,7 +32,9 @@
* @inheritdoc
*
* @param {object} fieldModel
* The field model that holds the state.
* @param {string} state
* The state to change to.
*/
stateChange: function (fieldModel, state) {
var from = fieldModel.previous('state');
......@@ -80,6 +82,7 @@
* @inheritdoc
*
* @return {object}
* A settings object for the quick edit UI.
*/
getQuickEditUISettings: function () {
return {padding: true, unifiedToolbar: true, fullWidthToolbar: true, popup: true};
......
......@@ -20,6 +20,7 @@
* @augments Drupal.quickedit.EditorView
*
* @param {object} options
* Options for the plain text editor.
*/
initialize: function (options) {
Drupal.quickedit.EditorView.prototype.initialize.call(this, options);
......@@ -55,6 +56,7 @@
* @inheritdoc
*
* @return {jQuery}
* The text element for the plain text editor.
*/
getEditedElement: function () {
return this.$textElement;
......@@ -64,8 +66,11 @@
* @inheritdoc
*
* @param {object} fieldModel
* The field model that holds the state.
* @param {string} state
* The state to change to.
* @param {object} options
* State options, if needed by the state change.
*/
stateChange: function (fieldModel, state, options) {
var from = fieldModel.previous('state');
......@@ -121,6 +126,7 @@
* @inheritdoc
*
* @return {object}
* A settings object for the quick edit UI.
*/
getQuickEditUISettings: function () {
return {padding: true, unifiedToolbar: false, fullWidthToolbar: false, popup: false};
......
......@@ -15,8 +15,10 @@
* @augments Backbone.Model
*
* @param {object} options
* Options for the base model-
*
* @return {Drupal.quickedit.BaseModel}
* A quickedit base model.
*/
initialize: function (options) {
this.__initialized = true;
......@@ -24,12 +26,18 @@
},
/**
* Set a value on the model
*
* @param {object|string} key
* The key to set a value for.
* @param {*} val
* The value to set.
* @param {object} [options]
* Options for the model.
*
* @return {*}
* The result of `Backbone.Model.prototype.set` with the specified
* parameters.
*/
set: function (key, val, options) {
if (this.__initialized) {
......
......@@ -114,6 +114,7 @@
* @augments Drupal.quickedit.BaseModel
*
* @param {object} options
* Options for the field model.
*/
initialize: function (options) {
// Store the original full HTML representation of this field.
......@@ -130,8 +131,10 @@
},
/**
* Destroys the field model.
*
* @param {object} options
* Options for the field model.
*/
destroy: function (options) {
if (this.get('state') !== 'inactive') {
......@@ -149,6 +152,7 @@
},
/**
* Validate function for the field model.
*
* @param {object} attrs
* The attributes changes in the save or set call.
......@@ -165,6 +169,7 @@
* validate and proceed.
*
* @return {string}
* A string to say something about the state of the field model.
*/
validate: function (attrs, options) {
var current = this.get('state');
......@@ -319,6 +324,7 @@
* One of {@link Drupal.quickedit.FieldModel.states}.
*
* @return {bool}
* Whether the 'from' state comes before the 'to' state.
*/
followsStateSequence: function (from, to) {
return _.indexOf(this.states, from) < _.indexOf(this.states, to);
......
......@@ -160,29 +160,42 @@
metadata: {
/**
* Check if a field exists in storage.
*
* @param {string} fieldID
* The field id to check.
*
* @return {bool}
* Whether it was found or not.
*/
has: function (fieldID) {
return storage.getItem(this._prefixFieldID(fieldID)) !== null;
},
/**
* Add metadata to a field id.
*
* @param {string} fieldID
* The field ID to add data to.
* @param {object} metadata
* Metadata to add.
*/
add: function (fieldID, metadata) {
storage.setItem(this._prefixFieldID(fieldID), JSON.stringify(metadata));
},
/**
* Get a key from a field id.
*
* @param {string} fieldID
* The field ID to check.
* @param {string} [key]
* The key to check. If empty, will return all metadata.
*
* @return {object|*}
* The value for the key, if defined. Otherwise will return all metadata
* for the specified field id.
*
*/
get: function (fieldID, key) {
var metadata = JSON.parse(storage.getItem(this._prefixFieldID(fieldID)));
......@@ -190,20 +203,26 @@
},
/**
* Prefix the field id.
*
* @param {string} fieldID
* The field id to prefix.
*
* @return {string}
* A prefixed field id.
*/
_prefixFieldID: function (fieldID) {
return 'Drupal.quickedit.metadata.' + fieldID;
},
/**
* Unprefix the field id.
*
* @param {string} fieldID
* The field id to unprefix.
*
* @return {string}
* An unprefixed field id.
*/
_unprefixFieldID: function (fieldID) {
// Strip "Drupal.quickedit.metadata.", which is 26 characters long.
......@@ -211,10 +230,13 @@
},
/**
* Intersection calculation.
*
* @param {string} fieldIDs
* @param {Array} fieldIDs
* An array of field ids to compare to prefix field id.
*
* @return {Array}
* The intersection found.
*/
intersection: function (fieldIDs) {
var prefixedFieldIDs = _.map(fieldIDs, this._prefixFieldID);
......@@ -246,7 +268,9 @@
* Queue contextual links to be processed.
*
* @param {jQuery.Event} event
* The `drupalContextualLinkAdded` event.
* @param {object} data
* An object containing the data relevant to the event.
*
* @listens event:drupalContextualLinkAdded
*/
......
......@@ -11,6 +11,7 @@
* Theme function for a "backstage" for the Quick Edit module.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {string} settings.id
* The id to apply to the backstage.
*
......@@ -27,6 +28,7 @@
* Theme function for a toolbar container of the Quick Edit module.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {string} settings.id
* the id to apply to the backstage.
*
......@@ -50,6 +52,7 @@
* Theme function for a toolbar container of the Quick Edit module.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {string} settings.entityLabel
* The title of the active entity.
* @param {string} settings.fieldLabel
......@@ -77,6 +80,7 @@
* Theme function for a toolbar container of the Quick Edit module.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {string} settings.id
* The id to apply to the toolbar container.
*
......@@ -91,6 +95,7 @@
* Theme function for a toolbar toolgroup of the Quick Edit module.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {string} [settings.id]
* The id of the toolgroup.
* @param {string} settings.classes
......@@ -123,6 +128,7 @@
* modal.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {Array} settings.buttons
* - String type: the type of the button (defaults to 'button')
* - Array classes: the classes of the button.
......@@ -157,6 +163,7 @@
* Theme function for a form container of the Quick Edit module.
*
* @param {object} settings
* Settings object used to construct the markup.
* @param {string} settings.id
* The id to apply to the toolbar container.
* @param {string} settings.loadingMsg
......
......@@ -38,6 +38,7 @@
* The Controller route for field processing.
*
* @return {string}
* The formatted URL.
*/
Drupal.quickedit.util.buildUrl = function (id, urlFormat) {
var parts = id.split('/');
......@@ -146,6 +147,7 @@
* Creates a {@link Drupal.Ajax} instance that is used to save a form.
*
* @param {object} options
* Submit options to the form.
* @param {bool} options.nocssjs
* Boolean indicating whether no CSS and JS should be returned (necessary
* when the form is invisible to the user).
......@@ -153,6 +155,7 @@
* Array containing view mode IDs (of other instances of this field on the
* page).
* @param {jQuery} $submit
* The submit element.
*
* @return {Drupal.Ajax}
* A {@link Drupal.Ajax} instance.
......@@ -176,7 +179,9 @@
* form.
*
* @param {Drupal.AjaxCommands~commandDefinition} response
* The Drupal AJAX response.
* @param {number} [status]
* The HTTP status code.
*/
success: function (response, status) {
for (var i in response) {
......
......@@ -127,6 +127,7 @@
* The fieldModel to which this change applies.
*
* @return {bool}
* Whether the editor change was accepted or rejected.
*/
acceptEditorStateChange: function (from, to, context, fieldModel) {
var accept = true;
......@@ -328,6 +329,7 @@
* Asks the user to confirm whether he wants to stop editing via a modal.
*
* @param {Drupal.quickedit.EntityModel} entityModel
* An instance of the EntityModel class.
*
* @see Drupal.quickedit.AppView#acceptEditorStateChange
*/
......@@ -402,6 +404,7 @@
* Reacts to field state changes; tracks global state.
*
* @param {Drupal.quickedit.FieldModel} fieldModel
* The `fieldModel` holding the state.
* @param {string} state
* The state of the associated field. One of
* {@link Drupal.quickedit.FieldModel.states}.
......
......@@ -13,6 +13,7 @@
* Define all events to listen to.
*
* @return {object}
* A map of events.
*/
events: function () {
// Prevents delay and simulated mouse events.
......@@ -31,6 +32,8 @@
},
/**
* Create a new contextual link view.
*
* @constructs
*
* @augments Backbone.View
......@@ -54,11 +57,15 @@
},
/**
* Render function for the contextual link view.
*
* @param {Drupal.quickedit.EntityModel} entityModel
* The associated `EntityModel`.
* @param {bool} isActive
* Whether the in-place editor is active or not.
*
* @return {Drupal.quickedit.ContextualLinkView}
* The `ContextualLinkView` in question.
*/
render: function (entityModel, isActive) {
this.$el.find('a').attr('aria-pressed', isActive);
......
......@@ -93,6 +93,7 @@
* Determines the actions to take given a change of state.
*
* @param {Drupal.quickedit.FieldModel} fieldModel
* The quickedit `FieldModel` that holds the state.
* @param {string} state
* The state of the associated field. One of
* {@link Drupal.quickedit.FieldModel.states}.
......
......@@ -16,6 +16,7 @@
/**
* @return {object}
* A map of events.
*/
events: function () {
var map = {
......@@ -32,7 +33,9 @@
* @augments Backbone.View
*
* @param {object} options
* Options to construct the view.
* @param {Drupal.quickedit.AppModel} options.appModel
* A quickedit `AppModel` to use in the view.
*/
initialize: function (options) {
var that = this;
......@@ -71,6 +74,7 @@
* @inheritdoc
*
* @return {Drupal.quickedit.EntityToolbarView}
* The entity toolbar view.
*/
render: function () {
if (this.model.get('isActive')) {
......@@ -147,6 +151,7 @@
* Repositions the entity toolbar on window scroll and resize.
*
* @param {jQuery.Event} event
* The scroll or resize event.
*/
windowChangeHandler: function (event) {
this.position();
......@@ -156,6 +161,7 @@
* Determines the actions to take given a change of state.
*
* @param {Drupal.quickedit.FieldModel} model
* The `FieldModel` model.
* @param {string} state
* The state of the associated field. One of
* {@link Drupal.quickedit.FieldModel.states}.
......@@ -254,6 +260,7 @@
* positionToolbar().
*
* @param {*} view
* The view the positions will be calculated from.
* @param {object} suggested
* A hash of top and left values for the position that should be set. It
* can be forwarded to .css() or .animate().
......@@ -345,6 +352,7 @@
* Set the model state to 'saving' when the save button is clicked.
*
* @param {jQuery.Event} event
* The click event.
*/
onClickSave: function (event) {
event.stopPropagation();
......@@ -357,6 +365,7 @@
* Sets the model state to candidate when the cancel button is clicked.
*
* @param {jQuery.Event} event
* The click event.
*/
onClickCancel: function (event) {
event.preventDefault();
......@@ -369,6 +378,7 @@
* Without this, it may reposition itself, away from the user's cursor!
*
* @param {jQuery.Event} event
* The mouse event.
*/
onMouseenter: function (event) {
clearTimeout(this.timer);
......@@ -378,6 +388,7 @@
* Builds the entity toolbar HTML; attaches to DOM; sets starting position.
*
* @return {jQuery}
* The toolbar element.
*/
buildToolbarEl: function () {
var $toolbar = $(Drupal.theme('quickeditEntityToolbar', {
......
......@@ -56,6 +56,7 @@
* Determines the actions to take given a change of state.
*
* @param {Drupal.quickedit.FieldModel} model
* The `FieldModel` model.
* @param {string} state
* The state of the associated field. One of
* {@link Drupal.quickedit.FieldModel.states}.
......@@ -128,6 +129,7 @@
* Starts hover; transitions to 'highlight' state.
*
* @param {jQuery.Event} event
* The mouse event.
*/
onMouseEnter: function (event) {
var that = this;
......@@ -139,6 +141,7 @@
* Stops hover; transitions to 'candidate' state.
*
* @param {jQuery.Event} event
* The mouse event.
*/
onMouseLeave: function (event) {
var that = this;
......@@ -150,6 +153,7 @@
* Transition to 'activating' stage.
*
* @param {jQuery.Event} event
* The click event.
*/
onClick: function (event) {
this.model.set('state', 'activating');
......@@ -313,8 +317,10 @@
* subtraction.
*
* @param {jQuery} $e
* The element to get position properties from.
*
* @return {object}
* An object containing css values for the needed properties.
*/
_getPositionProperties: function ($e) {
var p;
......@@ -340,6 +346,7 @@
* The value for a CSS position declaration.
*
* @return {string}
* A CSS value that is valid for `position`.
*/
_replaceBlankPosition: function (pos) {
if (pos === 'auto' || !pos) {
......
......@@ -34,15 +34,17 @@
* @augments Backbone.View
*
* @param {object} options
* Options object to construct the field toolbar.
* @param {jQuery} options.$editedElement
* The element being edited.
* @param {Drupal.quickedit.EditorView} options.editorView
* The EditorView the toolbar belongs to.
*/
initialize: function (options) {
this.$editedElement = options.$editedElement;
this.editorView = options.editorView;
/**
*
* @type {jQuery}
*/
this.$root = this.$el;
......@@ -57,6 +59,7 @@
* @inheritdoc
*
* @return {Drupal.quickedit.FieldToolbarView}
* The current FieldToolbarView.
*/
render: function () {
// Render toolbar and set it as the view's element.
......@@ -74,6 +77,7 @@
* Determines the actions to take given a change of state.
*
* @param {Drupal.quickedit.FieldModel} model
* The quickedit FieldModel
* @param {string} state
* The state of the associated field. One of
* {@link Drupal.quickedit.FieldModel.states}.
......@@ -191,6 +195,7 @@
* A toolgroup name.
*
* @return {jQuery}
* The toolgroup element.
*/
_find: function (toolgroup) {
return this.$el.find('.quickedit-toolgroup.' + toolgroup);
......@@ -204,8 +209,8 @@
*/
show: function (toolgroup) {
var $group = this._find(toolgroup);
// Attach a transitionEnd event handler to the toolbar group so that update
// events can be triggered after the animations have ended.
// Attach a transitionEnd event handler to the toolbar group so that
// update events can be triggered after the animations have ended.
$group.on(Drupal.quickedit.util.constants.transitionEnd, function (event) {
$group.off(Drupal.quickedit.util.constants.transitionEnd);
});
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment