Back to API overview

TABLE Object

The table object is a generalized table that appears all over the interface. It contains data ready for display and allows interaction with the user. The implementor doesn't need to understand the business domain of floorball.

The json for a table object looks like this: 

{
  type: "table",
  data: {
    context: CONTEXT,
    title: TITLE, 
    tabs: TABS, 
    slider: SLIDER, 
    header: HEADERS, 
    regions: REGIONS
  }, 
  reload_link: LINK
}

See documentation on page 27 (point 5.5) for a good example. An example for multiple regions can be found on page 30 (bottom) (point 5.6.2).

TITLE

Title of the table, will be displayed in some sort of header

TITLE = 'text'

CONTEXT

Context in which the current data has been fetched.

Basically it's a hash containing all the values necessary for the API to reproduce the current result, i.e. the variables accepted by the current method to select the data provided for this call.

Currently the only usage of the context is to build navigation links, the view doesn't presently use this information, and the view implementor does not need to understand the contents of context. 

"context": {
  "game_class": 11,
  "league": 1,
  "round": 7,
  "season": 2013
}

Navigation links are built using the gen_reload_link() function. The URL is generated based on the current context modified as per the context difference passed as an argument. This links will call the API anew, hence generating a full reload.

RELOAD_LINK = { 
  type: "reload", 
  set_in_context: OBJECT, 
  resource: 'text'
}

The term reload stands for loading new data for the same table with a (possibly) new context. To reload the current table using a reload link, you should expand the tables context by setting all the keys present in set_in_context to the values given. Then encode the request as usual (either by expanding the resource url using the base url or by bundling it with other requests) and redisplay the result of this operation.

TABS

Set of navigation links in the form of clickable tabs with a reference text. The currently displayed one is highlighted. Built with add_tab() providing text, link and highlighting value. Links are built with gen_reload_links().

TABS = [TAB]
# TAB is one of LINK_TAB, DROPDOWN_TAB 
LINK_TAB  = {
  text: 'text', 
  link: LINK, 
  type: "link", 
  highlight: 'bool'
}

Function add_dropdown_tab()

A dropdown tab is a way to integrate a hierarchical expandable dropdown navigation menu into the table's tab system. A call to add_dropdown_tab() will add a dropdown menu in the place of a tab. This is built passing the tab text, the API method base, and the list of headers (?) for the entries nested under it. The API method base is the particular way used to build links in the dropdown: each entry will contribute with a part of the context, to be based on the parent hierarchy - hence the add_dropdown_tab() being the root requires the base of the call (the API method to be called).

DROPDOWN_TAB = {
  type: "dropdown",
  levels: ['text'], 
  entries: [ENTRY], 
  resource: 'text', 
  highlight: 'bool'
}

levels contains the labels to show on each of the dropdown levels when no element is selected. Data is tree-like to a maximum depth equal to the size of levels.

Function dropdown.add_entry()

Adds an entry to a dropdown. The entry is built through dropdown.entry() (just an hash builder/setter). Each entry is expected to have a text, a context diff, an highlighted boolean, and an optional set of entries to be nested under it.

ENTRY = {
  text: 'text', 
  set_in_context: 'object', 
  highlight: 'bool', 
  entries: [ENTRY]
}

highlight on all levels is set if the current request could have come from selecting the tab. Whether it really did is a matter of UI state and cannot be handled in the backend.

SLIDER

SLIDER = {
  text: 'text', 
  links: {
    # All keys optional: 
    prev: LINK, 
    next: LINK, 
    across: { text: 'text', link: LINK }
  }
}

REGIONS

REGIONS = [REGION]
REGION = {
  text: 'text',   # (1)
  rows: [ROW]
}

ROW

A row is a list of cells, at most as long as the header.

Text lines inside cells indicate layout entities that should not be line wrapped inside. For example, if a cell contains two lines, care should be taken to output two lines. If lines are too long, each of the lines should be abbreviated using an ellipsis ('…').

ROW   = {
  highlight: 'bool'
  cells: [CELL]
}

CELL  = {
  text: ['text'], 
  link: LINK
}

HEADERS

Table headers contain labels for all table columns, provide alignment and table proportions, and will control allowed sorting for the table.

The same headers are common for all regions in the view. They could be repeated in each region for eye candy, but they're defined only once, globally, at table level. Alignment can be either 'l' for 'left', 'r' for 'right', or 'c' for 'center'.

Headers should be clickable to sort data based on that column. TBD: clicking and sorting behaviors are managed at view level.

HEADERS = [HEADER]
HEADER  = {
  text: 'text', 
  long: 'text', 
  short: 'text', 
  prefer: 'one of "short", "long", "fit"',
  align: 'one of "r", "l", "c"', 
  width: 'integer'
}

The width is proportional over the sum of all header widths: if three headers have widths 1, 2 and 1 respectively, the second header will take 50% of the rendered table width (1+2+1 == 4, 2/4 == 0.5), with the other two occupying 25% each.

You should look at prefer to know which of {long, short} to use as a header text. If prefer has the value "fit", you should use long if possible and short if you must.

Abbreviated headers (using short) should be explained in a legend of the form 'SHORT: LONG' below the table.