Skip to main content

Data Renderers

Styling can be applied to DataFrames using Data Stylers. However, there are times when you want to render data differently rather than just changing the styling. Here are some use cases.

  1. A single card layout instead of a row layout where multiple fields are all organized in a free-format.
  2. Visual representation of data such as showing stars for the ratings field.
  3. Concatenate multiple fields in a single cell.

Some of the above use cases can be solved using calculated fields although that is unnecessary if the calculation is only required for data presentation.

Data rendering is accomplished using templates. SQL Frames uses Eta to create and evaluate the templates.

Row renderer

Here the requirement is to render the entire row as a custom block with important information for the user. This is done using the df.fmt.setRowRendererProvider() API.

Let's go through the key API elements. The template itself is created using tag API provided by the df.fmt formatting plugin. The content of the template can be any valid HTML which can access the current row data using two variables it.v and it.dv. it.v provides access to the raw values while it.dv provides access to the display values which are generated by applying formatting such as localization to the raw value. If the field name is a valid javascript variable name, then it can be directly specified using the dot notation such as it.dv.Region. But if it is not a valid javascript variable name, then the indexing notation has to be used such as it.dv["Item Type"].

Security considerations

The values accessed using it.dv are sanitized to prevent xss attacks. The values accessed using it.v are raw values that are not sanitized. They are expected to be used within the template only for any sort of calculations and never to directly render them.

Even though the data is not rendered as a regular table-row the markup still uses table and table rows ensuring the infinite scrolling with virtual table rendering is still available with data renderers.

pdf.fmt.setRowRendererProvider is the API used to specify the row renderers. The getRenderers API returns an array of 1 or more row renderers. This allows the same data row to be rendered as multiple rows in the presentation layer.

Dark Mode

Toggling of dark mode can be supported by defining style sheet with css variables that change based on html[data-theme='dark'] or using the it.darkMode boolean and conditionally changing the style inline as shown above.

With event handling

The template provided for rendering can contain javascript code. Below example shows how a link is provided with a javascript event handler.

Security considerations

As mentioned above, only the display values are sanitized for xss attack but not the template. This is because, the developer writing the template or the end user using the template is expected to trust the code but not the data they are working with.


Row and Row Renderer

It is possible to render the regular row along with row renderer. This is possible using pdf.fmt.defaultRowRenderer which is a special row renderer giving the default behavior.


When both the row and renderer are displayed, the up/down arrow key navigation will only work on the first column (since the renderer row contains a single column spanning the entire row).


Hierarchical Row Rendering

SQL Frames allows making any DataFrame into a hierarchical DataFrame. These hierarchical data frames by default are rendered as a hierarchical grid. However, an alternative presentation of grouped lists like in Numbers on Mac can be created using row renderers as shown below.


Cell Renderer

Cell renderers have access to the data from the entire row. Hence, they can augment the cell details with other details from the row. In the following example, the Country cell is augmented with the Region it belongs to.

df.fmt.setFieldRenderer API is used to set the field renderer for a field. A field can have only one cell renderer.