[Layout] Add JSDoc to new scripts
Add in-line documentation to new scripts introduced to support the transitioned Layout view, WTD-535.
This commit is contained in:
Victor Woeltjen
@@ -5,25 +5,51 @@ define(
|
||||
function () {
|
||||
"use strict";
|
||||
|
||||
/**
|
||||
* The EditRepresenter is responsible for implementing
|
||||
* representation-level behavior relevant to Edit mode.
|
||||
* Specifically, this listens for changes to view configuration
|
||||
* or to domain object models, and triggers persistence when
|
||||
* these are detected.
|
||||
*
|
||||
* This is exposed as an extension of category `representers`,
|
||||
* which mct-representation will utilize to add additional
|
||||
* behavior to each representation.
|
||||
*
|
||||
* This will be called once per mct-representation directive,
|
||||
* and may be reused for different domain objects and/or
|
||||
* representations resulting from changes there.
|
||||
*
|
||||
* @constructor
|
||||
*/
|
||||
function EditRepresenter($q, scope) {
|
||||
var watches = [],
|
||||
domainObject,
|
||||
key;
|
||||
|
||||
// Mutate and persist a new version of a domain object's model.
|
||||
function doPersist(model) {
|
||||
// First, mutate; then, persist.
|
||||
return $q.when(domainObject.useCapability("mutation", function () {
|
||||
return model;
|
||||
})).then(function (result) {
|
||||
// Only persist when mutation was successful
|
||||
return result &&
|
||||
domainObject.getCapability("persistence").persist();
|
||||
});
|
||||
}
|
||||
|
||||
// Handle changes to model and/or view configuration
|
||||
function update() {
|
||||
// Look up from scope; these will have been populated by
|
||||
// mct-representation.
|
||||
var model = scope.model,
|
||||
configuration = scope.configuration;
|
||||
|
||||
// Update the configuration stored in the model, and persist.
|
||||
if (domainObject && domainObject.hasCapability("persistence")) {
|
||||
// Configurations for specific views are stored by
|
||||
// key in the "configuration" field of the model.
|
||||
if (key && configuration) {
|
||||
model.configuration = model.configuration || {};
|
||||
model.configuration[key] = configuration;
|
||||
@@ -32,18 +58,26 @@ define(
|
||||
}
|
||||
}
|
||||
|
||||
// Respond to the destruction of the current representation.
|
||||
function destroy() {
|
||||
// Stop watching for changes
|
||||
watches.forEach(function (deregister) { deregister(); });
|
||||
watches = [];
|
||||
}
|
||||
|
||||
// Handle a specific representation of a specific domain object
|
||||
function represent(representation, representedObject) {
|
||||
// Track the key, to know which view configuration to save to.
|
||||
key = representation.key;
|
||||
// Track the represented object
|
||||
domainObject = representedObject;
|
||||
|
||||
destroy(); // Ensure existing watches are released
|
||||
// Ensure existing watches are released
|
||||
destroy();
|
||||
|
||||
// Watch for changes to model or configuration; keep the
|
||||
// results, as $watch returns an de-registration function.
|
||||
// Use the "editor" capability to check if we are in Edit mode.
|
||||
watches = representedObject.hasCapability("editor") ? [
|
||||
scope.$watch("model", update, true),
|
||||
scope.$watch("configuration", update, true)
|
||||
@@ -51,7 +85,19 @@ define(
|
||||
}
|
||||
|
||||
return {
|
||||
/**
|
||||
* Set the current representation in use, and the domain
|
||||
* object being represented.
|
||||
*
|
||||
* @param {RepresentationDefinition} representation the
|
||||
* definition of the representation in use
|
||||
* @param {DomainObject} domainObject the domain object
|
||||
* being represented
|
||||
*/
|
||||
represent: represent,
|
||||
/**
|
||||
* Release any resources associated with this representer.
|
||||
*/
|
||||
destroy: destroy
|
||||
};
|
||||
}
|
||||
|
||||
@@ -5,29 +5,65 @@ define(
|
||||
function () {
|
||||
"use strict";
|
||||
|
||||
/**
|
||||
* The mct-drag directive allows drag functionality
|
||||
* (in the mousedown-mousemove-mouseup sense, as opposed to
|
||||
* the drag-and-drop sense) to be attached to specific
|
||||
* elements. This takes the form of three attributes:
|
||||
*
|
||||
* * `mct-drag`: An Angular expression to evaluate during
|
||||
* drag movement.
|
||||
* * `mct-drag-down`: An Angular expression to evaluate
|
||||
* when the drag begins.
|
||||
* * `mct-drag-up`: An Angular expression to evaluate when
|
||||
* dragging ends.
|
||||
*
|
||||
* In each case, a variable `delta` will be provided to the
|
||||
* expression; this is a two-element array or the horizontal
|
||||
* and vertical pixel offset of the current mouse position
|
||||
* relative to the mouse position where dragging began.
|
||||
*
|
||||
* @constructor
|
||||
*
|
||||
*/
|
||||
function MCTDrag($document) {
|
||||
|
||||
// Link; install event handlers.
|
||||
function link(scope, element, attrs) {
|
||||
// Keep a reference to the body, to attach/detach
|
||||
// mouse event handlers; mousedown and mouseup cannot
|
||||
// only be attached to the element being linked, as the
|
||||
// mouse may leave this element during the drag.
|
||||
var body = $document.find('body'),
|
||||
initialPosition,
|
||||
currentPosition,
|
||||
delta;
|
||||
|
||||
// Utility function to cause evaluation of mctDrag,
|
||||
// mctDragUp, etc
|
||||
function fireListener(name) {
|
||||
// Evaluate the expression, with current delta
|
||||
scope.$eval(attrs[name], { delta: delta });
|
||||
|
||||
// Trigger prompt digestion
|
||||
scope.$apply();
|
||||
}
|
||||
|
||||
// Update positions (both actual and relative)
|
||||
// based on a new mouse event object.
|
||||
function updatePosition(event) {
|
||||
currentPosition = [ event.pageX, event.pageY ];
|
||||
// Get the current position, as an array
|
||||
var currentPosition = [ event.pageX, event.pageY ];
|
||||
|
||||
// Track the initial position, if one hasn't been observed
|
||||
initialPosition = initialPosition || currentPosition;
|
||||
|
||||
// Compute relative position
|
||||
delta = currentPosition.map(function (v, i) {
|
||||
return v - initialPosition[i];
|
||||
});
|
||||
}
|
||||
|
||||
// Called during a drag, on mousemove
|
||||
function continueDrag(event) {
|
||||
updatePosition(event);
|
||||
fireListener("mctDrag");
|
||||
@@ -37,10 +73,14 @@ define(
|
||||
return false;
|
||||
}
|
||||
|
||||
// Called only when the drag ends (on mouseup)
|
||||
function endDrag(event) {
|
||||
// Detach event handlers
|
||||
body.off("mouseup", endDrag);
|
||||
body.off("mousemove", continueDrag);
|
||||
|
||||
// Also call continueDrag, to fire mctDrag
|
||||
// and do its usual position update
|
||||
continueDrag(event);
|
||||
|
||||
fireListener("mctDragUp");
|
||||
@@ -53,12 +93,18 @@ define(
|
||||
return false;
|
||||
}
|
||||
|
||||
// Called on mousedown on the element
|
||||
function startDrag(event) {
|
||||
// Listen for mouse events at the body level,
|
||||
// since the mouse may leave the element during
|
||||
// the drag.
|
||||
body.on("mouseup", endDrag);
|
||||
body.on("mousemove", continueDrag);
|
||||
|
||||
// Set an initial position
|
||||
updatePosition(event);
|
||||
|
||||
// Fire listeners, including mctDrag
|
||||
fireListener("mctDragDown");
|
||||
fireListener("mctDrag");
|
||||
|
||||
@@ -67,11 +113,14 @@ define(
|
||||
return false;
|
||||
}
|
||||
|
||||
// Listen for mousedown on the element
|
||||
element.on("mousedown", startDrag);
|
||||
}
|
||||
|
||||
return {
|
||||
// mct-drag only makes sense as an attribute
|
||||
restrict: "A",
|
||||
// Link function, to install event handlers
|
||||
link: link
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user