Toke

By Doron Horwitz

Description

Use a single datetime token syntax throughout your Javascript project, irrespective of any 3rd party date-related library you may use. Toke uses a single token syntax and allows you to output a version which can be understood by the different libraries in your project.

This allows you to set a single datetime format in a settings file and then ensure that any changes you make it to will be reflected across the whole project if you are using different libraries for date formatting.

Toke uses the datetime formatting tokens of the Moment.js library as its universal token syntax.

For example, say you are using Datejs for outputting a date in a particular format, but you also need your JqueryUI datepicker to display its date with the exact same format. So if the format you wanted was, in Moment.js syntax, DD-MMMM-YYYY, you would set it globally:

globalFormat = "DD-MMMM-YYYY";

Then to specify your jQueryUI's datepickers format, you would do:

$( ".selector" ).datepicker({ dateFormat: Toke.convert(globalFormat,"jqueryui") });

And to output a date using Datejs, you would do:

var myDate        = Date(),
    formattedDate = myDate.toString(Toke.convert(globalFormat,"datejs"));

alert(formattedDate);

Installation

Include the Javascript:

<script src="toke.js" type="text/javascript"></script>

Usage

The script makes the following function available

Toke.convert(originalFormatString, libraryName, [replaceUntranslatableTokens, [translateEscapeCharacters]])

The function takes the following arguments:

• originalFormatString
  • Type: string
  • Required: yes
  • Description: the format string using Moment.js syntax. See here for the available tokens.
• libraryName
  • Type: string
  • Required: yes
  • Description: the library into whose syntax to convert the originalFormatString. See the Support section for the available destination library formats. If libraryName refers to a library that is not supported, an Error will be thrown.
• replaceUntranslatableTokens
  • Type: boolean
  • Required: no
  • Default: false
  • Description: if true the tokens that do not have a direct translation from the Moment.js syntax are replaced with a noTranslation marker. If false the original Moment.js token appears in the final string.
• translateEscapeCharacters
  • Type: boolean
  • Required: no
  • Default: true
  • Description: Moment.js uses the [ ] escape characters to deliniate that a token should not be processed as a token but rather as a string. If translateEscapeCharacters is set to true then the escape characters will be removed (or replaced with the escape characters of the destination library) in the output string, if false they will appear in the final string.
• includeTokenPrefixesAndSuffixes
  • Type: boolean
  • Required: no
  • Default: true
  • Description: If set to false token prefixes and suffixes will not be output before and after tokens.

Examples

Toke.convert('DD MMMM YYYY, HH:mm:ss','sugar')

Will output {dd} {Month} {yyyy}, {HH}:{mm}:{ss}

Toke.convert('DD MMMM YYYY, HH:mm:ss','jqueryui')

Will output dd MM yy, HH:mm:ss, since jQueryUI does not support time token elements.

Toke.convert('DD MMMM YYYY, HH:mm:ss','jqueryui', true)

Will output dd MM yy, ::, since jQueryUI does not support time token elements, replaceUntranslatableTokens is set to true and the noTranslation token is specified as an empty string.

Toke.convert('DD MMMM [YYYY], HH:mm:ss','datejs')

Note that YYYY should translate to a yyyy Datejs token but the above will output dd MMMM YYYY, HH:mm:ss, since [ ] deliniates escape characters in Moment.js' token syntax and Datejs does not have an escapePrefix or escapeSuffix and translateExcapeCharacters defaults to true.

Support

Toke currently supports conversion into the syntax of the following libraries:

• Sugar
  • See the section on dates
  • libraryName attribute: sugar
• jQueryUI
  • Support for the $.datepicker.formatDate() and $.datepicker.parseDate() functions.
  • libraryName attribute: jqueryui
• Datejs
  • See the section on toString() FormatSpecifiers
  • libraryName attribute: datejs
• Steven Levithan's Date Format
  • libraryName attribute: stevenlevithan
• PHP (though php.js is more relevant)
  • Support for strftime() and strptime()
  • libraryName attribute: php
• Moment.js
  • Obviously.
  • Will ignore replaceUntranslatableTokens and translateEscapeCharacters and output the input format string untouched.
  • libraryName attribute: momentjs
• More to come...

Extending

If you need Toke to support a library it does not currently support, it is possible to add your own custom token dictionary lookup before or after Toke is included. To add a custom token lookup after Toke is included use the Toke.addCustomTokenLookup function. To add a custom token lookup before Toke is included, see the example custom_tokens.js.

License

Toke is covered by the BSD New License

Copyright (c) 2013, Doron Horwitz All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• The name of Doron Horwitz may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.