Basic usage

import * as qdt from "@qnc/qnc_data_tables.js";
// You can also subclass Renderer and override any of the methods, then use that
qdt.define_custom_element("qnc-data-table", new qdt.Renderer());
// now any <qnc-data-table> elements will automatically be handled

Setting up our styles

import * as qdt from "@qnc/qnc_data_tables.js";
document.head.appendChild(qdt.create_style());

Note: in the future, we might provide a css file which you can host/inject as you see fit. For now, this is the only supported technique.

Filter Forms

By connecting a data table to a form (via the filter_form_id configuration parameter), we'll submit that form's data every time we refresh the table. We'll also refresh the table every time the filter form dispatches a submit event. We do NOT, however:

• call preventDefault() on the form's submit event (you definitely need to this)
• automatically trigger the form to submit at any time (you might want to trigger the form to submit on every change, or even every input)

Interacting with the table via JS

Our custom element exposes a required_table_manager() method, which returns a TableManager instance. The TableManager allows you to:

• add/remove selected rows
• get ids of selected rows
• trigger the table to reload

See table_manager.ts for the full API.

Selection actions

qnc-data-table elements do not render any kind of "selection action buttons" (ie. things that can be done with the selected items). These elements do expose a TableManager, however, which you can use to implement your selection actions.

If you want to define your selection action buttons in your backend (ie. initial page html), we recommend using register_selection_fieldset_controller_custom_element.

Cell options / transformations

The cell content (html) returned by the backend will undergo one of several possible transformations, depending on what that html specifies. I don't like this approach, but it seems to be the only way to support several important patterns while protecting from common pitfalls.

Here we describe the different transformations in the same order in which we test the content. This is, roughly speaking, least common to most common.

In the subsequent sections, when we talk about "cell html matching an element", we mean that the string of html represents one complete element, with no surrounding text (not even whitespace). <b>Something</b> matches a b element, but <b>Something</b> does not.

<* data-qdt-full-cell>

If the cell html matches one element with attribute data-qdt-full-cell, then that element will be used directly as the entire cell. It's parent element is a flex container, which will stretch it to the width of the column and height of the row.

It will match a CSS selector with a specificity of 1 class applying the following rules:

.some-class-selector {
    padding: var(--qdt-cell-vertical-padding) var(--qdt-cell-horizontal-padding);
}

You may change the padding, as you see fit.

With this approach, you're opting out of our techniques for aligning the content within the cell. You're on your own.

If you set display to flex or grid on such an element, and that element has direct text node childen, then our text-overflow: ellipsis style won't work reliably.

or

If the cell html matches exactly one a or div element, then that element will be used directly as the entire cell. It's parent element is a flex container, which will stretch it to the width of the column and height of the row.

The element will "receive" standard padding, horizontal alignment (of children), and vertical alignment (of children). Specifically, it will match:

.some-class-selector {
    padding: var(--qdt-cell-vertical-padding) var(--qdt-cell-horizontal-padding);
    display: flex;
    align-items: var(--qdt-cell-align-items); /* for vertical alignment */
    justify-content: var(--qdt-cell-justify-content); /* for horizontal alignment */
}

You may change the padding, as you see fit. You may change the align-items or justify-content to set the vertical or horizontal alignment to something that differs from that of the table/column.

Whatever content is inside this element will automatically be wrapped in an extra div. This serves two purposes:

• restores standard flow layout (while allowing us to align the content as a group)
• enables text-overflow: ellipsis; to work on text nodes (if they were directly inside the flex parent, then text-overflow wouldn't work)

The purpose of using a "div wrapper" is to allow you to change the padding or content alignment (via the style attribute).

The purpose of using a "link wrapper" is to allow the entire cell to be clickable (and you can also change padding or alignment via style attribute).

or

These behave just like a / div elements, except that their content is wrapped in a span, instead of a div (since neither of these elements may have div children, according to the HTML spec).

As with link elements, the purpose here is to create full-cell clickable elements.

Anything else

Any other content will be wrapped in two nested div elements. The outer one has the padding and display flex. The inner one is "plain". You have no ability to change the padding or alignment.

Common Patterns

Triggering all tables on the page to reload

import { BaseQncDataTable } from "@qnc/qnc_data_tables";

for (const table of document.querySelectorAll('qnc-data-table, qnc-data-table-admin')) { // whatever custom element names you've registered
    if (!(table instanceof BaseQncDataTable)) {
        console.error(`Found a ${table.tagName} element which is not a BaseQncDataTable. Did we register the custom element properly?` )
        continue
    }
    table.required_table_manager().reload()
}

TODO

• Move column controls into top control bar, use qnc-dialog instead of details
• clean up styling, document how to customize (use custom css properties on the root element?)