YUI 3: DataType [beta]

Getting Started

Include Dependencies

The easiest way to include the source files for DataType and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:

<!-- YUI Seed --> <script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

The YUI instance will automatically pull down DataType's source files and any missing dependencies when the datatype module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.

If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use DataType.

The YUI Instance

Once you have the YUI seed file on your page (yui-min.js), you can create a new YUI instance for your application to use and populate it with the modules you need, specified as the first set of arguments to the use method:

// Create new YUI instance, and populate it with the required modules YUI().use("datatype", function(Y) { // DataType available, and ready for use. });

The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the datatype module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.

For more information on creating instances of YUI and the use method, see the YUI Global object documentation.

Using the DataType Utility

This section describes how to use the DataType Utility in further detail. It contains these subsections:

• Dates
  • Formatting dates
  • Parsing dates
• Numbers
  • Formatting numbers
  • Parsing numbers
• XML
  • Formatting xml
  • Parsing xml
• Y.Parsers shortcuts

Dates

Formatting dates

DataType.Date.format() will output dates as strings formatted using strftime tokens.

alert(Y.DataType.Date.format(new Date(), {format:"%Y-%m-%d %T \n %B, %A"}));

Additionally, DataType.Date.Locale supports the registration of custom locale objects.

Y.DataType.Date.Locale['fr'] = Y.merge(Y.DataType.Date.Locale, { a: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'], A: ['Dimanche', 'Lundi', 'Mardi', 'Mercredi', 'Jeudi', 'Vendredi', 'Samedi'], b: ['Jan', 'Fév', 'Mar', 'Avr', 'Mai', 'Jun', 'Jui', 'Aoû', 'Sep', 'Cct', 'Nov', 'Déc'], B: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'], c: '%a %d %b %Y %T %Z', p: ['', ''], P: ['', ''], x: '%d.%m.%Y', X: '%T' }); alert(Y.DataType.Date.format(new Date(), {format:"%c", locale:"fr"}));

Parsing dates

DataType.Date.parse() accepts any value supported by the JavaScript Date() constructor and converts it to a Date object. Invalid values will return null.

var date1 = Y.DataType.Date.parse("December 17, 1995 03:24:00"); var date2 = Y.DataType.Date.parse(1995,11,17); var date3 = Y.DataType.Date.parse(1995,11,17,3,24,0); var date4 = Y.DataType.Date.parse(948548583);

Numbers

Formatting numbers

JavaScript Number values can be formatted with a variety options into string values using DataType.Number.format().

alert(Y.DataType.Number.format(123123123.176,{ prefix: "&#165;", thousandsSeparator: ".", decimalSeparator: ",", decimalPlaces: 2, suffix: " (YEN)" }));

Parsing numbers

String values can be converted into Number objects with DataType.Number.parse().

var number = Y.DataType.Number.parse("123123");

XML

Formatting XML

DataType.XML.format() will accept an XML document and return its string representation. Note that browsers may slightly differ in the exact string that is returned.

var myString = Y.DataType.XML.format(myXMLDocument);

Parsing XML

DataType.XML.parse() will accept a string representation of XML and return an XML document object. Note that browsers differ in their handling of invalid syntax but will in general return an XML document even under error conditions.

var myXMLDocument = 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>Ghhi</name><rank>3</rank></item></myroot>");

Y.Parsers shortcuts

The functions DataType.Date.parse() and DataType.Number.parse() are registered with the Parsers object for seamless integration with the DataSchema Utility. For dynamic type enforcing when data is being normalized against a schema, simply point to the appropriate function using the built-in shortcut in your schema definition. Parsing your data in this manner is essential if your numerical or date data comes over the wire as JSON, since all the values will be strings.

YUI().use("datatype", "dataschema", function(Y) { var data_in = { "results":[ {"string":"aardvark", "number":"1", "date":"Jan 1, 2001"}, {"string":"bat", "number":"2", "date":"Feb 2, 2002"}, {"string":"camel", "number":"3", "date":"March 3, 2003"} ] }, schema = { resultListLocator: "results", resultFields: [ "string", // needs no parsing {key:"number", parser: "number"}, // converts string values to numbers {key:"date", parser: "date"}] // converts string values to dates }, data_out = Y.DataSchema.JSON.apply(schema, data_in); });

Support & Community