Options

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.

id

Table id. This parameter is important if more than one table for a given URL are displayed in the same page. It allows to generate unique keys for caching of filters and data related to a given table.

type: string
default: null

If an id is not specified, memory keys are generated on the basis of page URL (including hash).

NB:

var a = new KingTable({ id: "one" });

// getMemoryKey is a function used internally to obtain keys to cache data for a table
var key = a.getMemoryKey("foo"); // --> "one:/rhtml-schemas.kt:::foo"

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

httpMethod

Allows to specify HTTP method to be used when fetching list data (collections of items): GET or POST method. HTTP GET method is used by default and filters are sent using query string, since this enables support for HTTP Caching using Content-Cache header on the server side. If POST method is used instead, filters are sent as JSON serialized object (Content-Type application/json), in this case the LRU caching mechanism included in KingTable library is particularly valuable, since it allows to reduce AJAX requests. For more information on this topic, refer to dedicated wiki page.

type: string [GET | POST]
default: "GET"

fetchData

Allows to specify extra fetch data that should be added to filters collected by table. If it is a function, extra fetch data is obtained from calling this function in the context of KingTable instance.

type: object or function
default: undefined

dateFilterFormatter

Function used to format dates in filters, before they are used by the promise returned by getFetchPromise function. By default, getFetchPromise generates an AJAX request to a configured url; this function can be therefore used to create string representation of dates as desired. For GET requests, filters are placed in the query string; while for POST requests they are serialized in JSON. The function is called with two parameters: filter property name and value, to support different formats by filter property.

type: function
default: dates are all serialized to ISO 8601 formatted strings

sortByFormatter

Function used to format sort by criteria as desired, before they are sent for AJAX requests. The function is called with an array of arrays, like:

  // sort by "name"
  [
    ["name", 1]
  ]

  // sort by "name, birthdate desc"
  [
    ["name", 1],
    ["birthdate", -1]
  ]

  // sort by "name desc, birthdate desc"
  [
    ["name", -1],
    ["birthdate", -1]
  ]

type: function
default: sort by is converted to SQL like value (e.g. name, birthdate desc, ...)

numberFilterFormatter

Function used to format numbers in filters, before they are used by the promise returned by getFetchPromise function. By default, getFetchPromise generates an AJAX request to a configured url; this function can be therefore used to create string representation of dates as desired. For GET requests, filters are placed in the query string; while for POST requests they are serialized in JSON. The function is called with two parameters: filter property name and value, to support different formats by filter property.

type: function
default: numbers are not edited

emptyValue

The string representation of null and undefined values.

type: string
default: ""

beforeRender

Function called before each table render. The callback is called without arguments, in the context of the instance of KingTable. This option is used regardless of builder type (plain text, HTML, Rich HTML or a custom one).

type: function
default: void function

afterRender

Function called after each table render. The callback is called without arguments, in the context of the instance of KingTable. This option is used regardless of builder type (plain text, HTML, Rich HTML or a custom one).

type: function
default: void function

onFetchStart

Function called before fetching data to display on a table. The callback is called without arguments, in the context of the instance of KingTable.

type: function
default: void function

onFetchDone

Function called after successful fetching data to display on a table. The callback is called with response object from the fetcher promise, in the context of the instance of KingTable.

type: function
default: void function

onFetchFail

Function called after failure in fetching data to display on a table. The callback is called without arguments, in the context of the instance of KingTable.

type: function
default: void function

onFetchEnd

Function called always at the end of a promise to fetch data. The callback is called without arguments, in the context of the instance of KingTable.

type: function
default: void function

onSearchEmpty

Function called when the text search is emptied. The callback is called without arguments, in the context of the instance of KingTable.

type: function
default: void function

onSearchStart

Function called when the text search starts. The callback is called with search string as input parameter, in the context of the instance of KingTable.

type: function
default: void function

onLayoutRender

Only for RHTML Builder. Callback fired when the table layout is rendered, with root element as parameter.

type: function
default: undefined

onFiltersRender

Only for RHTML Builder. Callback fired when the table layout is rendered, with custom filters view element as parameter.

type: function
default: undefined

onViewUpdate

Only for RHTML Builder. Callback fired when the table view is updated, with custom filters view element as parameter.

type: function
default: undefined

prepareData

Function called to alter the data fed to the KingTable, with the data as argument. This function can be used to alter items fed to the collection.

type: function
default: void function

Example: Alter items adding a foo property.

   prepareData: function (data) {
      data.forEach(function(i) { i.foo = "FOO"; });
   },

page

Initial page number. NB: by default, page number is cached in localStorage and restored upon page refresh. If caching of filters is enabled (default), this option is used only the first time a table is rendered.

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

For example, imagine that your custom filters view need to display a select element with a series of options (types and statuses); and these options need to be fetched from server side.

  getTableData: function() {
    return new Promise(function (resolve, reject) {
      // TODO: implement your logic to fetch table specific data (e.g. an AJAX request)
      // resolve promise with return object (reject in case of AJAX error)
      resolve({
        types: ["A", "B", "C", "D", "E"],
        statuses: ["1", "2", "3", "4", "5"]
      })
    });
  }

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

