Source handlebars.phrase/handlebars.phrase.js

  1. (function (moduleFactory) {
  2.     if(typeof exports === "object") {
  3.         module.exports = moduleFactory(require("lodash"));
  4.     } else if (typeof define === "function" && define.amd) {
  5.         define(["lodash"], moduleFactory);
  6.     }
  7. }(function (_) {
  8. /**
  9.  * @module handlebars%phrase
  10.  * @description  Provides helper to allow strings to be externalised
  11.  * 
  12.  *      var Handlebars = require("handlebars");
  13.  *      var Phrase = require("handlebars.phrase");
  14.  *      Phrase.registerHelpers(Handlebars);
  15.  *      Phrase.setLanguages(langs);
  16.  *      Phrase.locale(lang);
  17.  * @returns {object} Phrase instance
  18.  */
  19.     var Handlebars;
  21.     var languageRegister;
  22.     var phraseRegister = {};
  23.     var phraseStrings = {}; // raw lang strings that can be returned as is
  24.     var phraseTemplates = {}; // compiled lang template cache
  25.     var locale = "default";
  26.     var pendDelimiter = ".";
  27.     var defaultLocaleProvidesFallback = false;
  28.     var phraseFilter;
  30.     var Phrase = (function () {
  31.         /**
  32.          * @template phrase
  33.          * @block helper
  34.          * @description  Outputs a phrase corresponding to key provided
  35.          *
  36.          *     {{phrase key}}
  37.          *
  38.          * Output a phrase, interpolating a variable from the context
  39.          * 
  40.          *     {{phrase key var=var}}
  41.          *
  42.          * Output a phrase for a particular locale
  43.          * 
  44.          *     {{phrase key lang}}
  45.          *     {{phrase key locale=lang}}
  46.          *
  47.          * Output a phrase for an appended key
  48.          * 
  49.          *     {{phrase key _append=append}}
  50.          *     {{phrase key _append=append _appendix=appendix}}
  51.          *
  52.          * Output a phrase for an prepended key
  53.          * 
  54.          *     {{phrase key _prepend=prepend}}
  55.          *     {{phrase key _prepend=prepend _prependix=prependix}}
  56.          *
  57.          * Output a phrase for debugging purposes
  58.          * 
  59.          *     {{phrase key _debug=true}}
  60.          *
  61.          * Use simpliflied syntax
  62.          *     ((key))
  63.          *     ((key var=var))
  64.          *
  65.          */
  66.         var PhraseHelper = function () {
  67.             var args = Array.prototype.slice.call(arguments);
  68.             var isGet = false;
  69.             if (args[0] === "get") {
  70.                 isGet = true;
  71.                 args.shift();
  72.             }
  73.             // if we don't pass key, how can we tell that arg isn't a locale?
  74.             var key = args[0];
  75.             var originalKey = key;
  76.             var params = {};
  77.             var options = args[args.length-1];
  79.             // allow helper context to be overridden
  80.             try {
  81.                 // add in this before opions.hash.params
  82.                 // however, that means all vars rampage through all scopes
  83.                 params = _.extend({}, (options.hash.params || {}), options.hash);
  84.                 delete options.hash.params;
  85.             } catch (e) {
  86.                 console.log(e, options, arguments);
  87.             }
  89.             // Determine which locale is in effect
  90.             var tmpLocale;
  91.             if (args.length === 3) {
  92.                 tmpLocale = args[1];
  93.             } else {
  94.                 tmpLocale = params.locale;
  95.             }
  96.             if (!tmpLocale && !isGet) {
  97.                 tmpLocale = this.locale;
  98.             }
  99.             if (!tmpLocale || tmpLocale === "default") {
  100.                 tmpLocale = locale;
  101.             }
  103.             // ensure phraseRegister entries exists for locale and tmpLocale
  104.             if (!phraseRegister[locale]) {
  105.                 phraseRegister[locale] = {};
  106.                 phraseStrings[locale] = {};
  107.                 phraseTemplates[locale] = {};
  108.             }
  109.             if (!phraseRegister[tmpLocale]) {
  110.                 phraseRegister[tmpLocale] = {};
  111.                 phraseStrings[tmpLocale] = {};
  112.                 phraseTemplates[tmpLocale] = {};
  113.             }
  115.             if (params._append) {
  116.                 key += pendDelimiter + params._append;
  117.                 if (params._appendix) {
  118.                     key += pendDelimiter + params._appendix;
  119.                 }
  120.             }
  121.             if (params._prepend) {
  122.                 key = params._prepend + pendDelimiter + key;
  123.                 if (params._prependix) {
  124.                     key = params._prependix + pendDelimiter + key;
  125.                 }
  126.             }
  128.             if (!phraseRegister[tmpLocale][key]) {
  129.                 var templateString = languageRegister[tmpLocale][key];
  130.                 if (templateString === undefined && tmpLocale !== locale) {
  131.                     languageRegister[tmpLocale][key] = languageRegister[locale][key];
  132.                     templateString = languageRegister[tmpLocale][key];
  133.                 }
  134.                 if (templateString !== undefined) {
  135.                     if (templateString.indexOf("{{") === -1 && templateString.indexOf("((") === -1) {
  136.                         phraseStrings[tmpLocale][key] = templateString;
  137.                         // possible to cache if compilable but
  138.                         // just reference to another static phrase?
  139.                     } else {
  140.                         phraseTemplates[tmpLocale][key] = Handlebars.compile(templateString);
  141.                     }
  142.                 }
  143.                 phraseRegister[tmpLocale][key] = true;
  144.             }
  146.             var langValue;
  147.             //  || (defaultLocaleProvidesFallback && phraseStrings[locale][key])
  148.             if (phraseStrings[tmpLocale][key]) {
  149.                 langValue = phraseStrings[tmpLocale][key];
  150.             } else if (phraseTemplates[tmpLocale][key]) {
  151.                 // could possibly cache the output using key created from input
  152.                 // but would that be any quicker?
  154.                 // ensure that tmpLocale gets passed on to nested phrases
  155.                 params.locale = tmpLocale;
  156.                 var data = _.extend({}, this, params);
  157.                 var template = phraseTemplates[tmpLocale][key];
  158.                 langValue = template.call(this, data);
  159.             } else {
  160.                 if (!isGet && !params["_allow-empty"]) {
  161.                     // return the key itself
  162.                     langValue = key;
  163.                 }
  164.             }
  165.             if (langValue && params._debug) {
  166.                 // output a value for debugging
  167.                 langValue = '<phrase data-phrase-key="' + key + '">' + langValue + "</phrase>";
  168.             }
  169.             if (langValue && phraseFilter) {
  170.                 // apply any filter that has been set
  171.                 langValue = phraseFilter(langValue);
  172.             }
  173.             return langValue ? new Handlebars.SafeString(langValue) : "";
  174.         };
  176.         var external = {
  177.             /**
  178.              * @method locale
  179.              * @static
  180.              * @param {string} [loc] Locale to change to
  181.              * @description Get or set default locale used by Phrase
  182.              *
  183.              * If called without loc parameter, returns locale
  184.              *
  185.              * If called with loc parameter, sets locale
  186.              *
  187.              * @returns {string} Phrase’s locale
  188.              */
  189.             locale: function (loc) {
  190.                 if (loc) {
  191.                     locale = loc;
  192.                 }
  193.                 return locale;
  194.             },
  195.             /**
  196.              * @method get
  197.              * @static
  198.              * @param {object} phrase Lookup key
  199.              * @param {object} args Any arguments to pass to phrase
  200.              * @param {object} context Specific context to use
  201.              * @param {string} [locale] Locale to use
  202.              * @description Get HandlebarsSafeString object for a key
  203.              *
  204.              * @returns {HandlebarsSafeString} phrase
  205.              */
  206.             get: function (phrase, args, context, locale) {
  207.                 if (!args) {
  208.                     args = {};
  209.                 }
  210.                 context = context || this;
  211.                 var params = ["get", phrase, {hash: args}];
  212.                 if (locale) {
  213.                     params.splice(2, 0, locale);
  214.                 }
  215.                 return PhraseHelper.apply(context, params);
  216.             },
  217.             /**
  218.              * @method getString
  219.              * @static
  220.              * @param {object} phrase Lookup key
  221.              * @param {object} args Any arguments to pass to phrase
  222.              * @param {object} context Specific context to use
  223.              * @param {string} [locale] Locale to use
  224.              * @description Get phrase value for a key
  225.              *
  226.              * @returns {string} phrase
  227.              */
  228.             getString: function (phrase, args, context, locale) {
  229.                 var value = external.get(phrase, args, context, locale);
  230.                 return value ? value.toString() : undefined;
  231.             },
  232.             /**
  233.              * @method setLanguages
  234.              * @static
  235.              * @param {object} [languages] Object of language phrases
  236.              * @param {object} [options]
  237.              * @param {boolean} [options.localefallback=false] Whether default language should provide missing values for other languages
  238.              * @param {string} [options.penddelimiter=.] Delimiter to use when appending or prepending keys
  239.              * @description Set languages object without which Phrase cannot work
  240.              *
  241.              * Clears any previously set languages
  242.              *
  243.              */
  244.             setLanguages: function (languages, options) {
  245.                 options = options || {};
  246.                 phraseRegister = {};
  247.                 phraseStrings = {};
  248.                 phraseTemplates = {};
  249.                 if (languages) {
  250.                     languageRegister = languages;
  251.                 }
  252.                 if (options.penddelimiter) {
  253.                     pendDelimiter = options.penddelimiter;
  254.                 }
  255.                 if (options.localefallback !== undefined) {
  256.                     defaultLocaleProvidesFallback = !!options.localefallback;
  257.                 }
  258.             },
  259.             /**
  260.              * @method addLanguages
  261.              * @static
  262.              * @param {object} [languages] Object of language phrases
  263.              * @description Add keys to existing languages object
  264.              *
  265.              * Clears any previously cached strings or templates for languages passed
  266.              */
  267.             addLanguages: function (languages) {
  268.                 languageRegister = languageRegister || {};
  269.                 if (languages) {
  270.                     for (var lang in languages) {
  271.                         phraseRegister[lang] = {};
  272.                         phraseStrings[lang] = {};
  273.                         phraseTemplates[lang] = {};
  274.                         languageRegister[lang] = _.extend({}, languageRegister[lang], languages[lang]);
  275.                     }
  276.                 }
  277.             },
  278.             /**
  279.              * @method setLanguage
  280.              * @static
  281.              * @param {string} lang Language to be set
  282.              * @param {object} phrases Phrases object for the language
  283.              * @description Set language individually
  284.              *
  285.              * Clears any previously cached strings or templates for language
  286.              *
  287.              */
  288.             setLanguage: function (lang, phrases) {
  289.                 languageRegister = languageRegister || {};
  290.                 phraseRegister[lang] = {};
  291.                 phraseStrings[lang] = {};
  292.                 phraseTemplates[lang] = {};
  293.                 languageRegister[lang] = phrases;
  294.             },
  295.             /**
  296.              * @method addLanguage
  297.              * @static
  298.              * @param {string} lang Language to add to
  299.              * @param {object} phrases Phrases object for the language
  300.              * @description Add phrases to individual language
  301.              *
  302.              * Clears any previously cached strings or templates for language
  303.              *
  304.              */
  305.             addLanguage: function (lang, phrases) {
  306.                 languageRegister = languageRegister || {};
  307.                 phraseRegister[lang] = {};
  308.                 phraseStrings[lang] = {};
  309.                 phraseTemplates[lang] = {};
  310.                 languageRegister[lang] = _.extend({}, languageRegister[lang], phrases);
  311.             },
  312.             /**
  313.              * @method registerHelper
  314.              * @static
  315.              * @param {object} hbars Handlebars instance
  316.              * @description Register Phrase helper with Handlebars
  317.              *
  318.              * - {@link template:phrase}
  319.              */
  320.             registerHelper: function (hbars) {
  321.                 Handlebars = hbars;
  322.                 Handlebars.registerHelper("phrase", PhraseHelper);
  323.                 var Hparse = Handlebars.parse;
  324.                 Handlebars.parse = function (input) {
  325.                     input = input.replace(/\(\(\(([^ ]+?)( .+?)*\)\)\)/g, function (m, m1, m2) {
  326.                         return '{{{phrase "' + m1 + '"' + (m2 ? m2 : "") + '}}}';
  327.                     });
  328.                     input = input.replace(/\(\(([^ ]+?)( .+?)*\)\)/g, function (m, m1, m2) {
  329.                         return '{{phrase "' + m1 + '"' + (m2 ? m2 : "") + '}}';
  330.                     });
  331.                     return Hparse(input);
  332.                 };
  333.             },
  334.             /**
  335.              * @method setFilter
  336.              * @static
  337.              * @param {function} fn
  338.              * @description Sets a filter to apply to all returned output
  339.              */
  340.             setFilter: function (fn) {
  341.                 phraseFilter = fn;
  342.             }
  344.         };
  345.         // alias plural form
  346.         external.registerHelpers = external.registerHelper;
  348.         return external;
  349.     })();
  351.     return Phrase;
  353. }));