X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/0494b8d9b9bb03ab6c22b34dae81261e3cd7e3e6..7a654f8d43fdb43d78b63d90528bed6e86b608cc:/src/core/src/util/Format.js diff --git a/src/core/src/util/Format.js b/src/core/src/util/Format.js new file mode 100644 index 00000000..4b1ac29d --- /dev/null +++ b/src/core/src/util/Format.js @@ -0,0 +1,512 @@ +/** + * @class Ext.util.Format + +This class is a centralized place for formatting functions inside the library. 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 = /(?:)((\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, { + /** + * @type String + * @property thousandSeparator + *

The character that the {@link #number} function uses as a thousand separator.

+ *

This defaults to ,, but may be overridden in a locale file.

+ */ + thousandSeparator: ',', + + /** + * @type String + * @property decimalSeparator + *

The character that the {@link #number} function uses as a decimal point.

+ *

This defaults to ., but may be overridden in a locale file.

+ */ + decimalSeparator: '.', + + /** + * @type Number + * @property currencyPrecision + *

The number of decimal places that the {@link #currency} function displays.

+ *

This defaults to 2, but may be overridden in a locale file.

+ */ + currencyPrecision: 2, + + /** + * @type String + * @property currencySign + *

The currency sign that the {@link #currency} function displays.

+ *

This defaults to $, but may be overridden in a locale file.

+ */ + currencySign: '$', + + /** + * @type Boolean + * @property currencyAtEnd + *

This may be set to true to make the {@link #currency} function + * append the currency sign to the formatted value.

+ *

This defaults to false, but may be overridden in a locale file.

+ */ + currencyAtEnd: false, + + /** + * 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 + */ + undef : function(value) { + return value !== undefined ? value : ""; + }, + + /** + * 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} + */ + defaultValue : function(value, defaultValue) { + return value !== undefined && value !== '' ? value : defaultValue; + }, + + /** + * 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); + }, + + /** + * 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(); + }, + + /** + * 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(); + }, + + /** + * 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); + }, + + /** + * 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); + } + }, + + /** + * 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 parse() 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); + }, + + /** + * 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); + }; + }, + + /** + * Strips all HTML tags + * @param {Mixed} value The text from which to strip tags + * @return {String} The stripped text + */ + stripTags : function(v) { + return !v ? v : String(v).replace(stripTagsRE, ""); + }, + + /** + * Strips all script tags + * @param {Mixed} value The text from which to strip script tags + * @return {String} The stripped text + */ + stripScripts : function(v) { + return !v ? v : String(v).replace(stripScriptsRe, ""); + }, + + /** + * 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"; + } + }, + + /** + * It does simple math for use in a template, for example:

+         * var tpl = new Ext.Template('{value} * 10 = {value:math("* 10")}');
+         *
+ * @return {Function} A function that operates on the passed value. + */ + math : function(){ + var fns = {}; + + return function(v, a){ + if (!fns[a]) { + fns[a] = Ext.functionFactory('v', 'return v ' + a + ';'); + } + return fns[a](v); + }; + }(), + + /** + * 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; + }, + + /** + *

Formats the passed number according to the passed format string.

+ *

The number of digits after the decimal separator character specifies the number of + * decimal places in the resulting string. The local-specific decimal character is used in the result.

+ *

The presence of a thousand separator character in the format string specifies that + * the locale-specific thousand separator (if any) is inserted separating thousand groups.

+ *

By default, "," is expected as the thousand separator, and "." is expected as the decimal separator.

+ *

New to Ext4

+ *

Locale-specific characters are always used in the formatted output when inserting + * thousand and decimal separators.

+ *

The format string must specify separator characters according to US/UK conventions ("," as the + * thousand separator, and "." as the decimal separator)

+ *

To allow specification of format strings according to local conventions for separator characters, add + * the string /i to the end of 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 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 + *
+ * @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) { + // + Ext.Error.raise({ + sourceClass: "Ext.util.Format", + sourceMethod: "number", + value: v, + formatString: formatString, + msg: "Invalid number format, should have no more than 1 decimal" + }); + // + } 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]; + } + } + + return (neg ? '-' : '') + formatString.replace(/[\d,?\.?]+/, fnum); + }, + + /** + * 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); + }; + }, + + /** + * 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')); + }, + + /** + * 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. + */ + nl2br : function(v) { + return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '
'); + }, + + /** + * Capitalize the given string. See {@link Ext.String#capitalize}. + */ + capitalize: Ext.String.capitalize, + + /** + * Truncate a string and add an ellipsis ('...') to the end if it exceeds the specified length. + * See {@link Ext.String#ellipsis}. + */ + ellipsis: Ext.String.ellipsis, + + /** + * Formats to a string. See {@link Ext.String#format} + */ + format: Ext.String.format, + + /** + * Convert certain characters (&, <, >, and ') from their HTML character equivalents. + * See {@link Ext.string#htmlDecode}. + */ + htmlDecode: Ext.String.htmlDecode, + + /** + * Convert certain characters (&, <, >, and ') to their HTML character equivalents for literal display in web pages. + * See {@link Ext.String#htmlEncode}. + */ + htmlEncode: Ext.String.htmlEncode, + + /** + * Adds left padding to a string. See {@link Ext.String#leftPad} + */ + leftPad: Ext.String.leftPad, + + /** + * Trims any whitespace from either side of a string. See {@link 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"); + } + }); +})();