Messages: Support default messages

Author: rxaviers

README.md

@@ -55,17 +55,25 @@ The numeric value to be formatted. Required.
 
 #### Usage
 
-- Default format with USD in English
-
-  `<FormatCurrency currency="USD">{150}</FormatCurrency>`
-
-Result: `<span>$150.00</span>` when using the `en` (English) locale.
-
-- Accounting format with EUR in Portuguese
-
-  `<FormatCurrency currency="EUR" options={{ style: "accounting" }}>{-150}</FormatCurrency>`
-
-Result: `<span>(€150,00)</span>` when using the `pt` (Portuguese) locale.
+Default format with USD.
+
+```js
+<FormatCurrency currency="USD">{150}</FormatCurrency>
+// Which would render:
+// <span>$150.00</span> when using the `en` (English) locale, or
+// <span>US$150,00</span> when using the `pt` (Portuguese) locale.
+```
+
+Accounting format with EUR.
+
+```js
+<FormatCurrency currency="EUR" options={{style: "accounting"}}>
+	{-150}
+</FormatCurrency>
+// Which would render:
+// <span>(€150.00)</span> when using the `en` (English) locale, or
+// <span>(€150,00)</span> when using the `pt` (Portuguese) locale.
+```
 
 ### FormatDate
 
@@ -88,17 +96,27 @@ The date object to be formatted. Required.
 
 #### Usage
 
-- Simple string skeleton
-
-  `<FormatDate options={{skeleton: "GyMMMd"}}>{new Date()}</FormatDate>`
+Simple string skeleton.
 
-Result: `<span>Feb 27, 2015 AD</span>` when using the `en` (English) locale.
+```js
+<FormatDate options={{skeleton: "GyMMMd"}}>
+	{new Date()}
+</FormatDate>
+// Which would render:
+// <span>Feb 27, 2015 AD</span> when using the `en` (English) locale, or
+// <span>27 de fev de 2015 d.C.</span> when using the `pt` (Portuguese) locale.
+```
 
-- Medium length date and time
+Medium length date and time.
 
-  `<FormatDate options={{ datetime: "medium" }}>{new Date()}</FormatDate>`
-
-Result: `<span>27 de fev de 2015 11:17:10</span>` when using the `pt` (Portuguese) locale.
+```js
+<FormatDate options={{datetime: "medium"}}>
+	{new Date()}
+</FormatDate>
+// Which would render:
+// <span>Feb 27, 2015, 11:17:10 AM</span> when using the `en` (English) locale, or
+// <span>27 de fev de 2015 11:17:10</span> when using the `pt` (Portuguese) locale.
+```
 
 ### FormatMessage
 
