docs/source/Format.html

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