autoHighlightSearchProperties

Whether values that generate search match should be automatically highlighted by table builder, or not.

type: boolean
default: true

onItemClick

Allows to define a click event handler, for the click on items elements. The event handler automatically receive the item of the clicked element as input.

type: function
default: null

    onItemClick: function (item, e) {
      console.log(item);
    },

itemDecorator

Allows to define a function to decorate item HTML elements. The function must return an object that is used to generate attributes for the HTML element of each item.

    itemDecorator: function (item) { 
      // allows to define HTML properties for each item
      return {"style": "background-color: " + item.color};
    },

filtersView

Allows to define a custom filters view. The parameter can be:

the id of a script tag with type "text/html", containing the filter view HTML
a function returning an HTML fragment

When specified, the default Rich HTML builder adds an "Advanced filters" button to the interface and allows to hide/show the filters view.

type: string or function
default: null

filtersViewExpandable

Whether the custom filters view can be hidden/shown, clicking an "Advanced filters" button. If false, the custom filters view is always displayed below pagination controls.

type: boolean
default: true

filtersViewOpen

Whether the custom filters view should be immediately visible. This option is ignored if filtersViewExpandable is set to false.

type: boolean
default: false

tools

Allows to define custom tools, to be rendered in table menu.

type: function or array
default: null

Refer to dedicated wiki page for detailed information.

prepTools

Allows to define a function to alter tools schema, before menu rendering.

type: function
default: null

The function is called in the context of table builder, with menu schema as first parameter. It can alter this array before menu is rendered (for example, sorting the array, adding or removing items).

Columns options

Following is a description of columns options.

displayName

The name that should be displayed inside the table header. By default, if not specified, the object property name is used. When instantiating a KingTable, it is possible to pass just the display name as column schema.

type: string
default: == property name

secret

Whether the column should be displayed at all. If true, the column is not displayed by table at all.

type: boolean
default: undefined

hidden

Whether the column should be hidden. If true, the column is not displayed by default, but can still be made visible by user, using the columns menu (Rich HTML builder).

type: boolean
default: false

sortable

Whether the column should allow sorting. This option affects only user interface: sorting can still be performed by programmer calling the table.sortBy method.

type: boolean
default: true

type

Allows to define the column type; used by the object KingTable.Schemas.DefaultByType. This value doesn't represent the default JavaScript types, but something more descriptive. For example, in javascript typeof [] gives "Object"; but the KingTable object analyzer is more specific, and returns "array" as property type. When obtaining the columns schema; the KingTable first analyzes the structure of the first item inside its collection; then applies the default properties by found type.

type: string
default: "text"

The object KingTable.Schemas.DefaultByType is meant to be extended with custom logic; following what is returned by the default object analyzer.

_.extend(KingTable.Schemas.DefaultByType, {
  boolean: function (columnSchema, objSchema) {
    return {
      sortable: true,
      html: function (item) { return "HTML FRAGMENT"; },
      position: 990
    };
  }
});

Events

KingTable library includes an implementation of events emitter. Custom events are used to decouple business logic from presentation-specific logic. Following is a list of custom events raised by instances of KingTable.

"empty:element"

Raised before the table element is emptied, during HTML rendering.

input: HTML element (table element)

"no-results"

Raised when there are no results to display.

input: none

"get-list:failed"

Raised when Promise to fetch list data (items to display) fails.

input: none

"get-table-data:failed"

Raised when Promise to fetch table specific data fails (promise returned by getTableData function).

input: none

"fetch:start"

Raised before starting to fetch items to display. This function is fired also when data is obtained from cache.

input: none

"fetch:done"

Raised when items to display are fetched successfully. If multiple requests start at the same time, only the last one fires this event. This function is fired also when data is obtained from cache.

input: none

"fetch:fail"

Raised when a Promise to fetch items to display is rejected. If multiple requests start at the same time, only the last one fires this event. This function is fired also when data is obtained from cache.

input: none

"fetch:end"

Always raised when a Promise to fetch items ends, regardless of its result. This function is fired also when data is obtained from cache.

input: none

"fetching:data"

Raised before starting to fetch items to display. This function is fired only when data is not obtained from cache (promise returned by getFetchPromise function).

input: none

"fetched:data"

Raised after items to display are fetched. This function is fired only when data is not obtained from cache (promise returned by getFetchPromise function).

input: none

"change:pagination"

Raised when the pagination changes.

input: none

"restore:filters"

Raised when filters are restored from cache.

input: filters object

table.on("restore:filters", function (filters) {

});

"store:filters"

Raised when filters are stored inside the cache.

input: filters object

table.on("store:filters", function (filters) {

});

"hard:refresh"

Raised when the table is hard-refreshed - refreshing also cached data.

input: none

"search-empty"

Raised when the table text search is emptied.

input: none

"search-active"

Raised when table text search is active.

input: none