innoq/tabelle

A library for generating pretty filterable and sortable tables that use your backend of choice

title: Tabelle

tabelle

A library for generating pretty filterable and sortable tables that use your backend of choice

This library uses custom elements. In order for this to work, you need to use a browser which support it or use a polyfill.

Install

npm install @innoq/tabelle

OR you can install tabelle from the unpkg cdn

The CSS styles are available from:

• https://unpkg.com/@innoq/tabelle@{VERSION}/dist/tabelle.css (with minimal styling for the table element)
• https://unpkg.com/@innoq/tabelle@{VERSION}/dist/tabelle-base.css (provides only base css for the structure of the components)

The JavaScript is available from:

• https://unpkg.com/@innoq/tabelle@{VERSION}/dist/tabelle.js (for tables rendered on the server)
• https://unpkg.com/@innoq/tabelle@{VERSION}/dist/tabelle-cljs.js (for tables rendered on the client)

How to Use Tabelle with SSR

Tabelle expects that you have an HTTP Resource which renders an HTML Table. In order to activate Tabelle, we can encapsulate our HTML Table in the <ta-belle> custom element which contains a link to the HTTP Resource:

<ta-belle id="tabelleId" search-src="/components/preview/tabelle--custom-element-state">
    <table class="tabelle">
        <thead>
            <tr>
                <th name="foo">Foo</th>
                <th name="bar">Bar</th>
                <th name="baz">Baz</th>
            </tr>
        </thead>
        <tbody>
            ...
        </tbody>
    </table>
</ta-belle>

The id attribute is required for the ta-belle.

The contract is that the <th> elements receive a name attribute which corresponds to the query parameter which will perform filtering for this column. If you leave the name column away, the column will remain unchanged.

What Tabelle does is generate a form for your table in an HTML form and then generate a different header for each column which has the input fields you need in order to perform querying against your backend. The HTML form for Tabelle is rendered next to your table and connected to the filter inputs in your table via the form attribute. This means that you can also have other HTML forms embedded inside of your HTML table if you want to.

By default, Tabelle will generate a text input field with the name specified by the <th> element (e.g. foo). This means that when you input text in the field and the form submits, a query will be generated with the query parameter ?foo={your text}.

By default, Tabelle will also generate a sort option for sorting ascending or decending. This is also an input field which will have the name sort. The value for the input will be the name of your column plus the direction (e.g. for <th name="bar"> the inputs with values bar-asc and bar-desc will be generated.) This means that when you select an arrow and the form submits, a query will be generated with the query paramter ?sort={{name}-asc or {name}-desc}. By default, Tabelle generates the value asc for ascending and desc for decending sort order.

By default, Tabelle will autosubmit its form whenever the user inputs a filter or clicks on the arrows in order to sort the column. Tabelle will take the result from submitting the form and replace the <ta-belle> element with the <ta-belle> element with the same id that is retrieved from the server.

The sorting and filtering logic need to be implemented in the backend.

It is also currently possible to add a select field to filter a column instead of a text field. Since we believe that HTML is the best description language to describe itself, we have implemented this by allowing you to render a select field in your <th> with the class .tabelle-input. If this is the case, this select field will be used instead of generating an input field.

<th>
    My header
    <select class=".tabelle-input" name="searchMe">
        <option>Option1</option>
        <option>Option2</option>
        <option>Option3</option>
    </select>
</th>

Since Tabelle replaces the entire HTML of the <ta-belle> element, you also need to ensure that the filters and sort direction that you sent to the server are rendered in the DOM that you return. You can set the filter when rendering a column via the value attribute of the th element.

<th name="foo" value="Faa">Foo</th>

To set the sort direction for a <ta-belle> you can set the sort attribute of the ta-belle to the name-direction where the name is the name of the column and direction is the direction for the sort (either asc or desc). This is also the value of the sort query parameter which is sent to the server whenever you change the sort direction.

<ta-belle sort="foo-asc">...</ta-belle>

Handling empty result sets

When you have made a search query and no results are found, it may be likely that you want to add some helpful message for the user letting them know that no search results are found. We want to allow maximum flexibility and allow you to translate and style your message however you would like.

To help you do this, just add the extra information in the <ta-belle> component. This will then appear when <ta-belle> replaces the content of the <ta-belle> component.

<ta-belle id="tabelle" search-src="...">
    <table>
        <thead>
            <tr>
                <th name="foo" value="NON-MATCHING-STRING">Foo</th>
                <th name="bar">Bar</th>
                <th name="baz">Baz</th>
            </tr>
        </thead>
    </table>
    <p>We did not find any search results for the filters you specified!</p>
</ta-belle>

You can also use this feature in order to embed a pagination component in your <ta-belle> which will be replaced after each round-trip with the server.

How to Use Tabelle with CSR

