/ext-4.0.7/docs/source/Format.html
https://bitbucket.org/srogerf/javascript · HTML · 547 lines · 491 code · 56 blank · 0 comment · 0 complexity · 22a866756aaba225d7001546d2111403 MD5 · raw file
- <!DOCTYPE html>
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>The source code</title>
- <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
- <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
- <style type="text/css">
- .highlight { display: block; background-color: #ddd; }
- </style>
- <script type="text/javascript">
- function highlight() {
- document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
- }
- </script>
- </head>
- <body onload="prettyPrint(); highlight();">
- <pre class="prettyprint lang-js"><span id='Ext-util-Format'>/**
- </span> * @class Ext.util.Format
- This class is a centralized place for formatting functions. It includes
- functions to format various different types of data, such as text, dates and numeric values.
- __Localization__
- This class contains several options for localization. These can be set once the library has loaded,
- all calls to the functions from that point will use the locale settings that were specified.
- Options include:
- - thousandSeparator
- - decimalSeparator
- - currenyPrecision
- - currencySign
- - currencyAtEnd
- This class also uses the default date format defined here: {@link Ext.Date#defaultFormat}.
- __Using with renderers__
- There are two helper functions that return a new function that can be used in conjunction with
- grid renderers:
- columns: [{
- dataIndex: 'date',
- renderer: Ext.util.Format.dateRenderer('Y-m-d')
- }, {
- dataIndex: 'time',
- renderer: Ext.util.Format.numberRenderer('0.000')
- }]
- Functions that only take a single argument can also be passed directly:
- columns: [{
- dataIndex: 'cost',
- renderer: Ext.util.Format.usMoney
- }, {
- dataIndex: 'productCode',
- renderer: Ext.util.Format.uppercase
- }]
- __Using with XTemplates__
- XTemplates can also directly use Ext.util.Format functions:
- new Ext.XTemplate([
- 'Date: {startDate:date("Y-m-d")}',
- 'Cost: {cost:usMoney}'
- ]);
- * @markdown
- * @singleton
- */
- (function() {
- Ext.ns('Ext.util');
- Ext.util.Format = {};
- var UtilFormat = Ext.util.Format,
- stripTagsRE = /<\/?[^>]+>/gi,
- stripScriptsRe = /(?:<script.*?>)((\n|\r|.)*?)(?:<\/script>)/ig,
- nl2brRe = /\r?\n/g,
- // A RegExp to remove from a number format string, all characters except digits and '.'
- formatCleanRe = /[^\d\.]/g,
- // A RegExp to remove from a number format string, all characters except digits and the local decimal separator.
- // Created on first use. The local decimal separator character must be initialized for this to be created.
- I18NFormatCleanRe;
- Ext.apply(UtilFormat, {
- <span id='Ext-util-Format-property-thousandSeparator'> /**
- </span> * @property {String} thousandSeparator
- * <p>The character that the {@link #number} function uses as a thousand separator.</p>
- * <p>This may be overridden in a locale file.</p>
- */
- thousandSeparator: ',',
- <span id='Ext-util-Format-property-decimalSeparator'> /**
- </span> * @property {String} decimalSeparator
- * <p>The character that the {@link #number} function uses as a decimal point.</p>
- * <p>This may be overridden in a locale file.</p>
- */
- decimalSeparator: '.',
- <span id='Ext-util-Format-property-currencyPrecision'> /**
- </span> * @property {Number} currencyPrecision
- * <p>The number of decimal places that the {@link #currency} function displays.</p>
- * <p>This may be overridden in a locale file.</p>
- */
- currencyPrecision: 2,
- <span id='Ext-util-Format-property-currencySign'> /**
- </span> * @property {String} currencySign
- * <p>The currency sign that the {@link #currency} function displays.</p>
- * <p>This may be overridden in a locale file.</p>
- */
- currencySign: '$',
- <span id='Ext-util-Format-property-currencyAtEnd'> /**
- </span> * @property {Boolean} currencyAtEnd
- * <p>This may be set to <code>true</code> to make the {@link #currency} function
- * append the currency sign to the formatted value.</p>
- * <p>This may be overridden in a locale file.</p>
- */
- currencyAtEnd: false,
- <span id='Ext-util-Format-method-undef'> /**
- </span> * Checks a reference and converts it to empty string if it is undefined
- * @param {Object} value Reference to check
- * @return {Object} Empty string if converted, otherwise the original value
- */
- undef : function(value) {
- return value !== undefined ? value : "";
- },
- <span id='Ext-util-Format-method-defaultValue'> /**
- </span> * Checks a reference and converts it to the default value if it's empty
- * @param {Object} value Reference to check
- * @param {String} defaultValue The value to insert of it's undefined (defaults to "")
- * @return {String}
- */
- defaultValue : function(value, defaultValue) {
- return value !== undefined && value !== '' ? value : defaultValue;
- },
- <span id='Ext-util-Format-method-substr'> /**
- </span> * Returns a substring from within an original string
- * @param {String} value The original text
- * @param {Number} start The start index of the substring
- * @param {Number} length The length of the substring
- * @return {String} The substring
- */
- substr : function(value, start, length) {
- return String(value).substr(start, length);
- },
- <span id='Ext-util-Format-method-lowercase'> /**
- </span> * Converts a string to all lower case letters
- * @param {String} value The text to convert
- * @return {String} The converted text
- */
- lowercase : function(value) {
- return String(value).toLowerCase();
- },
- <span id='Ext-util-Format-method-uppercase'> /**
- </span> * Converts a string to all upper case letters
- * @param {String} value The text to convert
- * @return {String} The converted text
- */
- uppercase : function(value) {
- return String(value).toUpperCase();
- },
- <span id='Ext-util-Format-method-usMoney'> /**
- </span> * Format a number as US currency
- * @param {Number/String} value The numeric value to format
- * @return {String} The formatted currency string
- */
- usMoney : function(v) {
- return UtilFormat.currency(v, '$', 2);
- },
- <span id='Ext-util-Format-method-currency'> /**
- </span> * Format a number as a currency
- * @param {Number/String} value The numeric value to format
- * @param {String} sign The currency sign to use (defaults to {@link #currencySign})
- * @param {Number} decimals The number of decimals to use for the currency (defaults to {@link #currencyPrecision})
- * @param {Boolean} end True if the currency sign should be at the end of the string (defaults to {@link #currencyAtEnd})
- * @return {String} The formatted currency string
- */
- currency: function(v, currencySign, decimals, end) {
- var negativeSign = '',
- format = ",0",
- i = 0;
- v = v - 0;
- if (v < 0) {
- v = -v;
- negativeSign = '-';
- }
- decimals = decimals || UtilFormat.currencyPrecision;
- format += format + (decimals > 0 ? '.' : '');
- for (; i < decimals; i++) {
- format += '0';
- }
- v = UtilFormat.number(v, format);
- if ((end || UtilFormat.currencyAtEnd) === true) {
- return Ext.String.format("{0}{1}{2}", negativeSign, v, currencySign || UtilFormat.currencySign);
- } else {
- return Ext.String.format("{0}{1}{2}", negativeSign, currencySign || UtilFormat.currencySign, v);
- }
- },
- <span id='Ext-util-Format-method-date'> /**
- </span> * Formats the passed date using the specified format pattern.
- * @param {String/Date} value The value to format. If a string is passed, it is converted to a Date by the Javascript
- * Date object's <a href="http://www.w3schools.com/jsref/jsref_parse.asp">parse()</a> method.
- * @param {String} format (Optional) Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
- * @return {String} The formatted date string.
- */
- date: function(v, format) {
- if (!v) {
- return "";
- }
- if (!Ext.isDate(v)) {
- v = new Date(Date.parse(v));
- }
- return Ext.Date.dateFormat(v, format || Ext.Date.defaultFormat);
- },
- <span id='Ext-util-Format-method-dateRenderer'> /**
- </span> * Returns a date rendering function that can be reused to apply a date format multiple times efficiently
- * @param {String} format Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
- * @return {Function} The date formatting function
- */
- dateRenderer : function(format) {
- return function(v) {
- return UtilFormat.date(v, format);
- };
- },
- <span id='Ext-util-Format-method-stripTags'> /**
- </span> * Strips all HTML tags
- * @param {Object} value The text from which to strip tags
- * @return {String} The stripped text
- */
- stripTags : function(v) {
- return !v ? v : String(v).replace(stripTagsRE, "");
- },
- <span id='Ext-util-Format-method-stripScripts'> /**
- </span> * Strips all script tags
- * @param {Object} value The text from which to strip script tags
- * @return {String} The stripped text
- */
- stripScripts : function(v) {
- return !v ? v : String(v).replace(stripScriptsRe, "");
- },
- <span id='Ext-util-Format-method-fileSize'> /**
- </span> * Simple format for a file size (xxx bytes, xxx KB, xxx MB)
- * @param {Number/String} size The numeric value to format
- * @return {String} The formatted file size
- */
- fileSize : function(size) {
- if (size < 1024) {
- return size + " bytes";
- } else if (size < 1048576) {
- return (Math.round(((size*10) / 1024))/10) + " KB";
- } else {
- return (Math.round(((size*10) / 1048576))/10) + " MB";
- }
- },
- <span id='Ext-util-Format-method-math'> /**
- </span> * It does simple math for use in a template, for example:<pre><code>
- * var tpl = new Ext.Template('{value} * 10 = {value:math("* 10")}');
- * </code></pre>
- * @return {Function} A function that operates on the passed value.
- * @method
- */
- math : function(){
- var fns = {};
- return function(v, a){
- if (!fns[a]) {
- fns[a] = Ext.functionFactory('v', 'return v ' + a + ';');
- }
- return fns[a](v);
- };
- }(),
- <span id='Ext-util-Format-method-round'> /**
- </span> * Rounds the passed number to the required decimal precision.
- * @param {Number/String} value The numeric value to round.
- * @param {Number} precision The number of decimal places to which to round the first parameter's value.
- * @return {Number} The rounded value.
- */
- round : function(value, precision) {
- var result = Number(value);
- if (typeof precision == 'number') {
- precision = Math.pow(10, precision);
- result = Math.round(value * precision) / precision;
- }
- return result;
- },
- <span id='Ext-util-Format-method-number'> /**
- </span> * <p>Formats the passed number according to the passed format string.</p>
- * <p>The number of digits after the decimal separator character specifies the number of
- * decimal places in the resulting string. The <u>local-specific</u> decimal character is used in the result.</p>
- * <p>The <i>presence</i> of a thousand separator character in the format string specifies that
- * the <u>locale-specific</u> thousand separator (if any) is inserted separating thousand groups.</p>
- * <p>By default, "," is expected as the thousand separator, and "." is expected as the decimal separator.</p>
- * <p><b>New to Ext JS 4</b></p>
- * <p>Locale-specific characters are always used in the formatted output when inserting
- * thousand and decimal separators.</p>
- * <p>The format string must specify separator characters according to US/UK conventions ("," as the
- * thousand separator, and "." as the decimal separator)</p>
- * <p>To allow specification of format strings according to local conventions for separator characters, add
- * the string <code>/i</code> to the end of the format string.</p>
- * <div style="margin-left:40px">examples (123456.789):
- * <div style="margin-left:10px">
- * 0 - (123456) show only digits, no precision<br>
- * 0.00 - (123456.78) show only digits, 2 precision<br>
- * 0.0000 - (123456.7890) show only digits, 4 precision<br>
- * 0,000 - (123,456) show comma and digits, no precision<br>
- * 0,000.00 - (123,456.78) show comma and digits, 2 precision<br>
- * 0,0.00 - (123,456.78) shortcut method, show comma and digits, 2 precision<br>
- * To allow specification of the formatting string using UK/US grouping characters (,) and decimal (.) for international numbers, add /i to the end.
- * For example: 0.000,00/i
- * </div></div>
- * @param {Number} v The number to format.
- * @param {String} format The way you would like to format this text.
- * @return {String} The formatted number.
- */
- number: function(v, formatString) {
- if (!formatString) {
- return v;
- }
- v = Ext.Number.from(v, NaN);
- if (isNaN(v)) {
- return '';
- }
- var comma = UtilFormat.thousandSeparator,
- dec = UtilFormat.decimalSeparator,
- i18n = false,
- neg = v < 0,
- hasComma,
- psplit;
- v = Math.abs(v);
- // The "/i" suffix allows caller to use a locale-specific formatting string.
- // Clean the format string by removing all but numerals and the decimal separator.
- // Then split the format string into pre and post decimal segments according to *what* the
- // decimal separator is. If they are specifying "/i", they are using the local convention in the format string.
- if (formatString.substr(formatString.length - 2) == '/i') {
- if (!I18NFormatCleanRe) {
- I18NFormatCleanRe = new RegExp('[^\\d\\' + UtilFormat.decimalSeparator + ']','g');
- }
- formatString = formatString.substr(0, formatString.length - 2);
- i18n = true;
- hasComma = formatString.indexOf(comma) != -1;
- psplit = formatString.replace(I18NFormatCleanRe, '').split(dec);
- } else {
- hasComma = formatString.indexOf(',') != -1;
- psplit = formatString.replace(formatCleanRe, '').split('.');
- }
- if (1 < psplit.length) {
- v = v.toFixed(psplit[1].length);
- } else if(2 < psplit.length) {
- //<debug>
- Ext.Error.raise({
- sourceClass: "Ext.util.Format",
- sourceMethod: "number",
- value: v,
- formatString: formatString,
- msg: "Invalid number format, should have no more than 1 decimal"
- });
- //</debug>
- } else {
- v = v.toFixed(0);
- }
- var fnum = v.toString();
- psplit = fnum.split('.');
- if (hasComma) {
- var cnum = psplit[0],
- parr = [],
- j = cnum.length,
- m = Math.floor(j / 3),
- n = cnum.length % 3 || 3,
- i;
- for (i = 0; i < j; i += n) {
- if (i !== 0) {
- n = 3;
- }
- parr[parr.length] = cnum.substr(i, n);
- m -= 1;
- }
- fnum = parr.join(comma);
- if (psplit[1]) {
- fnum += dec + psplit[1];
- }
- } else {
- if (psplit[1]) {
- fnum = psplit[0] + dec + psplit[1];
- }
- }
- if (neg) {
- /*
- * Edge case. If we have a very small negative number it will get rounded to 0,
- * however the initial check at the top will still report as negative. Replace
- * everything but 1-9 and check if the string is empty to determine a 0 value.
- */
- neg = fnum.replace(/[^1-9]/g, '') !== '';
- }
- return (neg ? '-' : '') + formatString.replace(/[\d,?\.?]+/, fnum);
- },
- <span id='Ext-util-Format-method-numberRenderer'> /**
- </span> * Returns a number rendering function that can be reused to apply a number format multiple times efficiently
- * @param {String} format Any valid number format string for {@link #number}
- * @return {Function} The number formatting function
- */
- numberRenderer : function(format) {
- return function(v) {
- return UtilFormat.number(v, format);
- };
- },
- <span id='Ext-util-Format-method-plural'> /**
- </span> * Selectively do a plural form of a word based on a numeric value. For example, in a template,
- * {commentCount:plural("Comment")} would result in "1 Comment" if commentCount was 1 or would be "x Comments"
- * if the value is 0 or greater than 1.
- * @param {Number} value The value to compare against
- * @param {String} singular The singular form of the word
- * @param {String} plural (optional) The plural form of the word (defaults to the singular with an "s")
- */
- plural : function(v, s, p) {
- return v +' ' + (v == 1 ? s : (p ? p : s+'s'));
- },
- <span id='Ext-util-Format-method-nl2br'> /**
- </span> * Converts newline characters to the HTML tag &lt;br/>
- * @param {String} The string value to format.
- * @return {String} The string with embedded &lt;br/> tags in place of newlines.
- */
- nl2br : function(v) {
- return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '<br/>');
- },
- <span id='Ext-util-Format-method-capitalize'> /**
- </span> * Alias for {@link Ext.String#capitalize}.
- * @method
- * @alias Ext.String#capitalize
- */
- capitalize: Ext.String.capitalize,
- <span id='Ext-util-Format-method-ellipsis'> /**
- </span> * Alias for {@link Ext.String#ellipsis}.
- * @method
- * @alias Ext.String#ellipsis
- */
- ellipsis: Ext.String.ellipsis,
- <span id='Ext-util-Format-method-format'> /**
- </span> * Alias for {@link Ext.String#format}.
- * @method
- * @alias Ext.String#format
- */
- format: Ext.String.format,
- <span id='Ext-util-Format-method-htmlDecode'> /**
- </span> * Alias for {@link Ext.String#htmlDecode}.
- * @method
- * @alias Ext.String#htmlDecode
- */
- htmlDecode: Ext.String.htmlDecode,
- <span id='Ext-util-Format-method-htmlEncode'> /**
- </span> * Alias for {@link Ext.String#htmlEncode}.
- * @method
- * @alias Ext.String#htmlEncode
- */
- htmlEncode: Ext.String.htmlEncode,
- <span id='Ext-util-Format-method-leftPad'> /**
- </span> * Alias for {@link Ext.String#leftPad}.
- * @method
- * @alias Ext.String#leftPad
- */
- leftPad: Ext.String.leftPad,
- <span id='Ext-util-Format-method-trim'> /**
- </span> * Alias for {@link Ext.String#trim}.
- * @method
- * @alias Ext.String#trim
- */
- trim : Ext.String.trim,
- <span id='Ext-util-Format-method-parseBox'> /**
- </span> * Parses a number or string representing margin sizes into an object. Supports CSS-style margin declarations
- * (e.g. 10, "10", "10 10", "10 10 10" and "10 10 10 10" are all valid options and would return the same result)
- * @param {Number/String} v The encoded margins
- * @return {Object} An object with margin sizes for top, right, bottom and left
- */
- parseBox : function(box) {
- if (Ext.isNumber(box)) {
- box = box.toString();
- }
- var parts = box.split(' '),
- ln = parts.length;
- if (ln == 1) {
- parts[1] = parts[2] = parts[3] = parts[0];
- }
- else if (ln == 2) {
- parts[2] = parts[0];
- parts[3] = parts[1];
- }
- else if (ln == 3) {
- parts[3] = parts[1];
- }
- return {
- top :parseInt(parts[0], 10) || 0,
- right :parseInt(parts[1], 10) || 0,
- bottom:parseInt(parts[2], 10) || 0,
- left :parseInt(parts[3], 10) || 0
- };
- },
- <span id='Ext-util-Format-method-escapeRegex'> /**
- </span> * Escapes the passed string for use in a regular expression
- * @param {String} str
- * @return {String}
- */
- escapeRegex : function(s) {
- return s.replace(/([\-.*+?\^${}()|\[\]\/\\])/g, "\\$1");
- }
- });
- })();
- </pre>
- </body>
- </html>