Linking Between Boards¶

Connect boards with Markdown links or chart link: fields. Dataface rewrites both at render time so the same YAML works in both dft serve and Cloud.

Drill down from charts and tables¶

Charts and tables support a link: field that turns each data element into a clickable link — navigating to another board or updating a variable in-place. Board-root paths are resolved the same way as Markdown links.

charts:
  tickets_by_status:
    type: bar
    query: tickets
    x: status
    y: count
    link: "/zendesk/tickets/list?status={{ x }}"   # {{ x }} = clicked bar's status

For tables, link: can be set at the chart root (applied to every cell) or overridden per column in style.columns:

charts:
  tickets_table:
    type: table
    query: open_tickets
    link: "/zendesk/tickets/detail?id={{ ticket_id }}"   # default for all cells
    style:
      columns:
        status:
          link: "/zendesk/backlog/?status={{ status }}"  # overrides root for this column

See Chart Interactions for the full link: reference.

Root-relative paths¶

Paths start with / and are relative to the dashboard namespace root — not the file system. You never type a storage prefix like faces/.

text: |
  [Open tickets](/zendesk/tickets/list?status=open)
  [Ticket detail](/zendesk/tickets/detail?id={{ ticket_id }})

/zendesk/tickets/list resolves to the board stored at faces/zendesk/tickets/list.yml (same path in Cloud — both use faces/).

Relative paths¶

../ and ./ resolve against the current board's directory.

If you are on zendesk/tickets/list:

Link	Resolves to
`./detail`	`zendesk/tickets/detail`
`../overview`	`zendesk/overview`

text: |
  [Detail view](./detail?id={{ ticket_id }})
  [Back to overview](../overview)

Query parameters and variables¶

Query strings on links map directly to dashboard variables. This is how you pass context between boards:

text: |
  [See ticket](/zendesk/tickets/detail?id={{ ticket_id }}&status={{ status }})

Suffix stripping¶

You can optionally include .md, .yml, or .yaml suffixes — Dataface strips them automatically:

text: |
  [Tickets](/zendesk/tickets/list.md)

resolves identically to /zendesk/tickets/list.

External links¶

Links starting with http://, https://, mailto:, or # are never rewritten — they pass through unchanged.

In Dataface Cloud, board links also inherit the current branch preview.

URL aliases & parameterized routes¶

aliases: is a root-level list of absolute URL paths that 302-redirect to this board's canonical file-path URL. Each entry must start with /; trailing slashes are normalized automatically.

aliases:
  - /old-reports/
  - /legacy/sales/

Rules:

An alias must not collide with a real board file path — the server raises an error at startup if it does.
Each alias must be unique across the project — two boards claiming the same alias is a startup error.

Parameterized aliases¶

An alias may contain a <name> capture segment. A request matching the pattern 302-redirects to the board's canonical URL with the captured segment appended as a query parameter of the same name — which the board then reads as a variable. This gives a single detail board a clean per-entity URL:

# faces/milestone.yml  (canonical URL: /milestone)
aliases:
  - /milestones/<name>
variables:
  name:
    input: select
    options:
      query: milestone_options
      column: slug

/milestones/m3-public-launch redirects to /milestone/?name=m3-public-launch, and milestone.yml renders with name bound to m3-public-launch.

A capture name matches exactly one non-empty path segment (no /). Use a capture name that matches the variable you want it to fill.
A real board file always wins over a pattern alias, so /milestones/ (a list board) and /milestones/<name> (the detail redirect) coexist without conflict.
Plain aliases (no <name>) redirect as before; only aliases with a capture are treated as patterns.

Aliasing a data or inspector route¶

The /data/... and /inspector/... paths are reserved for the built-in schema browser. An aliases: entry can still claim one of these paths — the alias redirect takes precedence over the generated system route, letting a board override what that URL serves.

# faces/warehouse_orders.yml
aliases:
  - /data/warehouse/public/orders

Auto-linking table rows¶

Set auto_link: true at the board root to have every table chart with no explicit link: automatically link each row to its canonical detail page — /data/<source>/<schema>/<table>/detail/:

auto_link: true

charts:
  orders_table:
    type: table
    query: orders

Default is off. Explicit link: on a chart or column always wins over auto_link; set link: ~ on a chart to suppress the auto-link for that one table without disabling auto_link board-wide.

List / detail convention¶

Teams can standardize recognizable path segments for common board roles:

…/list — filtered overview or table
…/detail — single-entity board (variables in query, e.g. ?id=)

This is a naming convention, not enforced by Dataface.