< Documentation Home

Searchable, Sortable Tables with DataTables

Want your List table to have a search box, clickable column sorting, and a "show 10/25/50 entries" menu? You can add the free DataTables library to your site yourself — it's not built into WebHaste, but it takes about five minutes.

What you'll need

This works with the List: Table block (see Lists for how to create a List and place it on a page). WebHaste doesn't include DataTables by default — it's a separate, free library, and adding it is a few small copy-and-paste steps in your site's template and page. Nothing here changes how Lists work, and sites that don't want it are unaffected.

Step 1: Turn off the List's own pagination

DataTables has its own paging, so having both on would show two sets of Previous/Next buttons. Open ⚙️ Site Admin → 🗂️ Lists, choose your list, turn pagination off, and click Save.

Step 2: Add DataTables to your template

If you don’t see Templates, Styles and Scripts tabs above your file list, open ⚙️ Site Admin → Site Settings and check Enable template, style & script editing. It’s off by default, so people who only edit page content never run into these files, and it’s a per-device setting — turning it on doesn’t change anything for anyone else who opens the same project. Then click the Templates tab and choose your template. (See Editing Templates, Styles, and Scripts for how these tabs work.) (Prefer a code editor such as VS Code? The file is in your project folder under .webhaste/templates/ — the one named in site.config.json as activeTemplate.)

Open your site's template for editing and add these two lines inside <head>, anywhere after the list.js line:

<link rel="stylesheet" href="https://cdn.datatables.net/3.1.2/css/dataTables.dataTables.min.css">
<script src="https://cdn.datatables.net/3.1.2/js/dataTables.min.js" defer></script>

DataTables 3 doesn't need jQuery, so these two lines are all there is to load. Keep the defer on the script tag so DataTables is ready before the startup script in Step 4 runs. Check datatables.net for the latest version number if you want to update the 3.1.2 above. If your site uses Bootstrap, DataTables also offers a Bootstrap 5 styling bundle that matches your table's look more closely — pick it from the same download page.

Step 3 (optional): Give one table an ID

Skip this step if you want DataTables on every List: Table on the page — the startup script in Step 4 finds them all on its own. You only need an ID if a page has several List tables and you want DataTables on just one of them.

On the page with your List: Table block, find the table controls and click the settings:

table-id.png

It should already have the table or table-auto classes. Add a unique ID value if one doesn't already exist, like shows-table.

Alternatively, you can switch to Code view and find the <table> tag. Add an id to it, like:

<table id="shows-table" class="table" data-list-src="/lists/shows.json" data-list-view="table">

Leave everything else on that tag exactly as it is.

Step 4: Add the startup script

Still in Code view, add this at the very bottom of the page (or paste it into the page's Header code field in Page Properties). It starts DataTables on every List: Table the moment WebHaste finishes drawing it:

<script>
document.addEventListener("cs-list-rendered", function (e) {
  var table = e.target;
  if (table.tagName !== "TABLE" || table.dataset.dt) return;
  table.dataset.dt = "1"; // the event can fire again; start DataTables only once
  new DataTable(table, { order: [] });
});
</script>

Why not just new DataTable("#shows-table")? WebHaste draws a List's rows in the visitor's browser, so on a published site they appear a moment after the page itself. If DataTables started right away, it would set itself up on the placeholder row and never notice your data. WebHaste announces each finished list with a cs-list-rendered event, and the script above simply waits for it. It also marks each table once it has started, because the event fires again whenever a list redraws (for example, if the list's own pagination is on).

The order: [] part tells DataTables to keep the sort order you chose for the List, instead of re-sorting by the first column. Remove it if you'd rather DataTables sort by the first column to begin with.

Only want DataTables on one table?

If a page has several List tables and only one should get DataTables, give that table an ID (Step 3) and add one line to the script, naming that ID:

<script>
document.addEventListener("cs-list-rendered", function (e) {
  var table = e.target;
  if (table.id !== "shows-table" || table.dataset.dt) return;
  table.dataset.dt = "1";
  new DataTable(table, { order: [] });
});
</script>

The version from Step 4 can also live in your template's <head> or your site's scripts/main.js file, so it applies to every page with a List table automatically. It just needs to load before the page finishes loading, which any script in the <head> or at the bottom of the page does.

Does your site have the "list rendered" event?

The event comes from your site's scripts/list.js. WebHaste copies that file into a project once, the first time you open it, and never overwrites it afterward, so a site started before the event was added has an older copy that never fires it. The Step 4 script would then do nothing at all, with no error.

To check, open the Scripts tab (see Step 2), choose list.js, and look for cs-list-rendered — or search for it in a code editor. If it's missing and you've never edited list.js yourself, delete scripts/list.js from your project folder and reopen the project in WebHaste; a fresh, current copy is put back automatically. If you did customize it, copy your changes into the new version by hand instead.

Stuck with an older list.js? Use this version instead.

This script works without the event. It checks right away whether the real rows are already there, and otherwise watches the table until they appear. It needs the table's ID from Step 3 — change shows-table to yours:

<script>
document.addEventListener("DOMContentLoaded", function () {
  var table = document.getElementById("shows-table");
  if (!table) return;
  var tbody = table.querySelector("tbody");
  function start() {
    if (tbody.querySelector(".cs-list-placeholder-cell")) return false;
    new DataTable(table, { order: [] });
    return true;
  }
  if (!start()) {
    var obs = new MutationObserver(function () {
      if (start()) obs.disconnect();
    });
    obs.observe(tbody, { childList: true });
  }
});
</script>

It has to check first and watch: on a published site the rows arrive a moment after the page, but in a Packaged (file://) build the list's data is built into the page, so the rows already exist by the time the script runs and a watcher alone would never fire.

Things to know

  • You won't see it in the editor. Like every List block, the editor and live Preview show only a placeholder, and outside scripts can't run in Preview at all. Publish, or use Render to Local Folder and open the result in a normal browser tab, to see the real thing.
  • Link and image columns work. Links stay clickable. Image-only columns can't be searched or sorted, since they have no text.
  • Offline (Packaged) sites: your List still renders, but DataTables is loaded from the internet. For a site that must work with no connection at all, download the DataTables .js and .css files, put them in your scripts/ folder, and point the two tags in Step 2 at /scripts/… instead.
  • Styling: DataTables adds its own classes (dt-search, dt-length, dt-paging) around your table. See the DataTables styling docs to customize them.

DataTables can do a lot more — column visibility, export buttons, fixed headers, and so on. Its examples page shows what's possible; anything there that works on a plain HTML table works on a List: Table.