added documentation and fix typos

clmath · clmath · commit a5e7d43928b5 · 2014-01-27T15:52:22.000+01:00
diff --git a/.travis.yml b/.travis.yml
@@ -1,5 +1,9 @@
 language: node_js
-node_js: "0.10"
-before_script: 
-  - npm install -g grunt-cli
-script: "grunt jshint"
+node_js: '0.10'
+before_script:
+- npm install -g grunt-cli
+script: grunt travis
+env:
+  global:
+  - secure: DO5E2w6hfCCrh8dm7hwQfePiOXnHFnyDXg6IyZCCrkIuleLYAFP7B/atlgFPyPSmMEu42JynWN6nrGGZv4s9br2IZR7kIPA5clnU2SAYwTbLdARNE8WIo5bWQcROX90MyvxaZV3C3/THdLF8eB3LTD3GEXiOePYQcuAHMAQvPfk=
+  - secure: cAQhsHCidIkL/ClxUOMGSNggytB0ugpjC8rlrQOu/fMp7he/BI/TqlgF78lA1Kzh55XXSOA8Sm25gb0r3wvzp2YZ1hx6U3qRrrHPymLvrD2pciVeXqd13tGWUhi+//uv1slL8pctneEkwqY+H31Wp5XPZkyY+kJbaJRxfHCrcek=
diff --git a/README.md b/README.md
@@ -1,6 +1,9 @@
 # requirejs-dplugins
 
