Skip to content

Options

Jump to bottom
Roberto Prevato edited this page May 1, 2017 · 41 revisions

Following is a list of options offered by KingTable library, including events and callback methods.

Constructor options

The KingTable constructor accepts two optional parameters: the first describes normal table options; while the second allows to override prototype methods upon instantiation.

  var options = {}; // specifies normal table options (extends default options, stored in table.options)
  var staticProperties = {}; // overrides members of KingTable prototype, by name
  var table = new KingTable(options, staticProperties);

To see the default table options, analyze the KingTable.defaults object.

Following documentation lists normal options, passed with the first parameter.

lang

Table language. This parameter must match a property of the KingTable.regional object, otherwise an exception is risen.

  • type: string
  • default: "en"

How to implement client side localization.

data

Allows to specify the collection of items that must be displayed by the KingTable; making it a fixed table.

  • type: array

The array of items can be either optimized or simple.

columns

The KingTable library is designed to help the programmers: it offers default values depending on the type of data structure it is going to display; while offering simple ways to customize the columns. The most common customization is to specify a display name for the columns. The name of the properties inside the columns option, must match the names of the items properties. Please refer to the section "columns options" for more information about the columns.

  • type: object

Example: upon render, the following table will generate an AJAX HTTP POST request to fetch data from /api/colors. It will then analyze the structure of returned items, to build its structure. Table headers will have the same name of item properties (e.g. "name" --> "name").

   var table = new KingTable({
     element: document.getElementById("table-container"),
     url: "/api/colors"
   })

   table.render();

Example: upon render, the following table will generate an AJAX HTTP POST request to fetch data from /api/colors. It will then analyze the structure of returned items, to build its structure. Table headers will have the display names specified in the columns option (e.g. "name" --> "Nome").

   var table = new KingTable({
     element: document.getElementById("table-container"),
     url: "/api/colors",
     columns: {
        name: "Nome" // in this example, hardcoded IT name is used for the sake of simplicity
     }
   })

   table.render();

caption

Allows to specify a table caption. Displaying the table caption is responsibility of the configured builder.

  • type: string
  • default: null

page

Initial page number. NB: by default, page number is cached in localStorage and restored upon page refresh.

  • type: number
  • default: 1

resultsPerPage

Initial page size. NB: by default, page size is cached in localStorage and restored upon page refresh.

  • type: number
  • default: 30

resultsPerPageSelect

Default selectable options for page size.

  • type: array of numbers
  • default: [10, 30, 50, 100, 200]

idProperty

Allows to specify the name of the property that should be used as id of the items. This is used to generate links to details URLs, if the option detailRoute is used. For more information, see the dedicated documentation.

  • type: string
  • default: null

search

Allows to define an initial text search.

  • type: string
  • default: null

formattedSuffix

The suffix to use for auto generated properties holding formatted values. Formatted values are culture dependent string representations of values, that can be used during textual searches. Original values are kept for sorting.

  • type: string
  • default: "_(formatted)"

columnDefault

The default column schema to use as a base for each column.

  • type: object
  • default:
  columnDefault: {
    name: "",         // display name of column
    type: "text",     // type of data 
    sortable: true,   // whether to allow sort by this column
    allowSearch: true,// whether to allow text search by this column
    hidden: false,    // allows to hide column (can still be displayed editing menu options)
    secret: false,    // allows to hide completely the column
    format: undefined // allows to define a formatting function for values
  }

allowSearch

Whether to allow text search. Unlike the allowSearch option for columns, this option affects only user interface: search can still be performed by programmer calling the table.search method.

  • type: boolean
  • default: true

itemCount

Whether to display item numbers. By default, row numbers are displayed.

  • type: boolean
  • default: true

minSearchChars

The number of minimum search text length, required to trigger an actual text search. This option is meant to avoid firing searches with short strings (by default, short mean 1 or 2 characters).

  • type: number
  • default: 3

exportFormats

Default export formats.

  • type: object
  • default:
  exportFormats: [
    {
      name: "Csv",
      format: "csv",
      type: "text/csv",
      cs: true  // client side
    },
    {
      name: "Json",
      format: "json",
      type: "application/json",
      cs: true  // client side
    },
    {
      name: "Xml",
      format: "xml",
      type: "text/xml",
      cs: true  // client side
    }
  ],

prettyXml

Whether to prettify xml when exporting, or not.

  • type: boolean
  • default: true

csvOptions

Allows to specify csv serialization options.

  • type: object
  • default: {}

exportHiddenProperties

Whether to include hidden properties in the output of client side export.

  • type: boolean
  • default: false

builder

The name of builder used to represent the table. This parameter must match a property of the KingTable.builders object, otherwise an exception is risen.

  • type: string
  • default: "rhtml"

How to implement custom table builders.

getTableData

Allows to define a function that returns data required to render the table itself. This is commonly necessary, for example, when an AJAX request is required to fetch filters information; such as dictionaries or arrays of possible types for select elements, a minimum value for a selectable date, etc. If specified, the function must return a Promise object or an object that 'quacks' like one; otherwise an exception is thrown. By default, the result of the AJAX request is cached using the HTML5 localStorage.

  • type: function
  • default: null

storeTableData

Whether to cache the result of the getTableData function in the storage returned by getDataStorage function (default HTML5 localStorage). By default this result is cached on client side, which can be useful to reduce the amount of AJAX requests.

  • type: boolean
  • default: true

lruCacheSize

The size of LRU caching mechanism used to store page data, in other words how many sets of items per key can be stored. For further information, see the dedicated wiki page.

  • type: number
  • default: 10

lruCacheMaxAge

LRU cache max age in milliseconds - default 15 minutes (601e315 ms). Set to a value <= 0 to disable expiration. For further information, see the dedicated wiki page.

  • type: number
  • default: 10

showAnchorTimestamp

Whether the anchor timestamp should be shown or not, that is the time at which data for a given set of filters (page number, size, order by) was collected. This is important for usability: the user should know when the data he's seeing was fetched by her client.

  • type: boolean
  • default: true

collectionName

The name of the collection used when generating output for the client side export feature (for example, for XML output).

  • type: string
  • default: "data"

searchSortingRules

Whether to override normal sort by criteria, during textual search. KingTable client side algorithm for searching by string also sorts objects by relevance. Usually this is true full text search implementations. In other words, during a text search, values are sorted by relevance and not by normal "order by" criteria.

  • type: boolean
  • default: true
Clone this wiki locally