Lists

A List Dashboard is used by specifying kind: "list" in the specification when instantiating a Dashboard object.

It adds functions to the Dashboard interface that help generate a list-based dashboard, in the form of a table with headings, and a number of columns, where each row represents one object that we are reporting on.

Interface

In addition to the standard Dashboard interface, List dashboards provide:

function columns(priority, columns)

Add one or more columns to the Dashboard.

priority is a number used for sorting the columns.

columns is a list of column definitions, which are either fact names as strings, or objects with the following common properties:

Property Description
type The column type. If no type is specified, then infer using the definition of the specified fact
fact Defined name of the fact
heading Heading displayed for the column. If no heading is specified then the description specified in the collection fact definition is used
exportHeading Heading used when the column is exported. Defaults to heading if not specified
style Style to use for the column, one of “wide”, “medium”, “small”, “tiny”

If a column definition is specified as a string, it’s interpreted as {fact:"factName"}, which will infer the type from the fact definition and render in an appropriate fashion.

NOTE To display the name of the object being reported on, use the implicit "ref" fact. If the object is a person, use a column definition like {fact:"ref", type:"ref-person-name", heading:"Name"}.

Different column types support and may require more than these properties. See the list of column types below.

function hasColumnBasedOnFact(fact)

Returns true if the dashboard currently has a column based on the fact.

property columnCount

The number of columns currently added to this dashboard.

Standard features

The List dashboard provides some standard features that can be utilised with the Dashboard use() function.

std:row_text_filter

Displays a simple text search widget which filters the dashboard as the user types.

It takes one argument, a specification object with the following properties:

Property Description
facts An array of facts that can be searched/filtered by
placeholder Text to be displayed when the search box is blank

For example:

dashboard.use("std:row_text_filter", {
    facts:["title","author"], 
    placeholder:"Search"
});

std:row_object_filter

Displays a dropdown widget which filters the dashboard where the specified fact matches the value selected in the dropdown.

It takes one argument, a specification object with the following properties:

Property Description
fact The fact to be used for filtering, must be a Ref
objects Either a type Ref from the schema requirements which generates a list of all Objects with that type, or a function that returns a list of objects with a ref and title property

For example, a simple object filter by type:

dashboard.use("std:row_object_filter, {
    fact:"author", objects:T.Author
});

Column types

simple

simple columns render the value of the fact as a string

ref

ref columns render the title of the object stored at the ref as a string and have the following optional properties:

Property Description
link Boolean. If true, the text is rendered as a link to the object specified by the fact
shortestTitle Boolean. If true, the shortest title attribute on the object is displayed

The ref type is used automatically if the fact specified has type ref

ref-person-name

When used with objects that have Person Name titles, ref-person-name will render them as “Last, First”, and the exported data will have each field of the name in a separate column.

Property Description
link Boolean. If true, the text is rendered as a link to the object specified by the fact

date

date columns render a date fact as a human readable string, by default the column uses the formatting “01 Jan 2015”, but alternate formatting can be specified using a property:

Property Description
format String. Format to use to render the date, as a standard date and time format string, default: (“dd MMM yyyy”)

The date type is used automatically if the fact specified has type date

datetime

Same implementation as date, except uses "dd MMM yyyy HH:mm" as the default format to also display time.

The datetime type is used automatically if the fact specified has type datetime

end-date

Same implementation as date, except for dates from the end of platform time ranges to prevent them showing the day after the last day of the range.

The end-date type is used automatically if the fact specified has type end-date

date-with-age-warning

date-with-age-warning columns act similarly to date columns, but allow styling to be applied dynamically based upon the value of the fact. The following properties can be used to control styling:

Property Description
format String. Format to use to render the date, as a standard date and time format string, default: (“dd MMM yyyy”)
warnDate Date. If the value of the fact is later than this date, then a warning hint (orange background) will be applied to the cell
errorDate Date. If the value of the fact is later than this date, then an error hint (red background) will be applied to the cell
successFact String. Name of a fact that implies a success condition. If the specified fact has a truthy value then a success hint (green background), overriding warn or error styling
determineCellStyle Function. A function with an argument row (an object containing all the facts for this row, accessible as row.factName), that can be used for more complex styling/warning rules. The function should return one of "warn" "error" or "success"

json

json columns pick a value to display from the JSON structure for json type facts.

This is useful when combined with some navigation UI to display related values, for example, values from different years. You can delegate the display to another column type using the column property.

Property Description
valueProperty (Optional) String. The property to use from the fact’s value, defaults to the "std:reporting:json_column:default_value_property" dashboard property
column (Optional) Column definition to use to display the value.

If you use the column property, the column definition must include the type. For example:

  {fact:"aJSONcolumn", column:{type:"date"}}

All the date types will automatically parse the value as a date using the XDate library. You must use ISO8601 format, for example, "2016-07-12T14:30:00".

If you’re displaying numbers from your json column, use a number type, for example "int", to display numbers nicely.

The "lookup" column type might be especially useful.

int

int columns display a number, rendering a grey dash when the value is 0

The int column type is used automatically if the fact specified has a type that is int float smallint or bigint

boolean

boolean columns render a unicode tick (✓) if the fact has a true or truthy value

It is possible to specify a truth function and use custom logic to determine whether a value should be true or false, as a column property:

Property Description
truthFunction Function. A function with an argument value (the value of the fact) which should return true or false

The boolean column type is used automatically if the fact specified has type boolean

lookup

lookup columns allow you to translate the value stored in the fact into a string to display. The result of looking up the value in a dictionary Object or calling a function is displayed and exported.

Property Description
lookup A dictionary Object or function used to look up the display value.

If a function is specified as lookup, it is called with two arguments, the first is the value to look up, and the second is the row object containing all the facts. This enables you to abuse lookup columns to perform arbitrary calculations using one or more facts. For example,

  lookup: function(value, row) {
    return row.first + " " + row.last;
  }

join

join columns provide an easy way to concatenate multiple facts into one column. It has the properties:

Property Description
columns Array. An array of column definitions
joinWith String. A string to use to separate the joined values (default: ", ")

attribute

attribute columns retrieve data directly from an object. There must be a fact property that refers to a ref, and a desc property that is an attribute defined in the schema requirements.

Property Description
desc Attribute. The attribute from the schema that we should retrieve data from

This column type should be used sparingly, in cases where there is data that doesn’t make sense to track as a fact but is still useful to display in an export for instance. It should not be used in place of facts, and is much slower than retrieving facts.

Email addresses for example, while not interesting enough to be defined as a fact, may be very useful to include on a dashboard export where people are involved for a mail-merge or similar.

linked

linked columns allow you to render any column type as a link. A column property must be specified or else an exception will be thrown. The default link if no link property is specified is the object the current row refers to.

Property Description
column Column. A single column definition
link Function. A function with an argument row (an object containing all the facts for this row, accessible as row.factName), which should return a URL as a string

html

html columns are used for rendering arbitrary HTML. Avoid using them as it’s easy to forget to escape the values. Consider using a lookup column instead.

HTML column definitions have the following properties:

Property Description
displayHTML Function. A function with an argument row, which should return a string of text or HTML to be rendered
exportValue Function. A function with an argument row 1, which should return a string of text to be used in a spreadsheet when exporting
sortValue Function. A function with an argument row 1, which the UI can use to provide custom sorting when the table is sorted by this column
exportOptions String. A value passed to the xls.cell function as the second options argument

Notes

1 row refers to the row object which has access to all of the facts for the current object. Facts are properties and can be access directly, for example, row.exampleFact will retrieve the value of “exampleFact”