-AMD plugins for RequireJS.
+Set of AMD plugins for RequireJS. It contains the following plugins:
+
+ * [i18n](#i18n)
+ * [maybe](#maybe)
 
 ## Status
 
@@ -16,17 +19,74 @@ All contributions require a [Dojo Foundation CLA](http://dojofoundation.org/abou
 ## Dependencies
 
 This project requires the following other project to run:
- * requirejs
+
+* requirejs
 
 ## Installation
 
 * Bower release installation: `bower install requirejs-dplugins`
 
 * Manual master installation: go to the root Dojo installation directory and clone requirejs-dplugins from github:
 
-	$ git clone git://github.com/ibm-js/requirejs-dplugins.git
+	`$ git clone git://github.com/ibm-js/requirejs-dplugins.git`
 
 ## Documentation
+### i18n
+This plugin is based on requirejs i18n but modified to support nls built layer.
+
+#### When the application IS NOT optimized
+If an application is not built, this plugin will behave exactly like the i18n plugin from RequireJS.
+The appropriate documentation can be found on [RequireJS website](http://requirejs.org/docs/api.html#i18n).
+
+#### When the application IS optimized
+Once the application is built, the plugin offer three new options:
+
+```
+requirejs.config({
+    config: {
+        i18n: {
+            layerOnly: bool,    //default: false
+            languagePack: bool, //default: false
+            enhanceLayer: bool, //default: true
+        }
+    }
+
+});
+```
+ * `layerOnly` (default: false)
+    
+    If `layerOnly = true`, the plugin is only looking for nls bundles in built nls layers. `layerOnly` must be true if only the built nls layers are deployed with the application.
+    If the individual nls bundles are also deployed, `layerOnly` should be false.
+
+ * `languagePack` (default: false)
+    
+    If true, this option give the possibility to add new locales to the application just by adding the corresponding built nls layer. However, this will result in more http requests (and some expected 404 in the console), so it should only be used in low latency environments (like cordova applications).
+ * `enhanceLayer` (default: true)
+    
+    This option is NOT used if `layerOnly = true`.
+
+    This option define the behaviour of the plugin when a bundle is retrieved from a layer with a less specific locale than requested (ie: bundle `en` from layer when `en-us` was requested).
+        
+    * If `enhanceLayer = false`, the plugin only use the bundle from the layer. This is useful when a part of the application is an already built package distributed without the individual nls bundles.
+    
+    * If `enhanceLayer = true`, the plugin will try to load a more specific individual bundle if one exist.
+ 
+
+
+### maybe
+This plugin allows to require modules that may or may not exist. If the module is not found it will be `undefined`.
+
+
+#### Sample usage
+```
+require(["maybe!a/module/id"], function(module){
+    if (module === undefined) {
+        //do something when module IS NOT found
+    } else {
+        //do something else 2when module IS found
+    }
+});
+```
 
 
 ## Credits
diff --git a/i18n.js b/i18n.js
@@ -160,9 +160,11 @@ define(['./i18n/common', "module"], function (common, module) {
 				masterMid,
 				layer;
 
+			moduleConfig.enhanceLayer = moduleConfig.enhanceLayer === undefined ? true : moduleConfig.enhanceLayer;
+				
 			// Parse name and set the locale if a top level bundle is required
 			name = parseName(name);
-			name.requestedLocale = name.requestedLocale || common.getLocale(config);
+			name.requestedLocale = name.requestedLocale || common.getLocale(moduleConfig.locale || config.locale);
 			masterMid = getMasterMid(name);
 
 			// If there is no layer, classic AMD mode
diff --git a/i18n/common.js b/i18n/common.js
@@ -2,8 +2,7 @@ define(["../maybe!./parentLocale"], function (parentLocale) {
 	parentLocale = parentLocale || {};
 
 	return {
-		getLocale: function (config) {
-			var locale = config.locale;
+		getLocale: function (locale) {
 			if (!locale) {
 				locale = typeof navigator === "undefined" ? "root" :
 					(navigator.language ||
diff --git a/i18n/parentLocale.js b/i18n/parentLocale.js
@@ -1,125 +1,125 @@
 define({
-	"en-AG": "en-001",
-	"en-AI": "en-001",
-	"en-BB": "en-001",
-	"en-BM": "en-001",
-	"en-BS": "en-001",
-	"en-BW": "en-001",
-	"en-BZ": "en-001",
-	"en-CC": "en-001",
-	"en-CK": "en-001",
-	"en-CM": "en-001",
-	"en-CX": "en-001",
-	"en-DM": "en-001",
-	"en-ER": "en-001",
-	"en-FJ": "en-001",
-	"en-FM": "en-001",
-	"en-GB": "en-001",
-	"en-GD": "en-001",
-	"en-GH": "en-001",
-	"en-GM": "en-001",
-	"en-GY": "en-001",
-	"en-JM": "en-001",
-	"en-KE": "en-001",
-	"en-KI": "en-001",
-	"en-KN": "en-001",
-	"en-KY": "en-001",
-	"en-LC": "en-001",
-	"en-LR": "en-001",
-	"en-LS": "en-001",
-	"en-MG": "en-001",
-	"en-MS": "en-001",
-	"en-MU": "en-001",
-	"en-MW": "en-001",
-	"en-NA": "en-001",
-	"en-NF": "en-001",
-	"en-NG": "en-001",
-	"en-NR": "en-001",
-	"en-NU": "en-001",
-	"en-PG": "en-001",
-	"en-PH": "en-001",
-	"en-PN": "en-001",
-	"en-PW": "en-001",
-	"en-RW": "en-001",
-	"en-SB": "en-001",
-	"en-SC": "en-001",
-	"en-SD": "en-001",
-	"en-SL": "en-001",
-	"en-SS": "en-001",
-	"en-SX": "en-001",
-	"en-SZ": "en-001",
-	"en-TC": "en-001",
-	"en-TK": "en-001",
-	"en-TO": "en-001",
-	"en-TT": "en-001",
-	"en-TV": "en-001",
-	"en-TZ": "en-001",
-	"en-UG": "en-001",
-	"en-VC": "en-001",
-	"en-VU": "en-001",
-	"en-WS": "en-001",
-	"en-ZA": "en-001",
-	"en-ZM": "en-001",
-	"en-ZW": "en-001",
-	"en-150": "en-GB",
-	"en-AU": "en-GB",
-	"en-BE": "en-GB",
-	"en-DG": "en-GB",
-	"en-FK": "en-GB",
-	"en-GG": "en-GB",
-	"en-GI": "en-GB",
-	"en-HK": "en-GB",
-	"en-IE": "en-GB",
-	"en-IM": "en-GB",
-	"en-IN": "en-GB",
-	"en-IO": "en-GB",
-	"en-JE": "en-GB",
-	"en-MO": "en-GB",
-	"en-MT": "en-GB",
-	"en-NZ": "en-GB",
-	"en-PK": "en-GB",
-	"en-SG": "en-GB",
-	"en-SH": "en-GB",
-	"en-VG": "en-GB",
-	"es-AR": "es-419",
-	"es-BO": "es-419",
-	"es-CL": "es-419",
-	"es-CO": "es-419",
-	"es-CR": "es-419",
-	"es-CU": "es-419",
-	"es-DO": "es-419",
-	"es-EC": "es-419",
-	"es-GT": "es-419",
-	"es-HN": "es-419",
-	"es-MX": "es-419",
-	"es-NI": "es-419",
-	"es-PA": "es-419",
-	"es-PE": "es-419",
-	"es-PR": "es-419",
-	"es-PY": "es-419",
-	"es-SV": "es-419",
-	"es-US": "es-419",
-	"es-UY": "es-419",
-	"es-VE": "es-419",
-	"pt-AO": "pt-PT",
-	"pt-CV": "pt-PT",
-	"pt-GW": "pt-PT",
-	"pt-MO": "pt-PT",
-	"pt-MZ": "pt-PT",
-	"pt-ST": "pt-PT",
-	"pt-TL": "pt-PT",
-	"az-Cyrl": "root",
-	"bs-Cyrl": "root",
-	"en-Dsrt": "root",
-	"ha-Arab": "root",
-	"mn-Mong": "root",
-	"ms-Arab": "root",
-	"pa-Arab": "root",
-	"shi-Latn": "root",
-	"sr-Latn": "root",
-	"uz-Arab": "root",
-	"uz-Cyrl": "root",
-	"vai-Latn": "root",
-	"zh-Hant": "root",
-	"zh-Hant-MO": "zh-Hant-HK"
+	"en-ag": "en-001",
+	"en-ai": "en-001",
+	"en-bb": "en-001",
+	"en-bm": "en-001",
+	"en-bs": "en-001",
+	"en-bw": "en-001",
+	"en-bz": "en-001",
+	"en-cc": "en-001",
+	"en-ck": "en-001",
+	"en-cm": "en-001",
+	"en-cx": "en-001",
+	"en-dm": "en-001",
+	"en-er": "en-001",
+	"en-fj": "en-001",
+	"en-fm": "en-001",
+	"en-gb": "en-001",
+	"en-gd": "en-001",
+	"en-gh": "en-001",
+	"en-gm": "en-001",
+	"en-gy": "en-001",
+	"en-jm": "en-001",
+	"en-ke": "en-001",
+	"en-ki": "en-001",
+	"en-kn": "en-001",
+	"en-ky": "en-001",
+	"en-lc": "en-001",
+	"en-lr": "en-001",
+	"en-ls": "en-001",
+	"en-mg": "en-001",
+	"en-ms": "en-001",
+	"en-mu": "en-001",
+	"en-mw": "en-001",
+	"en-na": "en-001",
+	"en-nf": "en-001",
+	"en-ng": "en-001",
+	"en-nr": "en-001",
+	"en-nu": "en-001",
+	"en-pg": "en-001",
+	"en-ph": "en-001",
+	"en-pn": "en-001",
+	"en-pw": "en-001",
+	"en-rw": "en-001",
+	"en-sb": "en-001",
+	"en-sc": "en-001",
+	"en-sd": "en-001",
+	"en-sl": "en-001",
+	"en-ss": "en-001",
+	"en-sx": "en-001",
+	"en-sz": "en-001",
+	"en-tc": "en-001",
+	"en-tk": "en-001",
+	"en-to": "en-001",
+	"en-tt": "en-001",
+	"en-tv": "en-001",
+	"en-tz": "en-001",
+	"en-ug": "en-001",
+	"en-vc": "en-001",
+	"en-vu": "en-001",
+	"en-ws": "en-001",
+	"en-za": "en-001",
+	"en-zm": "en-001",
+	"en-zw": "en-001",
+	"en-150": "en-gb",
+	"en-au": "en-gb",
+	"en-be": "en-gb",
+	"en-dg": "en-gb",
+	"en-fk": "en-gb",
+	"en-gg": "en-gb",
+	"en-gi": "en-gb",
+	"en-hk": "en-gb",
+	"en-ie": "en-gb",
+	"en-im": "en-gb",
+	"en-in": "en-gb",
+	"en-io": "en-gb",
+	"en-je": "en-gb",
+	"en-mo": "en-gb",
+	"en-mt": "en-gb",
+	"en-nz": "en-gb",
+	"en-pk": "en-gb",
+	"en-sg": "en-gb",
+	"en-sh": "en-gb",
+	"en-vg": "en-gb",
+	"es-ar": "es-419",
+	"es-bo": "es-419",
+	"es-cl": "es-419",
+	"es-co": "es-419",
+	"es-cr": "es-419",
+	"es-cu": "es-419",
+	"es-do": "es-419",
+	"es-ec": "es-419",
+	"es-gt": "es-419",
+	"es-hn": "es-419",
+	"es-mx": "es-419",
+	"es-ni": "es-419",
+	"es-pa": "es-419",
+	"es-pe": "es-419",
+	"es-pr": "es-419",
+	"es-py": "es-419",
+	"es-sv": "es-419",
+	"es-us": "es-419",
+	"es-uy": "es-419",
+	"es-ve": "es-419",
+	"pt-ao": "pt-pt",
+	"pt-cv": "pt-pt",
+	"pt-gw": "pt-pt",
+	"pt-mo": "pt-pt",
+	"pt-mz": "pt-pt",
+	"pt-st": "pt-pt",
+	"pt-tl": "pt-pt",
+	"az-cyrl": "root",
+	"bs-cyrl": "root",
+	"en-dsrt": "root",
+	"ha-arab": "root",
+	"mn-mong": "root",
+	"ms-arab": "root",
+	"pa-arab": "root",
+	"shi-latn": "root",
+	"sr-latn": "root",
+	"uz-arab": "root",
+	"uz-cyrl": "root",
+	"vai-latn": "root",
+	"zh-hant": "root",
+	"zh-hant-mo": "zh-hant-hk"
 });
