/**
+ * @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
*/
-Ext.util.Format = function() {
- var trimRe = /^\s+|\s+$/g,
- stripTagsRE = /<\/?[^>]+>/gi,
- stripScriptsRe = /(?:)((\n|\r|.)*?)(?:<\/script>)/ig,
- nl2brRe = /\r?\n/g;
-
- return {
- /**
- * Truncate a string and add an ellipsis ('...') to the end if it exceeds the specified length
- * @param {String} value The string to truncate
- * @param {Number} length The maximum length to allow before truncating
- * @param {Boolean} word True to try to find a common work break
- * @return {String} The converted text
+(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, {
+ /**
+ * @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>
*/
- ellipsis : function(value, len, word) {
- if (value && value.length > len) {
- if (word) {
- var vs = value.substr(0, len - 2),
- index = Math.max(vs.lastIndexOf(' '), vs.lastIndexOf('.'), vs.lastIndexOf('!'), vs.lastIndexOf('?'));
- if (index == -1 || index < (len - 15)) {
- return value.substr(0, len - 3) + "...";
- } else {
- return vs.substr(0, index) + "...";
- }
- } else {
- return value.substr(0, len - 3) + "...";
- }
- }
- return value;
- },
+ thousandSeparator: ',',
- /**
- * Checks a reference and converts it to empty string if it is undefined
- * @param {Mixed} value Reference to check
- * @return {Mixed} Empty string if converted, otherwise the original value
+ /**
+ * @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>
*/
- undef : function(value) {
- return value !== undefined ? value : "";
- },
+ decimalSeparator: '.',
- /**
- * Checks a reference and converts it to the default value if it's empty
- * @param {Mixed} value Reference to check
- * @param {String} defaultValue The value to insert of it's undefined (defaults to "")
- * @return {String}
+ /**
+ * @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>
*/
- defaultValue : function(value, defaultValue) {
- return value !== undefined && value !== '' ? value : defaultValue;
- },
+ currencyPrecision: 2,
- /**
- * Convert certain characters (&, <, >, and ') to their HTML character equivalents for literal display in web pages.
- * @param {String} value The string to encode
- * @return {String} The encoded text
+ /**
+ * @property {String} currencySign
+ * <p>The currency sign that the {@link #currency} function displays.</p>
+ * <p>This may be overridden in a locale file.</p>
*/
- htmlEncode : function(value) {
- return !value ? value : String(value).replace(/&/g, "&").replace(/>/g, ">").replace(/ /**
+ * @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,
- /**
- * Convert certain characters (&, <, >, and ') from their HTML character equivalents.
- * @param {String} value The string to decode
- * @return {String} The decoded text
+ /**
+ * 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
*/
- htmlDecode : function(value) {
- return !value ? value : String(value).replace(/>/g, ">").replace(/</g, "<").replace(/"/g, '"').replace(/&/g, "&");
+ undef : function(value) {
+ return value !== undefined ? value : "";
},
- /**
- * Trims any whitespace from either side of a string
- * @param {String} value The text to trim
- * @return {String} The trimmed text
+ /**
+ * 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}
*/
- trim : function(value) {
- return String(value).replace(trimRe, "");
+ defaultValue : function(value, defaultValue) {
+ return value !== undefined && value !== '' ? value : defaultValue;
},
- /**
- * Returns a substring from within an original string
+ /**
+ * 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
@@ -105,8 +147,8 @@ Ext.util.Format = function() {
return String(value).substr(start, length);
},
- /**
- * Converts a string to all lower case letters
+ /**
+ * Converts a string to all lower case letters
* @param {String} value The text to convert
* @return {String} The converted text
*/
@@ -114,8 +156,8 @@ Ext.util.Format = function() {
return String(value).toLowerCase();
},
- /**
- * Converts a string to all upper case letters
+ /**
+ * Converts a string to all upper case letters
* @param {String} value The text to convert
* @return {String} The converted text
*/
@@ -123,128 +165,126 @@ Ext.util.Format = function() {
return String(value).toUpperCase();
},
- /**
- * Converts the first character only of a string to upper case
- * @param {String} value The text to convert
- * @return {String} The converted text
+ /**
+ * Format a number as US currency
+ * @param {Number/String} value The numeric value to format
+ * @return {String} The formatted currency string
*/
- capitalize : function(value) {
- return !value ? value : value.charAt(0).toUpperCase() + value.substr(1).toLowerCase();
- },
-
- // private
- call : function(value, fn) {
- if (arguments.length > 2) {
- var args = Array.prototype.slice.call(arguments, 2);
- args.unshift(value);
- return eval(fn).apply(window, args);
- } else {
- return eval(fn).call(window, value);
- }
+ usMoney : function(v) {
+ return UtilFormat.currency(v, '$', 2);
},
- /**
- * Format a number as US currency
+ /**
+ * 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
*/
- usMoney : function(v) {
- v = (Math.round((v-0)*100))/100;
- v = (v == Math.floor(v)) ? v + ".00" : ((v*10 == Math.floor(v*10)) ? v + "0" : v);
- v = String(v);
- var ps = v.split('.'),
- whole = ps[0],
- sub = ps[1] ? '.'+ ps[1] : '.00',
- r = /(\d+)(\d{3})/;
- while (r.test(whole)) {
- whole = whole.replace(r, '$1' + ',' + '$2');
+ currency: function(v, currencySign, decimals, end) {
+ var negativeSign = '',
+ format = ",0",
+ i = 0;
+ v = v - 0;
+ if (v < 0) {
+ v = -v;
+ negativeSign = '-';
}
- v = whole + sub;
- if (v.charAt(0) == '-') {
- return '-$' + v.substr(1);
+ 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);
}
- return "$" + v;
},
- /**
- * Parse a value into a formatted date using the specified format pattern.
- * @param {String/Date} value The value to format (Strings must conform to the format expected by the javascript Date object's parse() method)
- * @param {String} format (optional) Any valid date format string (defaults to 'm/d/Y')
- * @return {String} The formatted date string
+ /**
+ * 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) {
+ date: function(v, format) {
if (!v) {
- return "";
+ return "";
}
if (!Ext.isDate(v)) {
v = new Date(Date.parse(v));
}
- return v.dateFormat(format || "m/d/Y");
+ return Ext.Date.dateFormat(v, format || Ext.Date.defaultFormat);
},
- /**
- * 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
+ /**
+ * 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 Ext.util.Format.date(v, format);
+ return UtilFormat.date(v, format);
};
},
- /**
- * Strips all HTML tags
- * @param {Mixed} value The text from which to strip tags
+ /**
+ * 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, "");
+ return !v ? v : String(v).replace(stripTagsRE, "");
},
- /**
- * Strips all script tags
- * @param {Mixed} value The text from which to strip script tags
+ /**
+ * 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, "");
+ return !v ? v : String(v).replace(stripScriptsRe, "");
},
- /**
- * Simple format for a file size (xxx bytes, xxx KB, xxx MB)
+ /**
+ * 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";
+ 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";
+ return (Math.round(((size*10) / 1048576))/10) + " MB";
}
},
- /**
- * It does simple math for use in a template, for example:
- * var tpl = new Ext.Template('{value} * 10 = {value:math("* 10")}');
- *
+ /**
+ * 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] = new Function('v', 'return v ' + a + ';');
+ fns[a] = Ext.functionFactory('v', 'return v ' + a + ';');
}
return fns[a](v);
};
}(),
- /**
- * Rounds the passed number to the required decimal precision.
+ /**
+ * 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.
@@ -258,51 +298,81 @@ Ext.util.Format = function() {
return result;
},
- /**
- * Formats the number according to the format string.
- *
examples (123456.789):
- *
- * 0 - (123456) show only digits, no precision
- * 0.00 - (123456.78) show only digits, 2 precision
- * 0.0000 - (123456.7890) show only digits, 4 precision
- * 0,000 - (123,456) show comma and digits, no precision
- * 0,000.00 - (123,456.78) show comma and digits, 2 precision
- * 0,0.00 - (123,456.78) shortcut method, show comma and digits, 2 precision
- * To reverse the grouping (,) and decimal (.) for international numbers, add /i to the end.
+ /**
+ * <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, format) {
- if (!format) {
+ number: function(v, formatString) {
+ if (!formatString) {
return v;
}
- v = Ext.num(v, NaN);
+ v = Ext.Number.from(v, NaN);
if (isNaN(v)) {
return '';
}
- var comma = ',',
- dec = '.',
+ var comma = UtilFormat.thousandSeparator,
+ dec = UtilFormat.decimalSeparator,
i18n = false,
- neg = v < 0;
+ neg = v < 0,
+ hasComma,
+ psplit;
v = Math.abs(v);
- if (format.substr(format.length - 2) == '/i') {
- format = format.substr(0, format.length - 2);
+
+ // 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;
- comma = '.';
- dec = ',';
+ hasComma = formatString.indexOf(comma) != -1;
+ psplit = formatString.replace(I18NFormatCleanRe, '').split(dec);
+ } else {
+ hasComma = formatString.indexOf(',') != -1;
+ psplit = formatString.replace(formatCleanRe, '').split('.');
}
- var hasComma = format.indexOf(comma) != -1,
- psplit = (i18n ? format.replace(/[^\d\,]/g, '') : format.replace(/[^\d\.]/g, '')).split(dec);
-
- if (1 < psplit.length) {
+ if (1 < psplit.length) {
v = v.toFixed(psplit[1].length);
- } else if(2 < psplit.length) {
- throw ('NumberFormatException: invalid format, formats should have no more than 1 period: ' + format);
+ } 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);
}
@@ -312,18 +382,18 @@ Ext.util.Format = function() {
psplit = fnum.split('.');
if (hasComma) {
- var cnum = psplit[0],
- parr = [],
- j = cnum.length,
+ 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) {
+ for (i = 0; i < j; i += n) {
+ if (i !== 0) {
n = 3;
}
-
+
parr[parr.length] = cnum.substr(i, n);
m -= 1;
}
@@ -337,42 +407,141 @@ Ext.util.Format = function() {
}
}
- return (neg ? '-' : '') + format.replace(/[\d,?\.?]+/, fnum);
+ 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);
},
- /**
- * Returns a number rendering function that can be reused to apply a number format multiple times efficiently
+ /**
+ * 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 Ext.util.Format.number(v, format);
+ return UtilFormat.number(v, format);
};
},
- /**
- * 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"
+ /**
+ * 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")
+ * @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'));
},
- /**
- * Converts newline characters to the HTML tag <br/>
+ /**
+ * Converts newline characters to the HTML tag <br/>
* @param {String} The string value to format.
- * @return {String} The string with embedded <br/> tags in place of newlines.
+ * @return {String} The string with embedded <br/> tags in place of newlines.
*/
nl2br : function(v) {
- return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, ' ');
+ return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '<br/>');
+ },
+
+ /**
+ * Alias for {@link Ext.String#capitalize}.
+ * @method
+ * @alias Ext.String#capitalize
+ */
+ capitalize: Ext.String.capitalize,
+
+ /**
+ * Alias for {@link Ext.String#ellipsis}.
+ * @method
+ * @alias Ext.String#ellipsis
+ */
+ ellipsis: Ext.String.ellipsis,
+
+ /**
+ * Alias for {@link Ext.String#format}.
+ * @method
+ * @alias Ext.String#format
+ */
+ format: Ext.String.format,
+
+ /**
+ * Alias for {@link Ext.String#htmlDecode}.
+ * @method
+ * @alias Ext.String#htmlDecode
+ */
+ htmlDecode: Ext.String.htmlDecode,
+
+ /**
+ * Alias for {@link Ext.String#htmlEncode}.
+ * @method
+ * @alias Ext.String#htmlEncode
+ */
+ htmlEncode: Ext.String.htmlEncode,
+
+ /**
+ * Alias for {@link Ext.String#leftPad}.
+ * @method
+ * @alias Ext.String#leftPad
+ */
+ leftPad: Ext.String.leftPad,
+
+ /**
+ * Alias for {@link Ext.String#trim}.
+ * @method
+ * @alias Ext.String#trim
+ */
+ trim : Ext.String.trim,
+
+ /**
+ * 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
+ };
+ },
+
+ /**
+ * Escapes the passed string for use in a regular expression
+ * @param {String} str
+ * @return {String}
+ */
+ escapeRegex : function(s) {
+ return s.replace(/([\-.*+?\^${}()|\[\]\/\\])/g, "\\$1");
}
- };
-}();
-