Cleaned up layout/partial shim in preparation; refs #3707

lib/hooks/views/layoutshim.js → lib/hooks/views/add-shim-for-layout-and-partials.js

@@ -6,21 +6,26 @@ var path = require('path');
 
 
 /**
- * Implement EJS layouts (a la Express 2)
+ * Implement EJS layouts and partials (a la Express 2).
+ *
+ * For further explanation, see:
+ *  => http://sailsjs.org/documentation/concepts/views/layouts#?why-do-layouts-only-work-for-ejs
+ * ------------------------------------------------------------------------------------------
  *
  * TODO:
  * Extrapolate this functionality to a separate hook
  * to make it easier for folks to extend it with support
- * for other view engines (e.g. hbs)
+ * for other view engines (e.g. hbs).
+ *   => See https://github.com/balderdashy/sails/issues/3707 for more info.
  *
  * @param  {Sails}   sails
  */
-module.exports = function layoutshim (sails) {
+module.exports = function addShimForLayoutAndPartials (sails) {
 
-  // If layout config is set, attempt to use view partials/layout
+  // If layout config is truthy, attempt to use view partials/layout.
   if (sails.config.views.layout) {
 
-    // If `http` hook is not enabled, we can't use partials
+    // If `http` hook is not enabled, we can't use partials.
     // (depends on express atm)
     if (sails.config.hooks.http) {
 
@@ -35,9 +40,14 @@ module.exports = function layoutshim (sails) {
         var ejsLayoutEngine = require('ejs-locals');
         sails.log.verbose('Overriding ejs engine config with ejslocals to implement layout support...');
         sails.config.views.engine.fn = ejsLayoutEngine;
-      }
+      }//</ejs>
 
-      // Use express-handlebars for handlebars templates, and set up layout functionality
+      // Use express-handlebars for handlebars templates, and set up layout functionality.
+      //
+      // > **WARNING**
+      // > Handlebars layout/partial support is EXPERIMENTAL and may be removed at any time.
+      // > It also might stay-- if you would like to see that, please create a proposal in the Sails
+      // > repo on GitHub explaining how you see usage working long-term.  Thanks!
       else if (engineName === 'handlebars') {
         var exphbs = require('express-handlebars');
         sails.log.verbose('Overriding handlebars engine with express-handlebars to implement layout support...');
@@ -49,7 +59,8 @@ module.exports = function layoutshim (sails) {
         });
 
         sails.config.views.engine.fn = hbs.engine;
-      }
-    }
-  }
+      }//</handlebars>
+
+    }//</HTTP hook enabled>
+  }//</sails.config.views.layout is truthy>
 };

lib/hooks/views/index.js

@@ -5,7 +5,7 @@
 var configure = require('./configure');
 var defaults = require('./defaults');
 var onRoute = require('./onRoute');
-var addLayoutShim = require('./layoutshim');
+var addShimForLayoutAndPartials = require('./add-shim-for-layout-and-partials');
 var addResViewMethod = require('./res.view');
 var render = require('./render');
 var statViews = require('./stat-views');
@@ -73,7 +73,7 @@ module.exports = function (sails) {
 
       // Declare hook loaded when ejs layouts have been applied,
       // views have been inventoried, and view-serving middleware has been prepared
-      addLayoutShim(sails);
+      addShimForLayoutAndPartials(sails);
 
       // Expose `sails.renderView()` function to userland.
       // (experimental!)