DataType examples.

src/datatype/docs/component.json

@@ -11,7 +11,17 @@
     "examples": [
 
         {
-            "name": "datatype_dateformat_lang",
+            "name": "datatype-dateformat",
+            "displayName": "DataType.Date.format()",
+            "modules": ["datatype"],
+            "description": "Formatting dates into strings.",
+	        "useModules": ["node", "datatype-date", "escape"],
+
+            "hideTableOfContents": true
+        },
+
+        {
+            "name": "datatype-dateformat-lang",
             "displayName": "Formatting Dates Using Language Resource Bundles",
             "modules": ["datatype", "intl"],
             "description": "Formatting dates into strings using pre-packaged language resource bundles.",
@@ -21,17 +31,7 @@
         },
 
         {
-            "name": "datatype_dateformat",
-            "displayName": "DataType.Date.format()",
-            "modules": ["datatype"],
-            "description": "Formatting dates into strings.",
-	        "useModules": ["node", "datatype-date", "escape"],
-
-                "hideTableOfContents": true
-            },
-
-        {
-            "name": "datatype_dateparse",
+            "name": "datatype-dateparse",
             "displayName": "DataType.Date.parse()",
             "modules": ["datatype"],
             "description": "Parsing data into dates.",
@@ -41,7 +41,7 @@
         },
 
         {
-            "name": "datatype_numberformat",
+            "name": "datatype-numberformat",
             "displayName": "DataType.Number.format()",
             "modules": ["datatype"],
             "description": "Formatting numbers into strings.",
@@ -51,7 +51,7 @@
         },
 
         {
-            "name": "datatype_numberparse",
+            "name": "datatype-numberparse",
             "displayName": "DataType.Number.parse()",
             "modules": ["datatype"],
             "description": "Parsing data into numbers.",
@@ -61,7 +61,7 @@
         },
 
         {
-            "name": "datatype_xmlformat",
+            "name": "datatype-xmlformat",
             "displayName": "DataType.XML.format()",
             "modules": ["datatype"],
             "description": "Formatting XML documents into strings.",
@@ -71,7 +71,7 @@
         },
 
         {
-            "name": "datatype_xmlparse",
+            "name": "datatype-xmlparse",
             "displayName": "DataType.XML.parse()",
             "modules": ["datatype"],
             "description": "Parsing strings into XML documents.",

src/datatype/docs/datatype-dateformat-lang.mustache

@@ -0,0 +1,99 @@
+<style scoped>
+/* custom styles for this example */
+
+#default_lang_output, #single_lang_output {
+    font-style:italic;
+}
+
+#event_output {
+    margin-left:1em;
+    color:#00aa00;
+    font-style:italic;
+}
+
+#demo .output {
+    margin-bottom:1em;
+    padding:10px;
+    border:1px solid #D9D9D9;
+}
+
+#demo_output.rtl {
+    text-align:right;
+}
+
+#switchlang   {
+    margin-top:3em;
+}
+</style>
+
+<div class="intro">
+    <p>The "date-format" module of the DataType Utility leverages the external language resource bundle support provided in 3.1.0, as the preferred way to define and deliver formatting patterns for various languages.</p>
+</div>
+
+<div class="example">
+    {{>datatype-dateformat-lang-source}}
+</div>
+
+<h4>Using Date Formatting Support</h4>
+
+<p>To use Date formatting language resource bundle support in your application, all you need to do is use the `datatype-date` module, and specify the (supported) language you need for the instance.</p>
+
+```
+// Default (no language specified)
+YUI().use("datatype-date", function (Y) {
+    Y.one("#default_lang_output").setContent(
+        Y.DataType.Date.format(new Date(), {format:"%x"})
+    );
+});
+
+// Format Date For fr-FR
+YUI({lang:"fr-FR"}).use("datatype-date", function (Y) {
+    Y.one("#single_lang_output").setContent(
+        Y.DataType.Date.format(new Date(), {format:"%x"})
+    );
+});
+```
+
+<h4>Switching Languages</h4>
+
+<p>You can also switch the language resource bundle currently in use for your YUI instance, by invoking `Y.use` to pull down another language resource bundle if required:</p>
+
+```
+    ...
+
+    var lang = Y.one("#demo_lang").get("value");
+
+    // Pull down a new language resource bundle for datatype-date.
+
+    // Since it's a potentially async operation, we write our application logic
+    // in a callback which is invoked once the new language resource bundle is pulled down
+
+    Y.use("lang/datatype-date-format_" + lang, function(Y) {
+
+        // You only need to set the language explicitly when switching languages,
+        // It is not required for the single language use case shown previously.
+        Y.Intl.setLang("datatype-date-format", lang);
+
+        formattedDate = Y.DataType.Date.format(new Date(), {format:"%c"});
+
+    });
+    ...
+```
+
+<p>The `Y.Intl` utility, which is automatically pulled down with a language resource bundle acts as a manager for language resource bundle handling, and is used to register new language resource bundles, set the language currently being used, and retrieve strings for the currently language.</p>
+
+<h4>Available Languages</h4>
+
+<p>The set of available languages for a given module, can be obtained from the <code>Intl</code> utility, and we use this support to generate the dropdown for this example:</p>
+
+```
+    // Insert the languages available for the datatype-date module
+    var availLangs = Y.Intl.getAvailableLangs("datatype-date-format"),
+        select = Y.one("#demo_lang"),
+        i;
+
+    for (i = 0; i < availLangs.length; i++) {
+        select.append('<option value="' + availLangs[i] + '">' + availLangs[i] + '</option>');
+    }
+```
+

