@extjs/sencha-cmd-linux-32
Version:
Productivity and performance optimization tool for building applications with Sencha Ext JS and Sencha Touch.
583 lines (534 loc) • 20.9 kB
JavaScript
/**
* @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}'
* ]);
*
* @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, {
//<locale>
/**
* @property {String} thousandSeparator
* The character that the {@link #number} function uses as a thousand separator.
*
* This may be overridden in a locale file.
*/
thousandSeparator: ',',
//</locale>
//<locale>
/**
* @property {String} decimalSeparator
* The character that the {@link #number} function uses as a decimal point.
*
* This may be overridden in a locale file.
*/
decimalSeparator: '.',
//</locale>
//<locale>
/**
* @property {Number} currencyPrecision
* The number of decimal places that the {@link #currency} function displays.
*
* This may be overridden in a locale file.
*/
currencyPrecision: 2,
//</locale>
//<locale>
/**
* @property {String} currencySign
* The currency sign that the {@link #currency} function displays.
*
* This may be overridden in a locale file.
*/
currencySign: '$',
//</locale>
//<locale>
/**
* @property {Boolean} currencyAtEnd
* This may be set to <code>true</code> to make the {@link #currency} function
* append the currency sign to the formatted value.
*
* This may be overridden in a locale file.
*/
currencyAtEnd: false,
//</locale>
/**
* 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 : "";
},
/**
* 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.
* @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
* @method
*/
substr : 'ab'.substr(-1) != 'b'
? function (value, start, length) {
var str = String(value);
return (start < 0)
? str.substr(Math.max(str.length + start, 0), length)
: str.substr(start, length);
}
: 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 = Ext.isDefined(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's built-in Date#parse method.
* @param {String} [format] 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 {Object} 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 {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, "");
},
/**
* 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.
* @method
*/
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 Ext JS 4
*
* 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,
fnum,
cnum,
parr,
j,
m,
n,
i;
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 (psplit.length > 2) {
//<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 if (psplit.length > 1) {
v = Ext.Number.toFixed(v, psplit[1].length);
} else {
v = Ext.Number.toFixed(v, 0);
}
fnum = v.toString();
psplit = fnum.split('.');
if (hasComma) {
cnum = psplit[0];
parr = [];
j = cnum.length;
m = Math.floor(j / 3);
n = cnum.length % 3 || 3;
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);
},
/**
* 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] 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, '<br/>');
},
/**
* Alias for {@link Ext.String#capitalize}.
* @method
* @inheritdoc Ext.String#capitalize
*/
capitalize: Ext.String.capitalize,
/**
* Alias for {@link Ext.String#ellipsis}.
* @method
* @inheritdoc Ext.String#ellipsis
*/
ellipsis: Ext.String.ellipsis,
/**
* Alias for {@link Ext.String#format}.
* @method
* @inheritdoc Ext.String#format
*/
format: Ext.String.format,
/**
* Alias for {@link Ext.String#htmlDecode}.
* @method
* @inheritdoc Ext.String#htmlDecode
*/
htmlDecode: Ext.String.htmlDecode,
/**
* Alias for {@link Ext.String#htmlEncode}.
* @method
* @inheritdoc Ext.String#htmlEncode
*/
htmlEncode: Ext.String.htmlEncode,
/**
* Alias for {@link Ext.String#leftPad}.
* @method
* @inheritdoc Ext.String#leftPad
*/
leftPad: Ext.String.leftPad,
/**
* Alias for {@link Ext.String#trim}.
* @method
* @inheritdoc 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) {
box = Ext.isEmpty(box) ? '' : 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");
}
});
}());