lib/yuilib/3.13.0/datatable-formatters/datatable-formatters-debug.js

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