docs/source/Format.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-util.Format'>/**
   2 </span> * @class Ext.util.Format
   3
   4 This class is a centralized place for formatting functions inside the library. It includes
   5 functions to format various different types of data, such as text, dates and numeric values.
   6
   7 __Localization__
   8 This class contains several options for localization. These can be set once the library has loaded,
   9 all calls to the functions from that point will use the locale settings that were specified.
  10 Options include:
  11 - thousandSeparator
  12 - decimalSeparator
  13 - currenyPrecision
  14 - currencySign
  15 - currencyAtEnd
  16 This class also uses the default date format defined here: {@link Ext.date#defaultFormat}.
  17
  18 __Using with renderers__
  19 There are two helper functions that return a new function that can be used in conjunction with
  20 grid renderers:
  21
  22     columns: [{
  23         dataIndex: 'date',
  24         renderer: Ext.util.Format.dateRenderer('Y-m-d')
  25     }, {
  26         dataIndex: 'time',
  27         renderer: Ext.util.Format.numberRenderer('0.000')
  28     }]
  29
  30 Functions that only take a single argument can also be passed directly:
  31     columns: [{
  32         dataIndex: 'cost',
  33         renderer: Ext.util.Format.usMoney
  34     }, {
  35         dataIndex: 'productCode',
  36         renderer: Ext.util.Format.uppercase
  37     }]
  38
  39 __Using with XTemplates__
  40 XTemplates can also directly use Ext.util.Format functions:
  41
  42     new Ext.XTemplate([
  43         'Date: {startDate:date(&quot;Y-m-d&quot;)}',
  44         'Cost: {cost:usMoney}'
  45     ]);
  46
  47  * @markdown
  48  * @singleton
  49  */
  50 (function() {
  51     Ext.ns('Ext.util');
  52
  53     Ext.util.Format = {};
  54     var UtilFormat     = Ext.util.Format,
  55         stripTagsRE    = /&lt;\/?[^&gt;]+&gt;/gi,
  56         stripScriptsRe = /(?:&lt;script.*?&gt;)((\n|\r|.)*?)(?:&lt;\/script&gt;)/ig,
  57         nl2brRe        = /\r?\n/g,
  58
  59         // A RegExp to remove from a number format string, all characters except digits and '.'
  60         formatCleanRe  = /[^\d\.]/g,
  61
  62         // A RegExp to remove from a number format string, all characters except digits and the local decimal separator.
  63         // Created on first use. The local decimal separator character must be initialized for this to be created.
  64         I18NFormatCleanRe;
  65
  66     Ext.apply(UtilFormat, {
  67 <span id='Ext-util.Format-property-thousandSeparator'>        /**
  68 </span>         * @type String
  69          * @property thousandSeparator
  70          * &lt;p&gt;The character that the {@link #number} function uses as a thousand separator.&lt;/p&gt;
  71          * &lt;p&gt;This defaults to &lt;code&gt;,&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
  72          */
  73         thousandSeparator: ',',
  74
  75 <span id='Ext-util.Format-property-decimalSeparator'>        /**
  76 </span>         * @type String
  77          * @property decimalSeparator
  78          * &lt;p&gt;The character that the {@link #number} function uses as a decimal point.&lt;/p&gt;
  79          * &lt;p&gt;This defaults to &lt;code&gt;.&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
  80          */
  81         decimalSeparator: '.',
  82
  83 <span id='Ext-util.Format-property-currencyPrecision'>        /**
  84 </span>         * @type Number
  85          * @property currencyPrecision
  86          * &lt;p&gt;The number of decimal places that the {@link #currency} function displays.&lt;/p&gt;
  87          * &lt;p&gt;This defaults to &lt;code&gt;2&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
  88          */
  89         currencyPrecision: 2,
  90
  91 <span id='Ext-util.Format-property-currencySign'>        /**
  92 </span>         * @type String
  93          * @property currencySign
  94          * &lt;p&gt;The currency sign that the {@link #currency} function displays.&lt;/p&gt;
  95          * &lt;p&gt;This defaults to &lt;code&gt;$&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
  96          */
  97         currencySign: '$',
  98
  99 <span id='Ext-util.Format-property-currencyAtEnd'>        /**
 100 </span>         * @type Boolean
 101          * @property currencyAtEnd
 102          * &lt;p&gt;This may be set to &lt;code&gt;true&lt;/code&gt; to make the {@link #currency} function
 103          * append the currency sign to the formatted value.&lt;/p&gt;
 104          * &lt;p&gt;This defaults to &lt;code&gt;false&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
 105          */
 106         currencyAtEnd: false,
 107
 108 <span id='Ext-util.Format-method-undef'>        /**
 109 </span>         * Checks a reference and converts it to empty string if it is undefined
 110          * @param {Mixed} value Reference to check
 111          * @return {Mixed} Empty string if converted, otherwise the original value
 112          */
 113         undef : function(value) {
 114             return value !== undefined ? value : &quot;&quot;;
 115         },
 116
 117 <span id='Ext-util.Format-method-defaultValue'>        /**
 118 </span>         * Checks a reference and converts it to the default value if it's empty
 119          * @param {Mixed} value Reference to check
 120          * @param {String} defaultValue The value to insert of it's undefined (defaults to &quot;&quot;)
 121          * @return {String}
 122          */
 123         defaultValue : function(value, defaultValue) {
 124             return value !== undefined &amp;&amp; value !== '' ? value : defaultValue;
 125         },
 126
 127 <span id='Ext-util.Format-method-substr'>        /**
 128 </span>         * Returns a substring from within an original string
 129          * @param {String} value The original text
 130          * @param {Number} start The start index of the substring
 131          * @param {Number} length The length of the substring
 132          * @return {String} The substring
 133          */
 134         substr : function(value, start, length) {
 135             return String(value).substr(start, length);
 136         },
 137
 138 <span id='Ext-util.Format-method-lowercase'>        /**
 139 </span>         * Converts a string to all lower case letters
 140          * @param {String} value The text to convert
 141          * @return {String} The converted text
 142          */
 143         lowercase : function(value) {
 144             return String(value).toLowerCase();
 145         },
 146
 147 <span id='Ext-util.Format-method-uppercase'>        /**
 148 </span>         * Converts a string to all upper case letters
 149          * @param {String} value The text to convert
 150          * @return {String} The converted text
 151          */
 152         uppercase : function(value) {
 153             return String(value).toUpperCase();
 154         },
 155
 156 <span id='Ext-util.Format-method-usMoney'>        /**
 157 </span>         * Format a number as US currency
 158          * @param {Number/String} value The numeric value to format
 159          * @return {String} The formatted currency string
 160          */
 161         usMoney : function(v) {
 162             return UtilFormat.currency(v, '$', 2);
 163         },
 164
 165 <span id='Ext-util.Format-method-currency'>        /**
 166 </span>         * Format a number as a currency
 167          * @param {Number/String} value The numeric value to format
 168          * @param {String} sign The currency sign to use (defaults to {@link #currencySign})
 169          * @param {Number} decimals The number of decimals to use for the currency (defaults to {@link #currencyPrecision})
 170          * @param {Boolean} end True if the currency sign should be at the end of the string (defaults to {@link #currencyAtEnd})
 171          * @return {String} The formatted currency string
 172          */
 173         currency: function(v, currencySign, decimals, end) {
 174             var negativeSign = '',
 175                 format = &quot;,0&quot;,
 176                 i = 0;
 177             v = v - 0;
 178             if (v &lt; 0) {
 179                 v = -v;
 180                 negativeSign = '-';
 181             }
 182             decimals = decimals || UtilFormat.currencyPrecision;
 183             format += format + (decimals &gt; 0 ? '.' : '');
 184             for (; i &lt; decimals; i++) {
 185                 format += '0';
 186             }
 187             v = UtilFormat.number(v, format);
 188             if ((end || UtilFormat.currencyAtEnd) === true) {
 189                 return Ext.String.format(&quot;{0}{1}{2}&quot;, negativeSign, v, currencySign || UtilFormat.currencySign);
 190             } else {
 191                 return Ext.String.format(&quot;{0}{1}{2}&quot;, negativeSign, currencySign || UtilFormat.currencySign, v);
 192             }
 193         },
 194
 195 <span id='Ext-util.Format-method-date'>        /**
 196 </span>         * Formats the passed date using the specified format pattern.
 197          * @param {String/Date} value The value to format. If a string is passed, it is converted to a Date by the Javascript
 198          * Date object's &lt;a href=&quot;http://www.w3schools.com/jsref/jsref_parse.asp&quot;&gt;parse()&lt;/a&gt; method.
 199          * @param {String} format (Optional) Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
 200          * @return {String} The formatted date string.
 201          */
 202         date: function(v, format) {
 203             if (!v) {
 204                 return &quot;&quot;;
 205             }
 206             if (!Ext.isDate(v)) {
 207                 v = new Date(Date.parse(v));
 208             }
 209             return Ext.Date.dateFormat(v, format || Ext.Date.defaultFormat);
 210         },
 211
 212 <span id='Ext-util.Format-method-dateRenderer'>        /**
 213 </span>         * Returns a date rendering function that can be reused to apply a date format multiple times efficiently
 214          * @param {String} format Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
 215          * @return {Function} The date formatting function
 216          */
 217         dateRenderer : function(format) {
 218             return function(v) {
 219                 return UtilFormat.date(v, format);
 220             };
 221         },
 222
 223 <span id='Ext-util.Format-method-stripTags'>        /**
 224 </span>         * Strips all HTML tags
 225          * @param {Mixed} value The text from which to strip tags
 226          * @return {String} The stripped text
 227          */
 228         stripTags : function(v) {
 229             return !v ? v : String(v).replace(stripTagsRE, &quot;&quot;);
 230         },
 231
 232 <span id='Ext-util.Format-method-stripScripts'>        /**
 233 </span>         * Strips all script tags
 234          * @param {Mixed} value The text from which to strip script tags
 235          * @return {String} The stripped text
 236          */
 237         stripScripts : function(v) {
 238             return !v ? v : String(v).replace(stripScriptsRe, &quot;&quot;);
 239         },
 240
 241 <span id='Ext-util.Format-method-fileSize'>        /**
 242 </span>         * Simple format for a file size (xxx bytes, xxx KB, xxx MB)
 243          * @param {Number/String} size The numeric value to format
 244          * @return {String} The formatted file size
 245          */
 246         fileSize : function(size) {
 247             if (size &lt; 1024) {
 248                 return size + &quot; bytes&quot;;
 249             } else if (size &lt; 1048576) {
 250                 return (Math.round(((size*10) / 1024))/10) + &quot; KB&quot;;
 251             } else {
 252                 return (Math.round(((size*10) / 1048576))/10) + &quot; MB&quot;;
 253             }
 254         },
 255
 256 <span id='Ext-util.Format-method-math'>        /**
 257 </span>         * It does simple math for use in a template, for example:&lt;pre&gt;&lt;code&gt;
 258          * var tpl = new Ext.Template('{value} * 10 = {value:math(&quot;* 10&quot;)}');
 259          * &lt;/code&gt;&lt;/pre&gt;
 260          * @return {Function} A function that operates on the passed value.
 261          */
 262         math : function(){
 263             var fns = {};
 264
 265             return function(v, a){
 266                 if (!fns[a]) {
 267                     fns[a] = Ext.functionFactory('v', 'return v ' + a + ';');
 268                 }
 269                 return fns[a](v);
 270             };
 271         }(),
 272
 273 <span id='Ext-util.Format-method-round'>        /**
 274 </span>         * Rounds the passed number to the required decimal precision.
 275          * @param {Number/String} value The numeric value to round.
 276          * @param {Number} precision The number of decimal places to which to round the first parameter's value.
 277          * @return {Number} The rounded value.
 278          */
 279         round : function(value, precision) {
 280             var result = Number(value);
 281             if (typeof precision == 'number') {
 282                 precision = Math.pow(10, precision);
 283                 result = Math.round(value * precision) / precision;
 284             }
 285             return result;
 286         },
 287
 288 <span id='Ext-util.Format-method-number'>        /**
 289 </span>         * &lt;p&gt;Formats the passed number according to the passed format string.&lt;/p&gt;
 290          * &lt;p&gt;The number of digits after the decimal separator character specifies the number of
 291          * decimal places in the resulting string. The &lt;u&gt;local-specific&lt;/u&gt; decimal character is used in the result.&lt;/p&gt;
 292          * &lt;p&gt;The &lt;i&gt;presence&lt;/i&gt; of a thousand separator character in the format string specifies that
 293          * the &lt;u&gt;locale-specific&lt;/u&gt; thousand separator (if any) is inserted separating thousand groups.&lt;/p&gt;
 294          * &lt;p&gt;By default, &quot;,&quot; is expected as the thousand separator, and &quot;.&quot; is expected as the decimal separator.&lt;/p&gt;
 295          * &lt;p&gt;&lt;b&gt;New to Ext4&lt;/b&gt;&lt;/p&gt;
 296          * &lt;p&gt;Locale-specific characters are always used in the formatted output when inserting
 297          * thousand and decimal separators.&lt;/p&gt;
 298          * &lt;p&gt;The format string must specify separator characters according to US/UK conventions (&quot;,&quot; as the
 299          * thousand separator, and &quot;.&quot; as the decimal separator)&lt;/p&gt;
 300          * &lt;p&gt;To allow specification of format strings according to local conventions for separator characters, add
 301          * the string &lt;code&gt;/i&lt;/code&gt; to the end of the format string.&lt;/p&gt;
 302          * &lt;div style=&quot;margin-left:40px&quot;&gt;examples (123456.789):
 303          * &lt;div style=&quot;margin-left:10px&quot;&gt;
 304          * 0 - (123456) show only digits, no precision&lt;br&gt;
 305          * 0.00 - (123456.78) show only digits, 2 precision&lt;br&gt;
 306          * 0.0000 - (123456.7890) show only digits, 4 precision&lt;br&gt;
 307          * 0,000 - (123,456) show comma and digits, no precision&lt;br&gt;
 308          * 0,000.00 - (123,456.78) show comma and digits, 2 precision&lt;br&gt;
 309          * 0,0.00 - (123,456.78) shortcut method, show comma and digits, 2 precision&lt;br&gt;
 310          * To allow specification of the formatting string using UK/US grouping characters (,) and decimal (.) for international numbers, add /i to the end.
 311          * For example: 0.000,00/i
 312          * &lt;/div&gt;&lt;/div&gt;
 313          * @param {Number} v The number to format.
 314          * @param {String} format The way you would like to format this text.
 315          * @return {String} The formatted number.
 316          */
 317         number:
 318             function(v, formatString) {
 319             if (!formatString) {
 320                 return v;
 321             }
 322             v = Ext.Number.from(v, NaN);
 323             if (isNaN(v)) {
 324                 return '';
 325             }
 326             var comma = UtilFormat.thousandSeparator,
 327                 dec   = UtilFormat.decimalSeparator,
 328                 i18n  = false,
 329                 neg   = v &lt; 0,
 330                 hasComma,
 331                 psplit;
 332
 333             v = Math.abs(v);
 334
 335             // The &quot;/i&quot; suffix allows caller to use a locale-specific formatting string.
 336             // Clean the format string by removing all but numerals and the decimal separator.
 337             // Then split the format string into pre and post decimal segments according to *what* the
 338             // decimal separator is. If they are specifying &quot;/i&quot;, they are using the local convention in the format string.
 339             if (formatString.substr(formatString.length - 2) == '/i') {
 340                 if (!I18NFormatCleanRe) {
 341                     I18NFormatCleanRe = new RegExp('[^\\d\\' + UtilFormat.decimalSeparator + ']','g');
 342                 }
 343                 formatString = formatString.substr(0, formatString.length - 2);
 344                 i18n   = true;
 345                 hasComma = formatString.indexOf(comma) != -1;
 346                 psplit = formatString.replace(I18NFormatCleanRe, '').split(dec);
 347             } else {
 348                 hasComma = formatString.indexOf(',') != -1;
 349                 psplit = formatString.replace(formatCleanRe, '').split('.');
 350             }
 351
 352             if (1 &lt; psplit.length) {
 353                 v = v.toFixed(psplit[1].length);
 354             } else if(2 &lt; psplit.length) {
 355                 //&lt;debug&gt;
 356                 Ext.Error.raise({
 357                     sourceClass: &quot;Ext.util.Format&quot;,
 358                     sourceMethod: &quot;number&quot;,
 359                     value: v,
 360                     formatString: formatString,
 361                     msg: &quot;Invalid number format, should have no more than 1 decimal&quot;
 362                 });
 363                 //&lt;/debug&gt;
 364             } else {
 365                 v = v.toFixed(0);
 366             }
 367
 368             var fnum = v.toString();
 369
 370             psplit = fnum.split('.');
 371
 372             if (hasComma) {
 373                 var cnum = psplit[0],
 374                     parr = [],
 375                     j    = cnum.length,
 376                     m    = Math.floor(j / 3),
 377                     n    = cnum.length % 3 || 3,
 378                     i;
 379
 380                 for (i = 0; i &lt; j; i += n) {
 381                     if (i !== 0) {
 382                         n = 3;
 383                     }
 384
 385                     parr[parr.length] = cnum.substr(i, n);
 386                     m -= 1;
 387                 }
 388                 fnum = parr.join(comma);
 389                 if (psplit[1]) {
 390                     fnum += dec + psplit[1];
 391                 }
 392             } else {
 393                 if (psplit[1]) {
 394                     fnum = psplit[0] + dec + psplit[1];
 395                 }
 396             }
 397
 398             return (neg ? '-' : '') + formatString.replace(/[\d,?\.?]+/, fnum);
 399         },
 400
 401 <span id='Ext-util.Format-method-numberRenderer'>        /**
 402 </span>         * Returns a number rendering function that can be reused to apply a number format multiple times efficiently
 403          * @param {String} format Any valid number format string for {@link #number}
 404          * @return {Function} The number formatting function
 405          */
 406         numberRenderer : function(format) {
 407             return function(v) {
 408                 return UtilFormat.number(v, format);
 409             };
 410         },
 411
 412 <span id='Ext-util.Format-method-plural'>        /**
 413 </span>         * Selectively do a plural form of a word based on a numeric value. For example, in a template,
 414          * {commentCount:plural(&quot;Comment&quot;)}  would result in &quot;1 Comment&quot; if commentCount was 1 or would be &quot;x Comments&quot;
 415          * if the value is 0 or greater than 1.
 416          * @param {Number} value The value to compare against
 417          * @param {String} singular The singular form of the word
 418          * @param {String} plural (optional) The plural form of the word (defaults to the singular with an &quot;s&quot;)
 419          */
 420         plural : function(v, s, p) {
 421             return v +' ' + (v == 1 ? s : (p ? p : s+'s'));
 422         },
 423
 424 <span id='Ext-util.Format-method-nl2br'>        /**
 425 </span>         * Converts newline characters to the HTML tag &amp;lt;br/&gt;
 426          * @param {String} The string value to format.
 427          * @return {String} The string with embedded &amp;lt;br/&gt; tags in place of newlines.
 428          */
 429         nl2br : function(v) {
 430             return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '&lt;br/&gt;');
 431         },
 432
 433 <span id='Ext-util.Format-property-capitalize'>        /**
 434 </span>         * Capitalize the given string. See {@link Ext.String#capitalize}.
 435          */
 436         capitalize: Ext.String.capitalize,
 437
 438 <span id='Ext-util.Format-property-ellipsis'>        /**
 439 </span>         * Truncate a string and add an ellipsis ('...') to the end if it exceeds the specified length.
 440          * See {@link Ext.String#ellipsis}.
 441          */
 442         ellipsis: Ext.String.ellipsis,
 443
 444 <span id='Ext-util.Format-property-format'>        /**
 445 </span>         * Formats to a string. See {@link Ext.String#format}
 446          */
 447         format: Ext.String.format,
 448
 449 <span id='Ext-util.Format-property-htmlDecode'>        /**
 450 </span>         * Convert certain characters (&amp;, &lt;, &gt;, and ') from their HTML character equivalents.
 451          * See {@link Ext.string#htmlDecode}.
 452          */
 453         htmlDecode: Ext.String.htmlDecode,
 454
 455 <span id='Ext-util.Format-property-htmlEncode'>        /**
 456 </span>         * Convert certain characters (&amp;, &lt;, &gt;, and ') to their HTML character equivalents for literal display in web pages.
 457          * See {@link Ext.String#htmlEncode}.
 458          */
 459         htmlEncode: Ext.String.htmlEncode,
 460
 461 <span id='Ext-util.Format-property-leftPad'>        /**
 462 </span>         * Adds left padding to a string. See {@link Ext.String#leftPad}
 463          */
 464         leftPad: Ext.String.leftPad,
 465
 466 <span id='Ext-util.Format-property-trim'>        /**
 467 </span>         * Trims any whitespace from either side of a string. See {@link Ext.String#trim}.
 468          */
 469         trim : Ext.String.trim,
 470
 471 <span id='Ext-util.Format-method-parseBox'>        /**
 472 </span>         * Parses a number or string representing margin sizes into an object. Supports CSS-style margin declarations
 473          * (e.g. 10, &quot;10&quot;, &quot;10 10&quot;, &quot;10 10 10&quot; and &quot;10 10 10 10&quot; are all valid options and would return the same result)
 474          * @param {Number|String} v The encoded margins
 475          * @return {Object} An object with margin sizes for top, right, bottom and left
 476          */
 477         parseBox : function(box) {
 478             if (Ext.isNumber(box)) {
 479                 box = box.toString();
 480             }
 481             var parts  = box.split(' '),
 482                 ln = parts.length;
 483
 484             if (ln == 1) {
 485                 parts[1] = parts[2] = parts[3] = parts[0];
 486             }
 487             else if (ln == 2) {
 488                 parts[2] = parts[0];
 489                 parts[3] = parts[1];
 490             }
 491             else if (ln == 3) {
 492                 parts[3] = parts[1];
 493             }
 494
 495             return {
 496                 top   :parseInt(parts[0], 10) || 0,
 497                 right :parseInt(parts[1], 10) || 0,
 498                 bottom:parseInt(parts[2], 10) || 0,
 499                 left  :parseInt(parts[3], 10) || 0
 500             };
 501         },
 502
 503 <span id='Ext-util.Format-method-escapeRegex'>        /**
 504 </span>         * Escapes the passed string for use in a regular expression
 505          * @param {String} str
 506          * @return {String}
 507          */
 508         escapeRegex : function(s) {
 509             return s.replace(/([\-.*+?\^${}()|\[\]\/\\])/g, &quot;\\$1&quot;);
 510         }
 511     });
 512 })();
 513 </pre></pre></body></html>