src/datatype/docs/datatype-dateformat.mustache

@@ -0,0 +1,38 @@
+<style scoped>
+/* custom styles for this example */
+#demo .output {margin-bottom:1em; padding:10px; border:1px solid #D9D9D9;}
+</style>
+
+<div class="intro">
+    <p>The Date module of the DataType Utility allows you to format a JavaScript Date object into a string with `strftime` syntax. This method allows you to specify any tokenized HTML value as the format. However, in this example the formatted output will be escaped for security.</p>
+
+    <p><strong>NOTE:</strong> As of 3.1.0, the formatting patterns used by DateType.Date can be driven by external language resource bundles as described in the <a href="datatype-dateformat-lang.html">"Formatting Dates Using Language Resource Bundles" Example</a>. This examples currently uses the 3.0.0 `dateFormat` and `locale` instance configuration support which have been deprecated.</p>
+</div>
+
+<div class="example">
+    {{>datatype-dateformat-source}}
+</div>
+
+<p>To convert a data value to a date, simply call the <code>parse()</code> function of the DataType.Date class:</p>
+
+```
+YUI().use("datatype-date", function(Y) {
+    var date = Y.DataType.Date.parse("Jan 7, 2003");
+    // date is a JavaScript Date object
+});
+```
+
+<p>Under the hood, the data value is converted to a date via the <code>Date()</code> constructor:</p>
+
+```
+YUI().use("datatype-date", function(Y) {
+    // These all return dates
+    var date = Y.DataType.Date.parse("December 17, 1995 03:24:00");
+
+    date = Y.DataType.Date.parse(1995,11,17);
+
+    date = Y.DataType.Date.parse(1995,11,17,3,24,0);
+
+    date = Y.DataType.Date.parse(948548583);
+});
+```

src/datatype/docs/datatype-dateparse.mustache

@@ -0,0 +1,36 @@
+<style scoped>
+/* custom styles for this example */
+#demo .output {margin-bottom:1em; padding:10px; border:1px solid #D9D9D9;}
+</style>
+
+<div class="intro">
+    <p>The Date module of the DataType Utility allows you to take a data value and convert it to a number. The `parse()` method will accept <a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Date">any value supported by JavaScript's `Date()` constructor</a>.</p>
+</div>
+
+<div class="example">
+    {{>datatype-dateparse-source}}
+</div>
+
+<p>To convert a data value to a date, simply call the `parse()` function of the DataType.Date class:</p>
+
+```
+YUI().use("datatype-date", function(Y) {
+    var date = Y.DataType.Date.parse("Jan 7, 2003");
+    // date is a JavaScript Date object
+});
+```
+
+<p>Under the hood, the data value is converted to a date via the `Date()` constructor:</p>
+
+```
+YUI().use("datatype-date", function(Y) {
+    // These all return dates
+    var date = Y.DataType.Date.parse("December 17, 1995 03:24:00");
+
+    date = Y.DataType.Date.parse(1995,11,17);
+
+    date = Y.DataType.Date.parse(1995,11,17,3,24,0);
+
+    date = Y.DataType.Date.parse(948548583);
+});
+```

src/datatype/docs/datatype-numberformat.mustache