@@ -109,63 +127,60 @@ It allows for the creation of internationalized messages (as defined by the [ICU
 
 #### Children
 
-String or array path to traverse a set of messages store in JSON format. Required.
+Required unless the `path` property is set. It's a string with the default message. Either this or the `path` property is required.
 
 #### Props
 
-- **path** - required
- - String or array path to traverse a set of messages store in JSON format
+- **path** - required unless children is set
+ - String or array path to traverse a set of messages store in JSON format. Defaults to the message itself defined by the children.
 - **variables** - optional
  - An array (where variables are represented as indeces) or object (for named variables) which contains values for variable replacement within a message.
 - **locale** - optional
  - A string value representing the locale (as defined by BCP47) used to override the default locale (preferred) set by your application using `Globalize.locale(locale)` when formatting the amount.
 
 #### Usage
 
-Below message JSON used in these examples:
-  ```JS
-  {
-    en: {
-      salutations: {
-        hi: "Hi",
-        bye: "Bye"
-      },
-      variables: {
-        hello: "Hello, {0} {1} {2}",
-        hey: "Hey, {first} {middle} {last}"
-      }
-    },
-    "pt": {
-      salutations: {
-        hi: "Oi",
-        bye: "Tchau"
-      },
-      variables: {
-        hello: "Olá, {0} {1} {2}",
-        hey: "Ei, {first} {middle} {last}"
-      }
-    }
-  }
-  ```
-- Simple salutation
-
-Hi: `<FormatMessage>{"salutations/hi"}</FormatMessage>`
-
-Result:
-
-  `<span>Hi</span>` when using the `en` (English) locale, or
-
-  `<span>Oi</span>` when using the `pt` (Portuguese) locale.
-
-- Variable Replacement
-
-Array: `<FormatMessage variables={["Wolfgang", "Amadeus", "Mozart"]}>{"variables/hello"}</FormatMessage>`
-
-Result: `<span>Hello, Wolfgang Amadeus Mozart</span>` when using the `en` (English) locale.
-
-Object in Portuguese: `<FormatMessage variables={{first:"Wolfgang", middle:"Amadeus", last:"Mozart"}}>{"variables/hey"}</FormatMessage>`
-
-Result: `<span>Ei, Wolfgang Amadeus Mozart</span>` when using the `pt` (Portuguese) locale.
+Below translation message JSON used in these examples:
+```js
+{
+	"pt": {
+		"Hi": "Oi",
+		"Hi, {0} {1} {2}": "Olá, {0} {1} {2}",
+		"Hello, {first} {middle} {last}": "Ei, {first} {middle} {last}"
+	}
+}
+```
+
+Simple salutation.
+
+```js
+<FormatMessage>Hi</FormatMessage>
+// Which would render:
+// <span>Hi</span> when using the default message, in this case `en` (English).
+// <span>Oi</span> when using the `pt` (Portuguese) locale and its translation messages.
+```
+
+Variable Replacement.
+
+```js
+// Using Array.
+<FormatMessage variables={["Wolfgang", "Amadeus", "Mozart"]}>
+	{"Hi, {0} {1} {2}"}
+</FormatMessage>
+// Which would render:
+// <span>Hello, Wolfgang Amadeus Mozart</span> when using the default message, in this case `en` (English).
+// <span>Hello, Wolfgang Amadeus Mozart</span> when using the `en` (English) locale and its translation messages.
+
+// Using Object.
+<FormatMessage variables={{first:"Wolfgang", middle:"Amadeus", last:"Mozart"}}>
+  {"Hey, {first} {middle} {last}"}
+</FormatMessage>
+// Which would render:
+// <span>Hey, Wolfgang Amadeus Mozart</span> when using the default message, in this case `en` (English).
+// <span>Ei, Wolfgang Amadeus Mozart</span> when using the `pt` (Portuguese) locale and its translation messages.
+```
+
+See [messageFormatter][] docs in Globalize for more message examples (e.g., pluralization or gender selection).
 
 ### FormatNumber
 
@@ -188,17 +203,25 @@ The number to be formatted. Required.
 
 #### Usage
 
-- Default format pi in English
-
-  `<FormatNumber locale="en">{Math.PI}</FormatNumber>`
-
-Result: `<span>3.142</span>` when using the `en` (English) locale.
-
-- Show at least 2 decimal places in Portuguese
-
-  `<FormatNumber options={{ minimumFractionDigits: 2 }}>{10000}</FormatNumber>`
-
-Result: `<span>10.000,00</span>` when using the `pt` (Portuguese) locale.
+Default format pi.
+
+```js
+<FormatNumber locale="en">{Math.PI}</FormatNumber>
+// Which would render:
+// <span>3.142</span> when using the `en` (English) locale, or
+// <span>3,142</span> when using the `pt` (Portuguese) locale.
+```
+
+Show at least 2 decimal places.
+
+```js
+<FormatNumber options={{minimumFractionDigits: 2}}>
+	{10000}
+</FormatNumber>
+// Which would render:
+// <span>10,000.00</span> when using the `en` (English) locale, or
+// <span>10.000,00</span> when using the `pt` (Portuguese) locale.
+```
 
 ## License
 

src/generator.js

@@ -8,6 +8,7 @@ function capitalizeFirstLetter(string) {
 function generator(fn, argArray, options) {
     var Fn = capitalizeFirstLetter(fn);
     options = options || {};
+    var beforeFormat = options.beforeFormat || function() {};
     return {
         displayName: Fn,
         format: function() {
@@ -28,6 +29,7 @@ function generator(fn, argArray, options) {
               this.instance = Globalize(this.props["locale"]);
             }
 
+            beforeFormat.call(this);
             return React.DOM.span(null, this.format());
         }
     }

src/message.js

@@ -4,4 +4,87 @@ import generator from "./generator";
 import "globalize/message";
 import "globalize/plural";
 
-export default React.createClass(generator("formatMessage", ["path", "variables"]));
+function messageSetup(componentProps, instance, args) {
+    var defaultMessage, path;
+    var children = componentProps.children;
+
+    function extractFromFnComments(fn) {
+        return fn.toString().replace(/(function \(\) \{\/\*|\*\/\})/g, "");
+    }
+
+    function getDefaultMessage(children) {
+        if (typeof children === "string") {
+            return children;
+        } else if (typeof children === "function") {
+            return extractFromFnComments(children);
+        } else {
+            throw new Error("Invalid default message type `" + typeof children + "`");
+        }
+    }
+
+    function getMessage() {
+        return instance.cldr.get(["globalize-messages/{bundle}"].concat(path));
+    }
+
+    function setMessage(message) {
+        var data = {};
+        function set(data, path, value) {
+            var i;
+            var node = data;
+            var length = path.length;
+
+            for (i = 0; i < length - 1; i++) {
+                if (!node[path[i]]) {
+                    node[path[i]] = {};
+                }
+                node = node[path[i]];
+            }
+            node[path[i]] = value;
+        }
+        set(data, [instance.cldr.attributes.bundle].concat(path), message);
+        Globalize.loadMessages(data);
+    }
+
+    // Set path.
+    if (args[0]) {
+        path = args[0].split("/");
+    } else {
+        defaultMessage = getDefaultMessage(children);
+        args[0] = sanitizePath(defaultMessage);
+        path = [args[0]];
+    }
+
+    // Development mode only.
+    if (instance.cldr) {
+        if (!getMessage()) {
+            defaultMessage = defaultMessage || getDefaultMessage(children);
+            setMessage(defaultMessage);
+        }
+    }
+
+}
+
+function sanitizePath(pathString) {
+    return pathString.trim().replace(/\{/g, "(").replace(/\}/g, ")").replace(/\//g, "|").replace(/\n/g, " ").replace(/ +/g, " ").replace(/"/g, "'");
+}
+
+// Overload Globalize's `.formatMessage` to allow default message.
+var messageFormatterSuper = Globalize.messageFormatter;
+Globalize.messageFormatter =
+Globalize.prototype.messageFormatter = function(pathOrMessage) {
+    var aux = {};
+    var sanitizedPath = sanitizePath(pathOrMessage);
+    if (this.cldr && this.cldr.get(["globalize-messages/{bundle}", sanitizedPath]) === undefined) {
+        aux[this.cldr.attributes.bundle] = {};
+        aux[this.cldr.attributes.bundle][sanitizedPath] = pathOrMessage;
+        Globalize.loadMessages(aux);
+    }
+    arguments[0] = sanitizedPath;
+    return messageFormatterSuper.apply(this, arguments);
+};
+
+export default React.createClass(generator("formatMessage", ["path", "variables"], {
+    beforeFormat: function() {
+        messageSetup(this.props, this.instance, this.args);
+    }
+}));