[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["datatable-body", "datatype-number-format", "datatype-date-format", "escape"]});