Skip to content

Commit

Permalink
Documentation for JSDoc and cleanup of file
Browse files Browse the repository at this point in the history
  • Loading branch information
@SirUli
SirUli committed Jul 20, 2012
1 parent 3a95b7a commit bcda203
Showing 1 changed file with 147 additions and 43 deletions.
190 changes: 147 additions & 43 deletions lib/helpers.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ exts = {
paths = {
'css': '/stylesheets/',
'js' : '/javascripts/'
},
merged = {
stylesheets: {ext: exts.css},
javascripts: {ext: exts.js}
};

/**
Expand All @@ -37,11 +41,17 @@ module.exports.HelperSet = HelperSet;

/**
* Set of helper methods
*
* @namespace
* @param {Object} ctl Controller object
*/
function HelperSet(ctl) {
var controller = ctl;
this.controller = ctl;

/**
* CSRF Meta Tag generation
*/
this.csrf_meta_tag = function () {
return controller && controller.protectedFromForgery() ? [
'<meta name="csrf-param" content="' + controller.request.csrfParam + '"/>',
Expand All @@ -54,6 +64,8 @@ function HelperSet(ctl) {

/**
* Make helpers local to query
*
* @param {Object} controller Controller Object
* @returns Object containing all helpers
*/
module.exports.personalize = function (controller) {
Expand All @@ -63,10 +75,14 @@ module.exports.personalize = function (controller) {
/**
* Return bunch of stylesheets link tags
*
* Examlple:
*
* <link href="/stylesheets/all.css" media="screen" rel="stylesheet" type="text/css" />
*
* @param {String} stylesheet filename
* @returns {String} HTML code to the stylesheets in the parameters
* @example
* <strong>In ejs:</strong>
* <code>&lt;%- stylesheet_link_tag('bootstrap', 'style') %&gt;</code>
* <strong>Returns:</strong>
* <code>&lt;link media="screen" rel="stylesheet" type="text/css" href="/css/bootstrap.css" /&gt;
* &lt;link media="screen" rel="stylesheet" type="text/css" href="/css/style.css" /&gt;</code>
*/
HelperSet.prototype.stylesheetLinkTag = function stylesheetLinkTag() {
if (!paths.css || !paths.stylesheets) {
Expand All @@ -92,15 +108,14 @@ HelperSet.prototype.stylesheet_link_tag = HelperSet.prototype.stylesheetLinkTag;

/**
* Generates set of javascript includes composed from arguments
* @param String script filename
* @param {String} script filename
* @returns {String} the generated &lt;script&gt; tags
* @example
*
* <%- javascript_include_tag('rails', 'application') %>
*
* generates
*
* <script type="text/javascript" src="/javascripts/rails.js"></script>
* <script type="text/javascript" src="/javascripts/application.js"></script>
* <strong>In ejs:</strong>
* <code>&lt;%- javascript_include_tag('rails', 'application') %&gt;</code>
* <strong>Returns:</strong>
* <code>&lt;script type="text/javascript" src="/javascripts/rails.js"&gt;&lt;/script&gt;
* &lt;script type="text/javascript" src="/javascripts/application.js"&gt;&lt;/script&gt;</code>
*/
HelperSet.prototype.javascriptIncludeTag = function javascriptIncludeTag() {
if (!paths.js || !paths.javascripts) {
Expand All @@ -123,17 +138,17 @@ HelperSet.prototype.javascriptIncludeTag = function javascriptIncludeTag() {
};
HelperSet.prototype.javascript_include_tag = HelperSet.prototype.javascriptIncludeTag;

var merged = {
stylesheets: {ext: exts.css},
javascripts: {ext: exts.js}
};

/**
* Merge files when caching enabled
*
* - app.set('merge javascripts')
* - app.set('merge stylesheets')
* TN: fixed https://github.com/1602/express-on-railway/issues/152
* @param {String} scope Scope which is merged, e.g. javascripts or stylesheets
* @param {Array} files Array of files which should be merged
* @example
* You can enable merging manually with the following configuration:
* - <code>app.set('merge javascripts')</code>
* - <code>app.set('merge stylesheets')</code>
* @see <a href="https://github.com/1602/express-on-railway/issues/152">#152</a>
* @returns {String} Pathname to the merged file
*/
function mergeFiles(scope, files) {
// ensure that feature is enabled
Expand Down Expand Up @@ -210,11 +225,15 @@ function mergeFiles(scope, files) {
/**
* Link helper
*
* @param {String} text
* @param {String} url
* @param {Object} params - set of html params (class, style, etc..)
*
* <a href="url">text</a>
* @param {String} text Text of the link
* @param {String} url Url where the link points to
* @param {Object} params Set of html params (class, style, etc..)
* @example
* <strong>In ejs:</strong>
* <code>&lt;%- link_to("Home", '/') %&gt;</code>
* <strong>Returns:</strong>
* <code>&lt;a href="/"&gt;Home&lt;/a&gt;</code>
* @returns {String} Generated html for link
*/
HelperSet.prototype.linkTo = function linkTo(text, url, params) {
['remote', 'method', 'jsonp', 'confirm'].forEach(dataParam.bind(params));
Expand All @@ -224,6 +243,10 @@ HelperSet.prototype.link_to = HelperSet.prototype.linkTo;

/**
* Form tag helper
*
* @methodOf HelperSet.prototype
* @param {Object} params
* @param {Function} block
*/
HelperSet.prototype.formTag = function (params, block) {
var self = this;
Expand Down Expand Up @@ -264,13 +287,22 @@ HelperSet.prototype.formTag = function (params, block) {
if (_method !== params.method) {
buf.push(HelperSet.prototype.input_tag({type: "hidden", name: "_method", value: _method }));
}

// function?
if (typeof block === 'function') {
block();
}
buf.push('</form>');
};
HelperSet.prototype.form_tag = HelperSet.prototype.formTag;

/**
* Prints error messages for the model instance
*
* @methodOf HelperSet.prototype
* @param {ModelInstance} resource
* @returns {String} Error messages from the model instance
*/
HelperSet.prototype.errorMessagesFor = function errorMessagesFor(resource) {
var out = '';
var h = this;
Expand Down Expand Up @@ -300,6 +332,11 @@ HelperSet.prototype.errorMessagesFor = function errorMessagesFor(resource) {

/**
* Form fields for resource helper
*
* @methodOf HelperSet.prototype
* @param {ModelInstance} resource
* @param {Function} block
* @namespace
*/
HelperSet.prototype.fields_for = function (resource, block) {
arguments.callee.buf = arguments.callee.caller.buf;
Expand All @@ -308,10 +345,24 @@ HelperSet.prototype.fields_for = function (resource, block) {
var resourceName = resource && resource.constructor && resource.constructor.modelName || false;
var complexNames = (app.set('view options') || {}).complexNames;

/**
* Generates a name
*
* @param {String} name Name of the element
* @requires resourceName
* @returns {String} returns the generated name
*/
function makeName(name) {
return complexNames && resourceName ? (resourceName + '[' + name + ']') : name;
}

/**
* Generates an id field
*
* @param {String} name Name of the element
* @requires resourceName
* @returns {String} returns the generated id name
*/
function makeId(name) {
return complexNames && resourceName ? (resourceName + '_' + name) : name;
}
Expand Down Expand Up @@ -427,6 +478,7 @@ HelperSet.prototype.fields_for = function (resource, block) {
/**
* Form for resource helper
*
* @methodOf HelperSet.prototype
* @param {ModelInstance} resource
* @param {Object} params
* @param {Function} block
Expand Down Expand Up @@ -457,7 +509,16 @@ HelperSet.prototype.form_for = HelperSet.prototype.formFor;
/**
* Input tag helper
*
* <input type="text" ... />
* @methodOf HelperSet.prototype
* @param {String} text - inner html
* @param {Object} params - set of tag attributes
* @param {Object} override - set params to override params in previous arg
* @returns {String} Finalized input tag
* @example
* <strong>In ejs:</strong>
* <code>&lt;%- form.input("test") %&gt;</code>
* <strong>Returns:</strong>
* <code>&lt;input name="test"/&gt;</code>
*/
HelperSet.prototype.input_tag = function (params, override) {
return '<input' + htmlTagParams(params, override) + ' />';
Expand All @@ -466,14 +527,26 @@ HelperSet.prototype.input_tag = function (params, override) {
/**
* Label tag helper
*
* <label>text</label>
* @methodOf HelperSet.prototype
* @param {String} text - inner html
* @param {Object} params - set of tag attributes
* @param {Object} override - set params to override params in previous arg
* @returns {String} Finalized label tag
* @example
* <strong>In ejs:</strong>
* <code>&lt;%- form.label("test", false, {class: "control-label"}) %&gt;</code>
* <strong>Returns:</strong>
* <code>&lt;label for="test" class="control-label"&gt;Test&lt;/label&gt;</code>
*/
HelperSet.prototype.label_tag = function (text, params, override) {
return genericTag('label', text, params, override);
};

/**
* Cross-site request forgery hidden inputs
*
* @methodOf HelperSet.prototype
* @returns {String} CSRF-Tag with parameters
*/
HelperSet.prototype.csrf_tag = function() {
return '<input type="hidden" name="' + this.controller.request.csrfParam + '" value="' + this.controller.request.csrfToken + '" />';
Expand All @@ -482,7 +555,12 @@ HelperSet.prototype.csrf_tag = function() {
/**
* Select tag helper
*
* <select>innerOptions</select>
* @methodOf HelperSet.prototype
* @author <a href="https://github.com/SirUli">Uli Wolf</a>
* @param {String} innerOptions Inner html of the select tag
* @param {Object} params Set of tag attributes
* @param {Object} override Set params to override params in previous arg
* @returns {String} Finalized select tag
*/
HelperSet.prototype.select_tag = function (innerOptions, params, override) {
return genericTag('select', innerOptions, params, override);
Expand All @@ -492,24 +570,30 @@ HelperSet.prototype.select_tag = function (innerOptions, params, override) {
* Option tag helper
*
* <option>text</option>
*
* @methodOf HelperSet.prototype
* @author <a href="https://github.com/SirUli">Uli Wolf</a>
* @param {String} text Inner html
* @param {Object} params Set of tag attributes
* @param {Object} override Set params to override params in previous arg
* @returns {String} Finalized option tag
*/
HelperSet.prototype.option_tag = function (text, params, override) {
return genericTag('option', text, params, override);
};

HelperSet.prototype.sanitize = sanitizeHTML;

/**
* Private util methods
*/

/**
* Returns html code of one tag with contents
*
* @param String name - name of tag
* @param String inner - inner html
* @param Object params - set of tag attributes
* @param Object override - set params to override params in previous arg
* @param {String} name name of tag
* @param {String} inner inner html
* @param {Object} params set of tag attributes
* @param {Object} override set params to override params in previous arg
* @returns {String} Finalized generic tag
*/
function genericTag(name, inner, params, override) {
return '<' + name + htmlTagParams(params, override) + '>' + inner + '</' + name + '>';
Expand All @@ -518,9 +602,10 @@ function genericTag(name, inner, params, override) {
/**
* Returns html code of a selfclosing tag
*
* @param String name - name of tag
* @param Object params - set of tag attributes
* @param Object override - set params to override params in previous arg
* @param {String} name name of tag
* @param {Object} params set of tag attributes
* @param {Object} override set params to override params in previous arg
* @returns {String} Finalized generic selfclosing tag
*/
function genericTagSelfclosing(name, params, override) {
return '<' + name + htmlTagParams(params, override) + ' />';
Expand All @@ -529,7 +614,7 @@ function genericTagSelfclosing(name, params, override) {
/**
* Prefixes key with 'data-'
*
* @param String key - name of key
* @param {String} key name of key
*/
function dataParam(key) {
if (this[key]) {
Expand All @@ -541,25 +626,27 @@ function dataParam(key) {
/**
* Compares a string against a string or an array
*
* @param String value - Content of the String to be compared
* @param Object selectvalue - String or Array of possiblities to be equal to the first string
* @author <a href="https://github.com/SirUli">Uli Wolf</a>
* @param {String} value Content of the String to be compared
* @param {String|Array} selectvalue String or Array of possiblities to be equal to the first string
* @returns {Boolean} True if the string matches the other string or array. False when not.
*/
function activeValue(value, selectvalue) {
var returnBool = false;

// If this is an Array (e.g. when multiple values should be selected), iterate
if (Object.prototype.toString.call(selectvalue) === '[object Array]') {
// This is an array
// This is an Array (e.g. when multiple values should be selected), iterate
for (var selectvalueNr in selectvalue) {
// Compare value against selectvalue. Cast to String as these might be objects.
// Cast to String as these might be objects.
if (String(value) == String(selectvalue[selectvalueNr])) {
returnBool = true
continue;
}
}
} else {
// This is just one entry
// Compare value against selectvalue. Cast to String as these might be objects.
// Cast to String as these might be objects.
if (String(value) == String(selectvalue)) {
returnBool = true
}
Expand All @@ -569,15 +656,32 @@ function activeValue(value, selectvalue) {

/**
* Escape &, &lt; and > symbols
*
* @param {String} html String with possible HTML-Elements
* @returns {String} resulting string with escaped characters
*/
function sanitizeHTML(html) {
return html.replace(/&/g, '&amp;').replace(/>/g, '&gt;').replace(/</g, '&lt;');
}
HelperSet.prototype.sanitize = sanitizeHTML;

/**
* Checks if the environment is production
*
* @returns {Boolean} True if production, otherwise false
*/
function checkProd() {
return app.settings.env === 'production';
}

/**
* Provides the link to a file. Checks if a file needs to be suffixed with a
* timestamp
*
* @param {String} type Type of the file, e.g. css or js
* @param {String} file name (local file) or link (external) to the file
* @returns {String} Final Link to the file
*/
function checkFile(type, file) {
var isExternalFile = regexps.isHttp.test(file),
isCached = file.match(regexps.cached),
Expand Down

0 comments on commit bcda203

Please sign in to comment.