As of v0.4.0, Tabelle also offers a custom element which will do the filtering and sorting of tables on the client as a progressive enhancement. This custom element is named <tabelle-cljs> and has a very similar API to that of <ta-belle>. The JavaScript for this component is bundled separately because it is a larger bundle (ca. 54KB) and you will probably only want to add the JavaScript dependency if you actually have a sortable table in the HTML which you are serving to the client.

It should be possible to use both <ta-belle> and <tabelle-cljs> in your application if for some of your tables you need to do sorting and filtering on the server and for other tables, the progressively enhanced version is sufficient. The CSS and HTML Markup for both is compatible, so any styling or customization that you do will work for both.

Tabelle Search

It is also possible to add a <tabelle-search> component which connects to a Tabelle and provides the Tabelle with a search over all columns within the table. The <tabelle-search> component communicates with the Tabelle by sending an Event to the Tabelle implementation while the user is typing in an input field contained in the component. This works with either the <ta-belle> or <tabelle-cljs> components.

Options

In <ta-belle> or <tabelle-cljs> you can add the following properties to activate the following behavior

Property	Behavior
change-uri (<ta-belle> only)	Modifies the browser history so that by forward/back you can restore the searches that have been made
sort	Value of the current sort direction. If either 'asc' or 'desc' is set, the ascending or descending arrow will be automatically selected
nofilter	Deactivates automatic generation of filter fields for whole table
debounce	Number in milliseconds to debounce before sending an input field to the server (Default 300)

In the <th> headers, you can add the following properties to activate the following behavior

Property	Behavior
name	ta-belle: The name of the query parameter which is used for searching. If no name is specified, no filter column will be generated tabelle-cljs: name is optional and can be used to customize the name of the class that is added to all the columns to activate sorting and filtering
value	specifies value which will be set for the generated input field
nosort	if no sorting functions should be generated for the column
nofilter	if not filtering functions are generated for the column

If the <tabelle-search> is positioned within either a <ta-belle> or <tabelle-cljs> no further configuration is needed. If the <tabelle-search> is positioned outside of the Tabelle, it can be configured as follows:

Property	Behavior
tabelleId	Indicates the HTML ID of the Tabelle with which the <tabelle-search> should communicate

Styling

We have made the styling as minimal as possible in order to allow you to customize the table as much as possible!

Resources

• Example Rails App
• Example Express App

Icon Attribution

Tabelle uses icons which are licensed under the Font Awesome Free License.

tabelle's Issues

Show a clear error when you provide query parameters

I used tabelle for a form where I have a query parameter that I need to be submitted alongside the tabelle parameters. Let's say I have invoices, and I always filter them by their status:

/invoices?status=paid

So I did this:

<ta-belle search-src="/invoices?status=paid">
  ...
</ta-belle>

When I do this, I get the following exception:

query strings are invalid within GET forms' action

The solution is to do this:

<ta-belle>
  <form action="/invoices">
    <input type="hidden" name="status" value="paid">
  </form>
</ta-belle>

I like the solution, but I think that:

1. The error should be more straight forward
2. The README should point out how to handle that in a FAQ section

What do you think? Thanks for the project, it really helps me get things done <3

When you click on a sortable arrow, it should be deselected.

This is a JavaScript only feature (because you can't deselect a radio button in HTML), but it would be nice.

Add a bit more flexibility to displaying a response

When a user does a search that comes back with no results, I want to show a helpful hint like "Your search did not return any results." I want to be able to translate this and I want to be able to style it, so I would like to generate that answer on the server side. However, I can currently only return a tbody, so I don't have that option. Suggestion:

The user needs to provide an id on the ta-belle element. If they don't, they will receive an error (I think I would just do a console.error("...") and then not activate ta-belle). When ta-belle receives the answer from the server, it will search for the element with the same ID and replace its content with the content of that element. Afterwards, it will re-add the filters. This allows users to add additional elements to the response other than the table.

What do you think? Thanks for the project, it really helps me get things done <3

The SVGs have hard-coded paths

The SVGs for the arrows have hard-coded paths, so if you install tabelle as an NPM package, the images won't be found:

https://github.com/innoq/tabelle/blob/master/components/atoms/radio-arrow/_radio-arrow.scss#L7

This needs to be configurable somehow 🤔

i18n for labels in custom element

Currently, the labels for the components that are generated by the custom element (e.g. sort arrows, filter field) are hard coded so that they contain English text. We should add an option to customize the texts so that Tabelle can be used in other languages.

Make customElements polyfill optional

The customElements polyfill should not be a part of this bundle, but rather should be able to be added explicitly by users only when they need it.

When installing as an NPM package, you need to provide the path

If you install tabelle as an NPM package, you have to import it like this:

import 'tabelle/dist/tabelle';

We can shorten that to:

import 'tabelle';

by setting the main attribute in the package.json to dist/tabelle.js 😄

A demo GIF

I think the README would benefit from a GIF screencapture of ta-belle in action. When I search for libraries that offer UI stuff, I always like to see it in action – and I prefer to do that without needing to install it first 😸