@@ -0,0 +1,44 @@
+<style scoped>
+/* custom styles for this example */
+#demo label {display:block;}
+#demo fieldset {margin:1em;}
+#demo .short label, #demo .medium label {display:inline;}
+#demo .short input {width:2em;}
+#demo .medium input {width:5em;}
+</style>
+
+<div class="intro">
+    <p>The Number module of the DataType Utility allows you to take a number and format it into a string with the following configuration parameters: `decimalPlaces`, `decimalSeparator`, `thousandsSeparator`, `prefix`, and `suffix`. Although this method allows you to specify HTML values, in this example the formatted output will be escaped for security.</p>
+</div>
+
+<div class="example">
+    {{>datatype-numberformat-source}}
+</div>
+
+<p>To output a number as a string, simply call the <code>format()</code> function of the DataType.Number class:</p>
+
+```
+YUI().use("datatype-number", function(Y) {
+    alert(Y.DataType.Number.format(123123123));
+
+    // This alerts the string "123123123"
+});
+```
+
+The `format()` function also takes a variety of configuration parameters that manipulate the value of the string. This is helpful, for instance, when displaying numbers as currency:
+
+```
+YUI().use("datatype-number", function(Y) {
+    alert(Y.DataType.Number.format(123123123.176,{
+        prefix: "&#165;",
+        thousandsSeparator: ".",
+        decimalSeparator: ",",
+        decimalPlaces: 2,
+        suffix: " (YEN)"
+    }));
+
+    // This alerts the string "&#165;123.123.123,18 (YEN)"
+});
+```
+
+<p><strong>Note:</strong> Although this method allows you to specify HTML values, in this example the formatted output will be escaped for security.</p>

src/datatype/docs/datatype-numberparse.mustache

@@ -0,0 +1,38 @@
+<style scoped>
+/* custom styles for this example */
+#demo label {display:block;}
+#demo fieldset {margin:1em;}
+</style>
+
+<div class="intro">
+    <p>The Number module of the DataType Utility allows you to take a data value and convert it to a number.</p>
+</div>
+
+<div class="example">
+    {{>datatype-numberparse-source}}
+</div>
+
+<p>To convert a data value to a number, simply call the `parse()` function of the DataType.Number class:</p>
+
+```
+YUI().use("datatype-number", function(Y) {
+    var output = Y.DataType.Number.parse("123123.123");
+    // output is the number 123123.123
+});
+```
+
+<p>Under the hood, the data value is converted to a number via `+data`, not `parseInt()`. When the resulting value is `NaN`, then null is returned:</p>
+
+```
+YUI().use("datatype-number", function(Y) {
+    var output = Y.DataType.Number.parse("$100");
+    // output is null
+
+    output = Y.DataType.Number.parse("20 dollars");
+    // output is null
+
+    output = Y.DataType.Number.parse(new Date("Jan 1, 2000"));
+    // output is 946713600000
+
+});
+```

src/datatype/docs/datatype-xmlformat.mustache

@@ -0,0 +1,12 @@
+<style scoped>
+/* custom styles for this example */
+#demo .output {margin-bottom:1em; padding:10px; border:1px solid #D9D9D9;}
+</style>
+
+<div class="intro">
+    <p>The XML module of the DataType Utility allows you to take an XML document and convert it to a string.</p>
+</div>
+
+<div class="example">
+    {{>datatype-xmlformat-source}}
+</div>

src/datatype/docs/datatype-xmlparse.mustache

@@ -0,0 +1,25 @@
+<style scoped>
+/* custom styles for this example */
+#demo input, #demo label {display:block;}
+#demo fieldset {margin:1em;}
+#demo textarea {width:40em;height:8em;}
+</style>
+
+<div class="intro">
+    <p>The XML module of the DataType Utility allows you to take a string and convert it to an XML document.</p>
+</div>
+
+<div class="example">
+    {{>datatype-xmlparse-source}}
+</div>
+
+<p>To convert a string to an XML document, simply call the <code>parse()</code> function of the DataType.XML class:</p>
+
+```
+YUI().use("datatype-xml", function(Y) {
+    var output = Y.DataType.XML.parse("<myroot><item type='foo'><name>Abc</name><rank>1</rank></item><item type='bar'><name>Def</name><rank>2</rank></item><item type='bat'><name>Ghi</name><rank>3</rank></item></myroot>");
+    // output is an XML document
+});
+```
+
+