From 078d63de364161682581ecae20afe3bb47f4cb6b Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Sun, 23 Nov 2014 18:03:48 -0800 Subject: [PATCH] [Common UI] Add JSDoc Add JSDoc to classes from commonUI bundles. WTD-574. --- .../commonUI/browse/src/BrowseController.js | 34 +++++++++++++++-- .../browse/src/creation/CreateAction.js | 38 ++++++++++++++++++- .../src/creation/CreateActionProvider.js | 22 +++++++++++ 3 files changed, 89 insertions(+), 5 deletions(-) diff --git a/platform/commonUI/browse/src/BrowseController.js b/platform/commonUI/browse/src/BrowseController.js index 53a16f7f31..d96089d1d8 100644 --- a/platform/commonUI/browse/src/BrowseController.js +++ b/platform/commonUI/browse/src/BrowseController.js @@ -11,37 +11,63 @@ define( var ROOT_OBJECT = "ROOT"; /** + * The BrowseController is used to populate the initial scope in Browse + * mode. It loads the root object from the objectService and makes it + * available in the scope for Angular template's; this is the point at + * which Angular templates first have access to the domain object + * hierarchy. * * @constructor */ function BrowseController($scope, objectService, navigationService) { + // Callback for updating the in-scope reference to the object + // that is currently navigated-to. function setNavigation(domainObject) { $scope.navigatedObject = domainObject; - //$scope.$apply("navigatedObject"); } + // Load the root object, put it in the scope. + // Also, load its immediate children, and (possibly) + // navigate to one of them, so that navigation state has + // a useful initial value. objectService.getObjects([ROOT_OBJECT]).then(function (objects) { var composition = objects[ROOT_OBJECT].useCapability("composition"); $scope.domainObject = objects[ROOT_OBJECT]; if (composition) { composition.then(function (c) { - // Navigate to the last root level component (usually "mine") + // Check if an object has been navigated-to already... if (!navigationService.getNavigation()) { + // If not, pick a default as the last + // root-level component (usually "mine") navigationService.setNavigation(c[c.length - 1]); } else { + // Otherwise, just expose it in the scope $scope.navigatedObject = navigationService.getNavigation(); } }); } }); + // Listen for changes in navigation state. + navigationService.addListener(setNavigation); + + // Clean up when the scope is destroyed $scope.$on("$destroy", function () { navigationService.removeListener(setNavigation); }); - navigationService.addListener(setNavigation); - return { + /** + * Navigate to a specific domain object. + * + * This is exposed so that the browse tree has a callback + * to invoke when the user clicks on a new object to navigate + * to it. + * + * @method + * @memberof BrowseController + * @param {DomainObject} domainObject the object to navigate to + */ setNavigation: function (domainObject) { navigationService.setNavigation(domainObject); } diff --git a/platform/commonUI/browse/src/creation/CreateAction.js b/platform/commonUI/browse/src/creation/CreateAction.js index 6b01d2bfce..d500673e41 100644 --- a/platform/commonUI/browse/src/creation/CreateAction.js +++ b/platform/commonUI/browse/src/creation/CreateAction.js @@ -9,11 +9,27 @@ define( "use strict"; /** + * The Create Action is performed to create new instances of + * domain objects of a specific type. This is the action that + * is performed when a user uses the Create menu. * * @constructor + * @param {Type} type the type of domain object to create + * @param {DomainObject} parent the domain object that should + * act as a container for the newly-created object + * (note that the user will have an opportunity to + * override this) + * @param {ActionContext} context the context in which the + * action is being performed + * @param {DialogService} dialogService the dialog service + * to use when requesting user input + * @param {CreationService} creationService the creation service, + * which handles the actual instantiation and persistence + * of the newly-created domain object */ function CreateAction(type, parent, context, dialogService, creationService) { /* + Overview of steps in object creation: 1. Show dialog a. Prepare dialog contents @@ -26,12 +42,15 @@ define( b. Add new id to composition 4. Persist destination container a. ...use persistence capability. - */ function perform() { + // The wizard will handle creating the form model based + // on the type... var wizard = new CreateWizard(type, parent); + // Create and persist the new object, based on user + // input. function persistResult(formValue) { var parent = wizard.getLocation(formValue), newModel = wizard.createModel(formValue); @@ -49,7 +68,24 @@ define( } return { + /** + * Create a new object of the given type. + * This will prompt for user input first. + * @method + * @memberof CreateAction + */ perform: perform, + + /** + * Get metadata about this action. This includes fields: + * * `name`: Human-readable name + * * `key`: Machine-readable identifier ("create") + * * `glyph`: Glyph to use as an icon for this action + * * `description`: Human-readable description + * * `context`: The context in which this action will be performed. + * + * @return {object} metadata about the create action + */ getMetadata: function () { return { key: 'create', diff --git a/platform/commonUI/browse/src/creation/CreateActionProvider.js b/platform/commonUI/browse/src/creation/CreateActionProvider.js index ae91aa43b6..9d203dd5f1 100644 --- a/platform/commonUI/browse/src/creation/CreateActionProvider.js +++ b/platform/commonUI/browse/src/creation/CreateActionProvider.js @@ -9,20 +9,42 @@ define( "use strict"; /** + * The CreateActionProvider is an ActionProvider which introduces + * a Create action for each creatable domain object type. * * @constructor + * @param {TypeService} typeService the type service, used to discover + * available types + * @param {DialogService} dialogService the dialog service, used by + * specific Create actions to get user input to populate the + * model of the newly-created domain object. + * @param {CreationService} creationService the creation service (also + * introduced in this bundle), responsible for handling actual + * object creation. */ function CreateActionProvider(typeService, dialogService, creationService) { return { + /** + * Get all Create actions which are applicable in the provided + * context. + * @memberof CreateActionProvider + * @method + * @returns {CreateAction[]} + */ getActions: function (actionContext) { var context = actionContext || {}, key = context.key, destination = context.domainObject; + // We only provide Create actions, and we need a + // domain object to serve as the container for the + // newly-created object (although the user may later + // make a different selection) if (key !== 'create' || !destination) { return []; } + // Introduce one create action per type return typeService.listTypes().map(function (type) { return new CreateAction( type,