Skip to main content

View Settings and Shareable Links

A view table lets each user adjust how a table looks and keep those choices, and lets them share what they are looking at. These are two separate facilities that persist in different places.

View Settings​

The View Settings dialog (provided by juneau-config.js) has four tabs: View, Search, Sort and Options. It lets the user change the visible columns, their labels, format and order, which columns are searchable and sortable, the page size and wrapping.

  • Apply commits the settings to the page-state store, keyed per table, so several tables on one page never overwrite each other. A reload restores them.
  • Settings are stored through JuneauViews.pageState (see JavaScript API), not in the address bar.
  • The dialog starts from the catalog defaults, and the saved blob is overlaid on top of them.
  • Saved view names have a maximum length, and Default is a reserved name.

For the dialog's tabs, the schemaVersion guard, settings applied on load, the Sort tab, auto-refresh and the Copy link button, see Datatable View Settings.

To keep settings somewhere other than browser localStorage, install a store with JuneauViews.pageState.useStore({getItem, setItem, removeItem}), or supply a persistence provider through JuneauViews.setPersistenceProvider(provider).

Copy link builds a URL for what the user is currently looking at: the selected tab, the active filters and the sort. The state is one readable ?state= query parameter, placed directly in the address bar.

  • JuneauViews.urlState.buildShareUrl(location, state) always includes ?state=, even when the clean-address option is on.
  • JuneauViews.urlState.copy(navigator, text) writes to the clipboard and resolves true or false; it never throws where the Clipboard API is absent or denied.
  • The catalog's cleanAddress key keeps the live address bar free of ?state=; Copy link still produces the full URL.
  • The view's urlState key (TableSpec.urlState(String...), or urlState: {day: {}} in a catalog) enables built-in directives. day carries day(YYYY-MM-DD) in ?state= and restricts the table to rows whose date falls in that calendar day's [start, end) window; a malformed or impossible date is ignored. The server resource receives the value as a day query parameter by default; to use another name, call TableSpec.urlStateDayParam("on") (or set urlState: {day: {param: "on"}} in a catalog), and the request carries on instead. Views without the key behave as before.

Open precedence​

When a page opens with ?state=, that state wins over the browser store for tab, filters and sort. It does not replace the recipient's saved View Settings: those are a separate store facet that the URL codec never touches. So a shared link shows the sender's filters and sort, laid out with the recipient's own column choices.

Hand-built pages

The views toolkit pack includes juneau-urlstate.js, so <@page toolkit="views"> pages get Copy link automatically. A hand-built page that uses Copy link must load ViewsMixin.URLSTATE_JS_PATH itself, after juneau-pagestate.js.