Commit a7326f8e authored by webchick's avatar webchick

Issue #2514894 by eiriksm: JSDoc contextual module

parent f643d48f
......@@ -76,8 +76,8 @@
$.extend({el: $region, model: model}, options))
);
// Add the model to the collection. This must happen after the views have been
// associated with it, otherwise collection change event handlers can't
// Add the model to the collection. This must happen after the views have
// been associated with it, otherwise collection change event handlers can't
// trigger the model change event handler in its views.
contextual.collection.add(model);
......@@ -140,6 +140,9 @@
* - drupalContextualLinkAdded: Triggered when a contextual link is added.
*
* @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches the outline behavior to the right context.
*/
Drupal.behaviors.contextual = {
attach: function (context) {
......@@ -163,8 +166,8 @@
if (html !== null) {
// Initialize after the current execution cycle, to make the AJAX
// request for retrieving the uncached contextual links as soon as
// possible, but also to ensure that other Drupal behaviors have had the
// chance to set up an event listener on the Backbone collection
// possible, but also to ensure that other Drupal behaviors have had
// the chance to set up an event listener on the Backbone collection
// Drupal.contextual.collection.
window.setTimeout(function () {
initContextual($context.find('[data-contextual-id="' + contextualID + '"]'), html);
......@@ -174,8 +177,8 @@
return true;
});
// Perform an AJAX request to let the server render the contextual links for
// each of the placeholders.
// Perform an AJAX request to let the server render the contextual links
// for each of the placeholders.
if (uncachedIDs.length > 0) {
$.ajax({
url: Drupal.url('contextual/render'),
......@@ -186,14 +189,15 @@
_.each(results, function (html, contextualID) {
// Store the metadata.
storage.setItem('Drupal.contextual.' + contextualID, html);
// If the rendered contextual links are empty, then the current user
// does not have permission to access the associated links: don't
// render anything.
// If the rendered contextual links are empty, then the current
// user does not have permission to access the associated links:
// don't render anything.
if (html.length > 0) {
// Update the placeholders to contain its rendered contextual links.
// Usually there will only be one placeholder, but it's possible for
// multiple identical placeholders exist on the page (probably
// because the same content appears more than once).
// Update the placeholders to contain its rendered contextual
// links. Usually there will only be one placeholder, but it's
// possible for multiple identical placeholders exist on the
// page (probably because the same content appears more than
// once).
$placeholders = $context.find('[data-contextual-id="' + contextualID + '"]');
// Initialize the contextual links.
......@@ -209,6 +213,8 @@
};
/**
* Namespace for contextual related functionality.
*
* @namespace
*/
Drupal.contextual = {
......@@ -222,8 +228,8 @@
views: [],
/**
* The {@link Drupal.contextual.RegionView} instances associated with each contextual
* region element.
* The {@link Drupal.contextual.RegionView} instances associated with each
* contextual region element.
*
* @type {Array}
*/
......
......@@ -28,7 +28,7 @@
var model = contextualToolbar.model = new contextualToolbar.StateModel({
// Checks whether localStorage indicates we should start in edit mode
// rather than view mode.
// @see Drupal.contextualToolbar.VisualView.persist()
// @see Drupal.contextualToolbar.VisualView.persist
isViewing: localStorage.getItem('Drupal.contextualToolbar.isViewing') !== 'false'
}, {
contextualCollection: Drupal.contextual.collection
......@@ -47,6 +47,9 @@
* Attaches contextual's edit toolbar tab behavior.
*
* @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches contextual toolbar behavior on a contextualToolbar-init event.
*/
Drupal.behaviors.contextualToolbar = {
attach: function (context) {
......@@ -57,6 +60,8 @@
};
/**
* Namespace for the contextual toolbar.
*
* @namespace
*/
Drupal.contextualToolbar = {
......
......@@ -70,6 +70,7 @@
* If it is opened, then also give focus.
*
* @return {Drupal.contextual.StateModel}
* The current contextual state model.
*/
toggleOpen: function () {
var newIsOpen = !this.get('isOpen');
......@@ -87,6 +88,7 @@
* focus, yet be closed for example when hovering.
*
* @return {Drupal.contextual.StateModel}
* The current contextual state model.
*/
close: function () {
this.set('isOpen', false);
......@@ -99,6 +101,7 @@
* Also closes + removes focus from every other contextual link.
*
* @return {Drupal.contextual.StateModel}
* The current contextual state model.
*/
focus: function () {
this.set('hasFocus', true);
......@@ -115,6 +118,7 @@
* Removes focus from this contextual link, unless it is open.
*
* @return {Drupal.contextual.StateModel}
* The current contextual state model.
*/
blur: function () {
if (!this.get('isOpen')) {
......
......@@ -58,6 +58,7 @@
* @augments Backbone.Model
*
* @param {object} attrs
* Attributes for the backbone model.
* @param {object} options
* An object with the following option:
* @param {Backbone.collection} options.contextualCollection
......
......@@ -24,6 +24,7 @@
* @augments Backbone.View
*
* @param {object} options
* Options for the view.
*/
initialize: function (options) {
this.options = options;
......@@ -38,6 +39,7 @@
* @inheritdoc
*
* @return {Drupal.contextualToolbar.AuralView}
* The current contextual toolbar aural view.
*/
render: function () {
// Render the state.
......@@ -80,6 +82,7 @@
* Responds to esc and tab key press events.
*
* @param {jQuery.Event} event
* The keypress event.
*/
onKeypress: function (event) {
// The first tab key press is tracked so that an annoucement about tabbing
......
......@@ -10,7 +10,10 @@
Drupal.contextualToolbar.VisualView = Backbone.View.extend(/** @lends Drupal.contextualToolbar.VisualView# */{
/**
* Events for the Backbone view.
*
* @return {object}
* A mapping of events to be used in the view.
*/
events: function () {
// Prevents delay and simulated mouse events.
......@@ -45,6 +48,7 @@
* @inheritdoc
*
* @return {Drupal.contextualToolbar.VisualView}
* The current contextual toolbar visual view.
*/
render: function () {
// Render the visibility.
......
......@@ -17,6 +17,7 @@
* @augments Backbone.View
*
* @param {object} options
* Options for the view.
*/
initialize: function (options) {
this.options = options;
......
......@@ -10,7 +10,10 @@
Drupal.contextual.RegionView = Backbone.View.extend(/** @lends Drupal.contextual.RegionView# */{
/**
* Events for the Backbone view.
*
* @return {object}
* A mapping of events to be used in the view.
*/
events: function () {
var mapping = {
......@@ -41,6 +44,7 @@
* @inheritdoc
*
* @return {Drupal.contextual.RegionView}
* The current contextual region view.
*/
render: function () {
this.$el.toggleClass('focus', this.model.get('hasFocus'));
......
......@@ -10,7 +10,10 @@
Drupal.contextual.VisualView = Backbone.View.extend(/** @lends Drupal.contextual.VisualView# */{
/**
* Events for the Backbone view.
*
* @return {object}
* A mapping of events to be used in the view.
*/
events: function () {
// Prevents delay and simulated mouse events.
......@@ -46,6 +49,7 @@
* @inheritdoc
*
* @return {Drupal.contextual.VisualView}
* The current contextual visual view.
*/
render: function () {
var isOpen = this.model.get('isOpen');
......
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