Version 3.18.1
Show:

File: datatable/js/formatters.js

  1. /**
  2. Adds predefined cell formatters to `Y.DataTable.BodyView`.
  3. @module datatable-formatters
  4. **/
  5. var Lang = Y.Lang,
  6. isValue = Lang.isValue,
  7. escape = Y.Escape.html,
  8. getCName = Y.ClassNameManager.getClassName,
  9. cName = function (name) {
  10. return getCName('datatable', name);
  11. },
  12. stringValue = function (value, def) {
  13. return (isValue(value) ? escape(value.toString()) : def || '');
  14. },
  15. /**
  16. Registry of function producing cell formatting functions.
  17. Allows for names to be used in the column
  18. definition `formatter` property:
  19. {key:"myColumn", formatter:"date"}
  20. These functions are not meant to be used directly. Instead, they will be
  21. automatically called when their names are used as values for the `formatter`
  22. property in a columnd definition.
  23. They will be called just once per rendering cycle and will receive
  24. the column configuration. They are expected to return a function that will
  25. then be called once per row and will do the actual formatting.
  26. They are expected to do all the preparatory once-per-render work
  27. so that the actual formatting function doesn't need to repeat it.
  28. @class DataTable.BodyView.Formatters
  29. **/
  30. Formatters = {
  31. /**
  32. Returns a formatter that produces a BUTTON element using the value of
  33. the [buttonLabel](DataTable.Column.html#property_buttonLabel)
  34. column definition attribute as its label or the text
  35. `Click` if not found.
  36. Applies the CSS className `yui3-datatable-button` to the cell.
  37. @method button
  38. @param col {Object} The column definition.
  39. @return {Function} A formatter function that produces a `<button>` element.
  40. @static
  41. **/
  42. button: function (col) {
  43. var className = cName('button'),
  44. html = '<button>' + (col.buttonLabel || 'Click') + '</button>';
  45. col.allowHTML = true;
  46. return function(o) {
  47. o.className = className;
  48. return html;
  49. };
  50. },
  51. /**
  52. Returns a formatter function that returns the texts `"true"` or `"false"`
  53. and assigns the CSS classNames `yui3-datatable-true` or `yui3-datatable-false`
  54. based on the value of the cell.
  55. If either a [booleanLabels](DataTable.Column.html#property_booleanLabels)
  56. configuration object is defined for the column
  57. or a [booleanLabels](DataTable.html#attr_booleanLabels)
  58. configuration attribute is defined for the datatable,
  59. the formatter will use the values for the properties `true` or `false`
  60. of either of those objects as the text to show.
  61. It returns `null`s or `undefined`s unchanged so that the `emptyCellValue`
  62. configuration attribute will eventually apply.
  63. {key:"active", formatter: "boolean", booleanLabels: {
  64. "true": "yes",
  65. "false": "no"
  66. }}
  67. @method boolean
  68. @param col {Object} The column definition.
  69. @return {Function} A formatter function that formats boolean data.
  70. @static
  71. **/
  72. 'boolean': function (col) {
  73. var labels = col.booleanLabels || this.get('booleanLabels') || {'true':'true', 'false':'false'};
  74. return function(o) {
  75. var value = o.value;
  76. if (!value && value !== false) {
  77. return value;
  78. }
  79. value = value?'true':'false';
  80. o.className = cName(value);
  81. return labels[value];
  82. };
  83. },
  84. /**
  85. Returns a formatter function that formats values as currency using
  86. the [Number.format](Number.html#method_format) method.
  87. It looks for the format to apply in the
  88. [currencyFormat](DataTable.Column.html#property_currencyFormat) property
  89. of the column or in the
  90. [currencyFormat](DataTable.html#attr_currencyFormat)
  91. attribute of the whole table.
  92. {key: "amount", formatter: "currency", currencyFormat: {
  93. decimalPlaces:2,
  94. decimalSeparator: ",",
  95. thousandsSeparator: ".",
  96. suffix: "&euro;"
  97. }}
  98. See [Number.format](Number.html#method_format) for the available format specs.
  99. Anything that cannot be parsed as a number will be returned unchanged.
  100. Applies the CSS className `yui3-datatable-currency` to the cell.
  101. @method currency
  102. @param col {Object} The column definition.
  103. @return {Function} A formatter function that formats numerical data as currency.
  104. @static
  105. **/
  106. currency: function (col) {
  107. var className = cName('currency'),
  108. format = col.currencyFormat || this.get('currencyFormat'),
  109. fn = Y.Number.format;
  110. return function (o) {
  111. o.className = className;
  112. var value = parseFloat(o.value);
  113. if (!value && value !== 0) {
  114. return o.value;
  115. }
  116. return fn(value, format);
  117. };
  118. },
  119. /**
  120. Returns a date formatting function based on the given format.
  121. @method _date
  122. @param format {String} The format spec definition.
  123. @return {Function} A formatter function that formats numerical data as currency.
  124. @private
  125. @static
  126. **/
  127. _date: function (format) {
  128. var className = cName('date'),
  129. fn = Y.Date.format;
  130. format = {format: format};
  131. return function (o) {
  132. o.className = className;
  133. return fn(o.value, format);
  134. };
  135. },
  136. /**
  137. Returns a date formatting function.
  138. It looks for the format to apply in the
  139. [dateFormat](DataTable.Column.html#property_dateFormat)
  140. property of the column or in the
  141. [dateFormat](DataTable.html#attr_dateFormat)
  142. attribute of the whole table.
  143. {key: "DOB", formatter: "date", dateFormat: "%I:%M:%S %p"}
  144. See [Date.format](Date.html#method_format) for the available format specs.
  145. Anything that is not a date is returned unchanged.
  146. Applies the CSS className `yui3-datatable-date` to the cell.
  147. @method date
  148. @param col {Object} The column definition.
  149. @return {Function} A formatter function that formats dates.
  150. @static
  151. **/
  152. 'date' : function (col) {
  153. return Formatters._date(col.dateFormat || this.get('dateFormat'));
  154. },
  155. /**
  156. Returns a date-only (no time part) formatting function using the current locale.
  157. {key: "DOB", formatter: "localDate"}
  158. Anything that is not a date is returned unchanged.
  159. Applies the CSS className `yui3-datatable-date` to the cell.
  160. @method localDate
  161. @return {Function} A formatter function that formats dates.
  162. @static
  163. **/
  164. localDate : function () {
  165. return Formatters._date('%x');
  166. },
  167. /**
  168. Returns a time-only (no date part) formatting function using the current locale.
  169. {key: "startTime", formatter: "localTime"}
  170. Anything that is not a date is returned unchanged.
  171. Applies the CSS className `yui3-datatable-date` to the cell.
  172. @method localTime
  173. @return {Function} A formatter function that formats dates.
  174. @static
  175. **/
  176. localTime : function () {
  177. return Formatters._date('%X');
  178. },
  179. /**
  180. Returns a date formatting function using the current locale.
  181. {key: "DOB", formatter: "localDateTime"}
  182. Anything that is not a date is returned unchanged.
  183. Applies the CSS className `yui3-datatable-date` to the cell.
  184. @method localDateTime
  185. @return {Function} A formatter function that formats dates.
  186. @static
  187. **/
  188. localDateTime : function () {
  189. return Formatters._date('%c');
  190. },
  191. /**
  192. Returns a function that produces email links.
  193. If the column definition contains a property
  194. [linkFrom](DataTable.Column.html#property_linkFrom) it will use the value
  195. in that field for the link, otherwise, the same column value will be used for both
  196. link and text.
  197. {key: "contact", formatter: "email", linkFrom: "contactEmail"}
  198. It will use the respective
  199. [emptyCellValue](DataTable.Column.html#property_emptyCellValue)
  200. column configuration attribute
  201. for each of the value and the link if either is empty.
  202. If the link value is still empty, it will return the value with no link.
  203. Applies the CSS className `yui3-datatable-email` to the cell.
  204. @method email
  205. @param col {Object} The column definition.
  206. @return {Function} A formatter function that adds a mailto: link to the value.
  207. @static
  208. **/
  209. email: function (col) {
  210. var className = cName('email'),
  211. linkFrom = col.linkFrom,
  212. emptyValue = col.emptyCellValue,
  213. emptyLink = (this.getColumn(linkFrom) || {}).emptyCellValue;
  214. col.allowHTML = true;
  215. return function (o) {
  216. var value = stringValue(o.value, emptyValue),
  217. link = (linkFrom ? stringValue(o.data[linkFrom], emptyLink) : value);
  218. o.className = className;
  219. if (link) {
  220. return '<a href="mailto:' + link + '">' + value + '</a>';
  221. }
  222. return value;
  223. };
  224. },
  225. /**
  226. Returns a function that produces links.
  227. If the column definition contains a property
  228. [linkFrom](DataTable.Column.html#property_linkFrom) it will use the value
  229. in that field for the link, otherwise, the same column value will be used for both
  230. link and text.
  231. {key: "company", formatter: "link", linkFrom: "webSite"}
  232. It will use the respective
  233. [emptyCellValue](DataTable.Column.html#property_emptyCellValue)
  234. column configuration attribute
  235. for each of the value and the link if either is empty.
  236. If the link value is still empty, it will return the value with no link.
  237. Applies the CSS className `yui3-datatable-link` to the cell.
  238. @method link
  239. @param col {Object} The column definition.
  240. @return {Function} A formatter function that adds a link to the value.
  241. @static
  242. **/
  243. link: function (col) {
  244. var className = cName('link'),
  245. linkFrom = col.linkFrom,
  246. emptyValue = col.emptyCellValue,
  247. emptyLink = (this.getColumn(linkFrom) || {}).emptyCellValue;
  248. col.allowHTML = true;
  249. return function (o) {
  250. var value = stringValue(o.value, emptyValue),
  251. link = (linkFrom ? stringValue(o.data[linkFrom], emptyLink) : value);
  252. o.className = className;
  253. if (link) {
  254. return '<a href="' + link + '">' + value + '</a>';
  255. }
  256. return value;
  257. };
  258. },
  259. /**
  260. Returns a formatter function that formats values using
  261. the [Number.format](Number.html#method_format) method.
  262. It looks for the format to apply in the
  263. [numberFormat](DataTable.Column.html#property_numberFormat)
  264. property of the column or in the
  265. [numberFormat](DataTable.html#attr_numberFormat)
  266. attribute of the whole table.
  267. {key: "weight", formatter: "number", numberFormat: {
  268. decimalPlaces:2,
  269. decimalSeparator: ",",
  270. thousandsSeparator: ",",
  271. suffix: "kg"
  272. }}
  273. See [Number.format](Number.html#method_format) for the available format specs.
  274. Anything that cannot be parsed as a number will be returned unchanged.
  275. Applies the CSS className `yui3-datatable-number` to the cell.
  276. @method number
  277. @param col {Object} The column definition.
  278. @return {Function} A formatter function that formats numerical data as currency.
  279. @static
  280. **/
  281. number: function (col) {
  282. var className = cName('number'),
  283. format = col.numberFormat || this.get('numberFormat'),
  284. fn = Y.Number.format;
  285. return function (o) {
  286. o.className = className;
  287. var value = parseFloat(o.value);
  288. if (!value && value !== 0) {
  289. return o.value;
  290. }
  291. return fn(value, format);
  292. };
  293. },
  294. /**
  295. Returns a formatter function that returns texts from a lookup table
  296. based on the stored value.
  297. It looks for the translation to apply in the
  298. [lookupTable](DataTable.Column.html#property_lookupTable) property of the
  299. column in either of these two formats:
  300. {key: "status", formatter: "lookup", lookupTable: {
  301. 0: "unknown",
  302. 1: "requested",
  303. 2: "approved",
  304. 3: "delivered"
  305. }},
  306. {key: "otherStatus", formatter: "lookup", lookupTable: [
  307. {value:0, text: "unknown"},
  308. {value:1, text: "requested"},
  309. {value:2, text: "approved"},
  310. {value:3, text: "delivered"}
  311. ]}
  312. Applies the CSS className `yui3-datatable-lookup` to the cell.
  313. @method lookup
  314. @param col {Object} The column definition
  315. @return {Function} A formatter function that returns the `text`
  316. associated with `value`.
  317. @static
  318. */
  319. lookup: function (col) {
  320. var className = cName('lookup'),
  321. lookup = col.lookupTable || {},
  322. entries, i, len;
  323. if (Lang.isArray(lookup)) {
  324. entries = lookup;
  325. lookup = {};
  326. for (i = 0, len = entries.length; i < len; ++i) {
  327. lookup[entries[i].value] = entries[i].text;
  328. }
  329. }
  330. return function (o) {
  331. o.className = className;
  332. return lookup[o.value];
  333. };
  334. }
  335. };
  336. Y.mix(Y.DataTable.BodyView.Formatters, Formatters);
  337. /**
  338. Label to be shown in the face of a button produced by the
  339. [button](DataTable.BodyView.Formatters.html#method_button) formatter
  340. @property buttonLabel
  341. @type String
  342. @for DataTable.Column
  343. */
  344. /**
  345. Determines the texts to be shown to represent Boolean values when the
  346. [boolean](DataTable.BodyView.Formatters.html#method_boolean) formatter
  347. is used.
  348. The attribute is an object with text values for properties `true` and `false`.
  349. {key:"active", formatter: "boolean", booleanLabels: {
  350. "true": "yes",
  351. "false": "no"
  352. }}
  353. @property booleanLabels
  354. @type Object
  355. @for DataTable.Column
  356. */
  357. /**
  358. Determines the texts to be shown to represent Boolean values when the
  359. [boolean](DataTable.BodyView.Formatters.html#method_boolean) formatter
  360. is used on any column.
  361. It works like the column-specific
  362. [booleanLabels](DataTable.Column.html#property_booleanLabels) but
  363. for all columns using the
  364. [boolean](DataTable.BodyView.Formatters.html#method_boolean) formatter at once.
  365. The values are often retrieved from a resource of localized texts.
  366. @attribute booleanLabels
  367. @type Object
  368. @for DataTable
  369. */
  370. /**
  371. Format specification for columns using the
  372. [currency](DataTable.BodyView.Formatters.html#method_currency) formatter.
  373. It contains an object as described in
  374. [Number.format](Number.html#method_format).
  375. @property currencyFormat
  376. @type Object
  377. @for DataTable.Column
  378. */
  379. /**
  380. Format specification for columns using the
  381. [currency](DataTable.BodyView.Formatters.html#method_currency) formatter.
  382. It contains an object as described in
  383. [Number.format](Number.html#method_format).
  384. It is similar to
  385. [currencyFormat](DataTable.Column.html#property_currencyFormat)
  386. but it applies to any column using the
  387. [currency](DataTable.BodyView.Formatters.html#method_currency) formatter.
  388. The values are often retrieved from a resource of localized configuration.
  389. @attribute currencyFormat
  390. @type Object
  391. @for DataTable
  392. */
  393. /**
  394. Format specification for columns using the
  395. [date](DataTable.BodyView.Formatters.html#method_date) formatter.
  396. It contains a string as described in
  397. [Date.format](Date.html#method_format).
  398. @property dateFormat
  399. @type String
  400. @for DataTable.Column
  401. */
  402. /**
  403. Format specification for columns using the
  404. [date](DataTable.BodyView.Formatters.html#method_date) formatter.
  405. It contains an object as described in
  406. [Date.format](Date.html#method_format).
  407. It is similar to
  408. [dateFormat](DataTable.Column.html#property_dateFormat)
  409. but it applies to any column using the
  410. [date](DataTable.BodyView.Formatters.html#method_date) formatter.
  411. The values are often retrieved from a resource of localized configuration.
  412. @attribute dateFormat
  413. @type String
  414. @for DataTable
  415. */
  416. /**
  417. Name of the field that is to provide the link for a column using the
  418. [email](DataTable.BodyView.Formatters.html#method_email) or
  419. [link](DataTable.BodyView.Formatters.html#method_link)
  420. formatters.
  421. @property linkFrom
  422. @type String
  423. @for DataTable.Column
  424. */
  425. /**
  426. Format specification for columns using the
  427. [number](DataTable.BodyView.Formatters.html#method_number) formatter.
  428. It contains an object as described in
  429. [Number.format](Number.html#method_format).
  430. @property numberFormat
  431. @type Object
  432. @for DataTable.Column
  433. */
  434. /**
  435. Format specification for columns using the
  436. [number](DataTable.BodyView.Formatters.html#method_number) formatter.
  437. It contains an object as described in
  438. [Number.format](Number.html#method_format).
  439. It is similar to
  440. [numberFormat](DataTable.Column.html#property_numberFormat)
  441. but it applies to any column using the
  442. [number](DataTable.BodyView.Formatters.html#method_number) formatter.
  443. The values are often retrieved from a resource of localized configuration.
  444. @attribute numberFormat
  445. @type Object
  446. @for DataTable
  447. */
  448. /**
  449. Map of values to text used to translate internal values to human readable text
  450. in columns using the [lookup](DataTable.BodyView.Formatters.html#method_lookup)
  451. formatter.
  452. The map can be given in either of two formats:
  453. {key: "status", formatter: "lookup", lookupTable: {
  454. 0: "unknown",
  455. 1: "requested",
  456. 2: "approved",
  457. 3: "delivered"
  458. }},
  459. {key: "otherStatus", formatter: "lookup", lookupTable: [
  460. {value:0, text: "unknown"},
  461. {value:1, text: "requested"},
  462. {value:2, text: "approved"},
  463. {value:3, text: "delivered"}
  464. ]}
  465. The last format is compatible with the [dropdown](DataTable.Editors.html#property_dropdown)
  466. and autocomplete-based editors, where the order of the items in the dropdown matters.
  467. @property lookupTable
  468. @type Object || Array
  469. @for DataTable.Column
  470. */