Updates to documentation and fixes for JSHint warnings

controllers/base_controller.js

@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2015  PencilBlue, LLC
+    Copyright (C) 2016  PencilBlue, LLC
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -14,6 +14,7 @@
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
+'use strict';
 
 //dependencies
 var url  = require('url');
@@ -110,21 +111,88 @@ module.exports = function BaseControllerModule(pb) {
      */
     BaseController.prototype.init = function(props, cb) {
         var self = this;
-        this.reqHandler          = props.request_handler;
-        this.req                 = props.request;
-        this.res                 = props.response;
-        this.session             = props.session;
-        this.body                = props.body;
+
+        /**
+         * The instance of the request handler that processed the request
+         * @property reqHandler
+         * @type {RequestHandler}
+         */
+        this.reqHandler = props.request_handler;
+
+        /**
+         * The current request object
+         * @property req
+         * @type {Request}
+         */
+        this.req = props.request;
+
+        /**
+         * The current response object
+         * @property res
+         * @type {Response}
+         */
+        this.res = props.response;
+
+        /**
+         * The session object that represents the calling entity
+         * @property session
+         * @type {object}
+         */
+        this.session = props.session;
+
+        /**
+         * The deserialized body of the request.  This field is only ever populted if the executing route specifies the
+         * "request_body" attribute and provides valid MIME types that map to a registered body parser
+         * @property body
+         * @type {object|null}
+         */
+        this.body = props.body;
+
+        /**
+         * @deprecated Use this.ls
+         * @property localizationService
+         * @type {Localization}
+         */
         this.localizationService = props.localization_service;
-        this.ls                  = this.localizationService;
-        this.pathVars            = props.pathVars;
-        this.query               = props.query;
+
+        /**
+         * @property ls
+         * @type {Localization}
+         */
+        this.ls = props.localization_service;
+
+        /**
+         * The hash of key/value pairs that represent the variables passed in the route path
+         * @property pathVars
+         * @type {object}
+         */
+        this.pathVars = props.pathVars;
+
+        /**
+         * The hash of key/value pairs that represent the variables passed as query string parameters
+         * @property query
+         * @type {object}
+         */
+        this.query = props.query;
+
+        /**
+         * The title of the view to be rendered, if there is a view
+         * @property pageName
+         * @type {string}
+         */
         this.pageName            = '';
         this.siteObj             = props.siteObj;
         this.site                = props.site;
         this.siteName            = props.siteName;
         this.hostname            = SiteService.getHostWithProtocol(self.siteObj.hostname) || pb.config.siteRoot;
-        this.referer             = this.req.headers.referer;
+
+        /**
+         * The referring URL
+         * @deprecated
+         * @property referer
+         * @type {string}
+         */
+        this.referer = this.req.headers.referer;
 
         /**
          * @property ts
@@ -140,6 +208,10 @@ module.exports = function BaseControllerModule(pb) {
 
         //build out a base service context that can be cloned and passed to any
         //service objects
+        /**
+         * @property context
+         * @type {{req: Request, session: object, ls: Localization, ts: TemplateService, site: string, hostname: string, activeTheme: string, onlyThisSite: boolean, siteObj: object}}
+         */
         this.context = {
             req: this.req,
             session: this.session,
@@ -177,7 +249,7 @@ module.exports = function BaseControllerModule(pb) {
 
         //create options
         var tsOpts = {
-            ls: this.localizationService,
+            ls: this.ls,
             activeTheme: props.activeTheme,
             site: this.site
         };
@@ -323,12 +395,12 @@ module.exports = function BaseControllerModule(pb) {
         if(this.session.error) {
             var error = this.session.error;
             delete this.session.error;
-            cb(null, new pb.TemplateValue(util.format(ALERT_PATTERN, 'alert-danger', this.localizationService.get(error)), false));
+            cb(null, new pb.TemplateValue(util.format(ALERT_PATTERN, 'alert-danger', this.ls.get(error)), false));
         }
         else if(this.session.success) {
             var success = this.session.success;
             delete this.session.success;
-            cb(null, new pb.TemplateValue(util.format(ALERT_PATTERN, 'alert-success', this.localizationService.get(success)), false));
+            cb(null, new pb.TemplateValue(util.format(ALERT_PATTERN, 'alert-success', this.ls.get(success)), false));
         }
         else {
             cb(null, '');
@@ -456,16 +528,16 @@ module.exports = function BaseControllerModule(pb) {
         for (var i = 0; i < requiredParameters.length; i++) {
 
             if (typeof queryObject[requiredParameters[i]] === 'undefined') {
-                return this.localizationService.get('FORM_INCOMPLETE');
+                return this.ls.get('FORM_INCOMPLETE');
             }
             else if (queryObject[requiredParameters[i]].length === 0) {
-                return this.localizationService.get('FORM_INCOMPLETE');
+                return this.ls.get('FORM_INCOMPLETE');
             }
         }
 
         if(queryObject.password && queryObject.confirm_password) {
             if(queryObject.password !== queryObject.confirm_password) {
-                return this.localizationService.get('PASSWORD_MISMATCH');
+                return this.ls.get('PASSWORD_MISMATCH');
             }
         }
 
@@ -516,13 +588,13 @@ module.exports = function BaseControllerModule(pb) {
         }
 
         var rules = this.getSanitizationRules();
-        for(var prop in obj) {
+        Object.keys(obj).forEach(function(prop) {
             if (util.isString(obj[prop])) {
 
                 var config = rules[prop];
-                obj[prop] = BaseController.sanitize(obj[prop], config);
+                obj[prop] = pb.BaseObjectService.sanitize(obj[prop], config);
             }
-        }
+        });
     };
 
     /**
@@ -584,10 +656,10 @@ module.exports = function BaseControllerModule(pb) {
     BaseController.apiResponse = function(cd, msg, dta) {
         if(typeof msg === 'undefined') {
             switch(cd) {
-                case BaseController.FAILURE:
+                case BaseController.API_FAILURE:
                     msg = 'FAILURE';
                     break;
-                case BaseController.SUCCESS:
+                case BaseController.API_SUCCESS:
                     msg = 'SUCCESS';
                     break;
                 default:

include/client_js.js

@@ -14,6 +14,7 @@
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
+'use strict';
 
 //dependencies
 var util = require('./util.js');
@@ -35,7 +36,7 @@ module.exports = function ClientJsModule(pb) {
      * @method getAngularController
      * @param {Object} objects     Object to be passed into AngularJS scope
      * @param {Array}  modules     Array of AngularJS module names
-     * @param {String} directiveJS JavaScript to run after on-finish-render directive
+     * @param {String} [directiveJS] JavaScript to run after on-finish-render directive
      */
     ClientJs.getAngularController = function(objects, modules, directiveJS) {
         if(!util.isArray(modules) || modules.length === 0) {
@@ -62,16 +63,16 @@ module.exports = function ClientJsModule(pb) {
      */
     ClientJs.getAngularObjects = function(objects) {
         var scopeString = '';
-        for(var key in objects) {
-            if(util.isString(objects[key]) && objects[key].indexOf('function(') == 0) {
+        Object.keys(objects).forEach(function(key) {
+            if(util.isString(objects[key]) && objects[key].indexOf('function(') === 0) {
                 scopeString = scopeString.concat('$scope.' + key + ' = ' + objects[key] + ";\n");
-                continue;
+                return;
             }
             scopeString = scopeString.concat('$scope.' + key + '=' + JSON.stringify(objects[key], null, pb.log.isSilly() ? ' ' : undefined) + ";\n");
-        }
+        });
 
         return scopeString;
-    }
+    };
 
     /**
      * Creates a JS tag that loads the specified url

include/http/request_handler.js

@@ -348,7 +348,7 @@ module.exports = function RequestHandlerModule(pb) {
             descriptor.method = descriptor.method.toUpperCase();
         }
         else {
-            descriptor.method = 'ALL'
+            descriptor.method = 'ALL';
         }
 
         //make sure we get a valid prototype back
@@ -669,7 +669,7 @@ module.exports = function RequestHandlerModule(pb) {
      */
     RequestHandler.isPublicRoute = function(path){
         for (var i = 0; i < PUBLIC_ROUTE_PREFIXES.length; i++) {
-            if (path.indexOf(PUBLIC_ROUTE_PREFIXES[i]) == 0) {
+            if (path.indexOf(PUBLIC_ROUTE_PREFIXES[i]) === 0) {
                 return true;
             }
         }

include/service/entities/content/page_service.js

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
+'use strict';
 
 //dependencies
 var util  = require('../../../util.js');
@@ -33,6 +34,9 @@ module.exports = function(pb) {
      * @extends BaseObjectService
      * @constructor
      * @param {object} context
+     * @param {object} [context.contentSettings]
+     * @param {string} context.site
+     * @param {boolean} context.onlyThisSite
      */
     function PageService(context){
         if (!util.isObject(context)) {
@@ -96,10 +100,11 @@ module.exports = function(pb) {
     /**
      *
      * @static
-     * @method
+     * @method format
      * @param {Object} context
      * @param {PageService} context.service An instance of the service that triggered
      * the event that called this handler
+     * @param {object} context.data
      * @param {Function} cb A callback that takes a single parameter: an error if occurred
      */
     PageService.format = function(context, cb) {
@@ -125,10 +130,11 @@ module.exports = function(pb) {
     /**
      *
      * @static
-     * @method
+     * @method merge
      * @param {Object} context
-     * @param {PageService} service An instance of the service that triggered
+     * @param {PageService} context.service An instance of the service that triggered
      * the event that called this handler
+     * @param {object} context.data
      * @param {Function} cb A callback that takes a single parameter: an error if occurred
      */
     PageService.merge = function(context, cb) {
@@ -161,6 +167,7 @@ module.exports = function(pb) {
      * @method validate
      * @param {Object} context
      * @param {Object} context.data The DTO that was provided for persistence
+     * @param {Array} context.data.page_topics
      * @param {PageService} context.service An instance of the service that triggered
      * the event that called this handler
      * @param {Function} cb A callback that takes a single parameter: an error if occurred
@@ -267,6 +274,7 @@ module.exports = function(pb) {
      * @static
      * @method setSectionClause
      * @param {Object} where
+     * @param {string} sectionId
      */
     PageService.setSectionClause = function(where, sectionId) {
         where.article_sections = sectionId + '';
@@ -277,6 +285,7 @@ module.exports = function(pb) {
      * @static
      * @method setTopicClause
      * @param {Object} where
+     * @param {string} topicId
      */
     PageService.setTopicClause = function(where, topicId) {
         where.page_topics = topicId + '';

include/service/entities/plugin_service.js

@@ -1078,7 +1078,7 @@ module.exports = function PluginServiceModule(pb) {
      */
     PluginService.prototype.initPlugin = function(plugin, cb) {
         if (typeof plugin !== 'object') {
-            return cb(new Error('PluginService:[INIT] The plugin object must be passed in order to initilize the plugin'), null);
+            return cb(new Error('PluginService:[INIT] The plugin object must be passed in order to initialize the plugin'), null);
         }
 
         pb.log.debug("PluginService:[INIT] Beginning initialization of %s (%s)", plugin.name, plugin.uid);

include/theme/top_menu.js

@@ -245,9 +245,9 @@ module.exports = function TopMenuServiceModule(pb) {
      * @method getNavItems
      * @param {Object} options
      * @param {Localization} options.ls
-     * @param {String} options.activeTheme
      * @param {Object} options.session
      * @param {String} options.currUrl
+     * @param {string} options.site
      * @param {Function} cb
      */
     TopMenuService.prototype.getNavItems = function(options, cb) {

plugins/pencilblue/include/routes.js

@@ -642,7 +642,7 @@ module.exports = function Routes(pb){
             auth_required: true,
             inactive_site_access: true,
             controller: path.join(pb.config.docRoot, 'plugins', 'pencilblue', 'controllers', 'api', 'admin', 'content', 'media', 'upload_media.js'),
-            content_type: 'text/html'
+            content_type: 'application/json'
         },
         {
             method: 'get',