diff --git a/docs-mintlify/docs/data-modeling/dimensions.mdx b/docs-mintlify/docs/data-modeling/dimensions.mdx index 08e3d1ec1f613..d80572764287d 100644 --- a/docs-mintlify/docs/data-modeling/dimensions.mdx +++ b/docs-mintlify/docs/data-modeling/dimensions.mdx @@ -379,6 +379,150 @@ See the following recipes: +## Links + +Dimensions can declare **links** — clickable navigation targets that supporting +tools (such as [Cube Cloud Workbooks][ref-workbooks]) surface next to the +dimension's values. + +`links` is a **list**, so a single dimension can declare **any number of +links** — they all appear together in the cell menu. Each link points either to +an **external URL** (`url`) or to **another Cube Cloud dashboard** (`dashboard`, +a drill-in), and its URL is built per row from the dimension's data. The example +below declares two links on one dimension (an external search and a drill-in). + + + +Dimension `links` require Cube **v1.6.53** or newer. + + + +### Parameters + +`links` is a list of link objects. Each link accepts: + +| Parameter | Required? | Description | +| --- | --- | --- | +| `name` | **Required** | Identifier, unique within the dimension. Also used in the synthetic dimension name (see [Behavior](#behavior)). | +| `label` | **Required** | The text shown for the link in the UI. | +| `url` | **Either `url` or `dashboard`** | SQL expression that builds an **external** URL per row. May [reference][ref-references] columns and other dimensions. | +| `dashboard` | **Either `url` or `dashboard`** | The target Cube Cloud dashboard's **slug** (a **drill-in**). Each link sets exactly one of `url` or `dashboard` — never both — but different links on the same dimension can mix the two. | +| `icon` | Optional | A [Tabler icon][link-tabler] name (see [Icons](#icons)). Defaults to a generic link icon. | +| `target` | Optional | Where to open the link: `blank` (default — new tab) or `self` (same tab). Applies to **external** links only — drill-ins always navigate in-app (see [Behavior](#behavior)). | +| `params` | Optional | Extra per-row parameters. For `url:` they are appended as query parameters. For `dashboard:` they become **equality filters** on the target dashboard — each `key` is a member of the target dashboard's view (a cube path such as `orders.status` is auto-resolved to the matching view member), and `value` is the per-row value. | + +### Example + + + +```yaml title="YAML" +cubes: + - name: orders + sql_table: orders + + dimensions: + - name: status + sql: status + type: string + links: + # External link — opens a URL built from the row's value + - name: search + label: Search the web + url: "CONCAT('https://www.google.com/search?q=order+', {CUBE}.status)" + icon: brand-google + target: blank + + # Drill-in link — opens another Cube Cloud dashboard, filtered by the row + - name: details + label: Open order details + dashboard: orders-detail # the target dashboard's slug + params: + - key: orders_view.status + value: "{CUBE}.status" +``` + +```javascript title="JavaScript" +cube(`orders`, { + sql_table: `orders`, + + dimensions: { + status: { + sql: `status`, + type: `string`, + links: [ + { + name: `search`, + label: `Search the web`, + url: `CONCAT('https://www.google.com/search?q=order+', ${CUBE}.status)`, + icon: `brand-google`, + target: `blank` + }, + { + name: `details`, + label: `Open order details`, + dashboard: `orders-detail`, + params: [{ key: `orders_view.status`, value: `${CUBE}.status` }] + } + ] + } + } +}) +``` + + + +### Icons + +`icon` accepts any name from the [Tabler icon set][link-tabler] — the +kebab-case name **without** any prefix, for example `brand-google`, +`external-link`, `layout-dashboard`, or `send`. Browse and search the available +names at [tabler.io/icons][link-tabler]. If `icon` is omitted, a default link +icon is shown. + +### Setting a dashboard slug + +A `dashboard:` link targets another dashboard by its **slug** — a short, stable, +human-readable identifier (e.g. `orders-detail`). The slug is **portable across +environments**: it is resolved within the current deployment, so the same model +works in development and production without hardcoding dashboard IDs. + +To set a slug in Cube Cloud, open the target dashboard, open its **options +sidebar**, and fill the **Slug** field (see +[Dashboards → Dashboard slug](/docs/explore-analyze/dashboards#dashboard-slug)). +Slugs are **unique per deployment**, and the `dashboard:` value in your link must +match the slug exactly. + +**There is no required order.** You can write the `dashboard:` slug in the model +first (it won't break anything — a link whose slug doesn't yet resolve is simply +skipped in the cell menu) and set the dashboard's slug later, or set the +dashboard slug first and reference it from the model afterwards. The link starts +working as soon as both sides use the same slug. + +### Behavior + +- **Per-row resolution** — each link's `url` (and its `params`) is evaluated for + every row, so the destination reflects the clicked cell. Internally a link + compiles to a hidden **synthetic dimension** named + `___link__url` holding the resolved URL; it is added to the + query automatically and is never shown as a column. +- **Null values** — if the source value (and thus the resolved URL) is null for + a row, that link is omitted from the menu for that row. +- **Where links appear** — in Cube Cloud, links surface in the table + [**cell menu**](/docs/explore-analyze/charts/chart-types/table#cell-menu) on + every results table (dashboard and workbook table charts, embedded dashboards, + and Explore / SQL results). A left-click on a cell opens the menu listing the + dimension's links, alongside **Copy value** and, on measures, **Drill down**. +- **Drill-in vs external** — a `dashboard:` link navigates **in-app, in the same + tab** (Cmd/Ctrl-click opens a new tab), ignoring `target`; a `url:` link opens + per its `target` (`blank` by default). +- **Filters** — for `dashboard:` links, each `params` entry becomes an + **equality filter** on the target (the `key` is a view member, the `value` is + the per-row value). An unknown or inaccessible target slug is skipped + gracefully — the user is notified and no navigation happens. + +See the [`links` reference][ref-dimensions-ref] for the canonical parameter +list. + ## Hierarchies Dimensions can be organized into [hierarchies][ref-hierarchies] to define @@ -418,6 +562,9 @@ cubes: and non-standard time periods [ref-dimensions-ref]: /reference/data-modeling/dimensions +[ref-workbooks]: /docs/explore-analyze/workbooks +[ref-references]: /docs/data-modeling/syntax#references +[link-tabler]: https://tabler.io/icons [ref-measures-page]: /docs/data-modeling/measures [ref-joins]: /docs/data-modeling/joins [ref-type]: /reference/data-modeling/dimensions#type diff --git a/docs-mintlify/docs/explore-analyze/charts/chart-types/table.mdx b/docs-mintlify/docs/explore-analyze/charts/chart-types/table.mdx index fc4e465e52d58..9b6b4ef99453b 100644 --- a/docs-mintlify/docs/explore-analyze/charts/chart-types/table.mdx +++ b/docs-mintlify/docs/explore-analyze/charts/chart-types/table.mdx @@ -1,9 +1,9 @@ --- title: Table -description: Display query results as a configurable table with pivots, conditional formatting, and inline visualizations. +description: Display query results as a configurable table with pivots, conditional formatting, and custom styling. --- -The table visualization presents query results in a structured grid. Unlike the raw results table in the query panel, the table visualization is designed for sharing — it supports pivots, column display overrides, conditional formatting, custom styling, and inline bar/link/image column rendering. +The table visualization presents query results in a structured grid. Unlike the raw results table in the query panel, the table visualization is designed for sharing — it supports pivots, conditional formatting, custom styling, and a per-cell menu for links, copy, and drill-down. {/* TODO screenshot: styled table with pivot and conditional formatting (hidden — replace this comment with when image is ready) */} @@ -49,30 +49,7 @@ Click the dropdown arrow on any field in the **Fields** section to configure it: | **Word wrap** | Allow cell content to wrap to multiple lines | | **Hide** | Show or hide the column | -## Display tab — showing columns as links, images, or bars - -By default, columns display their raw value. The **Display** tab for each field lets you change this: - -### Links - -Display a field's value as a clickable hyperlink. To create dynamic per-row links: - -1. Add a [calculated field](/docs/explore-analyze/workbooks/calculated-fields) that produces a URL — for example: - ``` - CONCAT("https://example.com/orders/", order_items.order_id) - ``` -2. In the table visualization, hide the calculated field column. -3. In the **Display** tab for the field you want to link, set **Display as** to **Link** and select the hidden URL field as the source. - -{/* TODO screenshot: column display dropdown showing Link option selected (hidden — replace this comment with when image is ready) */} - -### Images - -Display a field as an image by setting **Display as** to **Image**. Configure height and width. To make the image a link, check **Link image** and set the **Link URL**. - -The URL must be publicly accessible without authentication. - -### Inline bars +## Inline bars Display a numeric column as a proportional in-cell bar. In the column's per-column section on the **Style** tab, use the **Display as** control to add a bar. Each bar's length reflects the value's magnitude within the column's range. @@ -88,6 +65,37 @@ When a column contains both positive and negative values, bars are drawn in both {/* TODO screenshot: table with inline bar column (hidden — replace this comment with when image is ready) */} +## Cell menu + +A **left-click on any table cell** selects it and opens a context menu (links, +copy, drill-down). The menu +is consistent everywhere a results table appears — dashboard and workbook table +charts, embedded dashboards, and the Explore / SQL-runner results grid. It lists, +top to bottom: + +- **Data-model links** — drill into another dashboard or open an external URL. + These come from [`links` defined on the dimension](/docs/data-modeling/dimensions#links) + in the data model (not configured per-table). A **drill-in** link + (`dashboard:`) navigates in-app to the target dashboard, filtered by the + clicked row; an **external** link (`url:`) opens its URL. Each link shows its + configured icon (or a default link icon). +- **Copy value** — copies the cell's value to the clipboard. +- **Drill down** — on a measure cell with drill members, opens the drill-down + modal for that value. (Shown where the surface supports drill-through, e.g. + dashboard and workbook tables; not in Explore results.) + +Other gestures: + +- **Cmd/Ctrl-click a link** opens its target in a **new tab** (drill-ins + otherwise stay in the same tab). +- **Shift-click a cell** selects it without opening the menu, so `Cmd`/`Ctrl`+`C` + copies the value. +- **Right-click** opens your **browser's native menu** (not the cell menu). + +Links are declared once on the dimension in the data model, not configured +per-table — see [Dimensions → Links](/docs/data-modeling/dimensions#links) to +define them. + ## Style options The **Style** tab controls the visual appearance of the table: diff --git a/docs-mintlify/docs/explore-analyze/dashboards/index.mdx b/docs-mintlify/docs/explore-analyze/dashboards/index.mdx index ca6287f47528b..76bee74299f63 100644 --- a/docs-mintlify/docs/explore-analyze/dashboards/index.mdx +++ b/docs-mintlify/docs/explore-analyze/dashboards/index.mdx @@ -18,6 +18,30 @@ Dashboards enable you to: In the dashboard builder inside your [workbook][ref-workbooks], select the reports you want to include and arrange them on the canvas alongside other [widgets][ref-widgets] to tell your data story, then publish the dashboard. This gives stakeholders direct access to the insights that matter most, without the complexity of the underlying analysis. +## Dashboard slug + +A dashboard can have a **slug** — a short, stable, human-readable identifier +(e.g. `orders-detail`) used to link to it from the data model. Data-model +[dimension links][ref-dimension-links] with a `dashboard:` value reference a +dashboard by its slug to drill into it. + +To set it, open the dashboard in the builder, open the **options sidebar**, and +fill the **Slug** field. Slugs are **unique per deployment** and are resolved +within the current deployment, so the same model works across environments. The +dashboard's own URL is unaffected (it stays `publicId`-based). + + + +**There is no required order between the model and the dashboard.** You can +reference a slug from a `dashboard:` link in the data model before any dashboard +uses it, or set a dashboard's slug before any link references it — neither +breaks. A link whose slug doesn't (yet) resolve is simply skipped in the cell +menu, and starts working as soon as a dashboard in the deployment claims that +slug. (If you later clear or change a slug that links still reference, the +options sidebar warns you to update those links.) + + + ## Download as PNG or PDF Open a published dashboard, click the **More actions** (`⋯`) button in the @@ -37,5 +61,6 @@ refresh][ref-scheduled-refreshes]. [ref-workbooks]: /docs/explore-analyze/workbooks [ref-widgets]: /docs/explore-analyze/dashboards/widgets +[ref-dimension-links]: /docs/data-modeling/dimensions#links [ref-notifications]: /docs/explore-analyze/notifications [ref-scheduled-refreshes]: /docs/explore-analyze/scheduled-refreshes diff --git a/docs-mintlify/reference/data-modeling/dimensions.mdx b/docs-mintlify/reference/data-modeling/dimensions.mdx index 0cf4d9f40f4b1..6d18691e1bc61 100644 --- a/docs-mintlify/reference/data-modeling/dimensions.mdx +++ b/docs-mintlify/reference/data-modeling/dimensions.mdx @@ -428,8 +428,9 @@ Using it with other dimension types will result in a validation error. ### `links` -The `links` parameter allows you to define links associated with a dimension. -They can be rendered as HTML links by supporting tools, e.g., [Workbooks][ref-workbooks]. +The `links` parameter allows you to define **one or more** links associated with a +dimension (it is a list). They can be rendered as HTML links by supporting tools, e.g., +[Workbooks][ref-workbooks]. Links are useful to let users navigate to related external resources (e.g., Google search), internal tools (e.g., Salesforce), or other pages in a BI tool. @@ -440,11 +441,17 @@ in the [synthetic dimension](#synthetic) name. A link must specify either a `url` or a `dashboard`: - `url` is a SQL expression that constructs the link URL. It can [reference][ref-references] column and dimension values, just like the [`sql` parameter](#sql) or [`mask` parameter](#mask). -- `dashboard` is a dashboard identifier. When set, the link URL is generated as - `/dashboard/`. The `params` object is still appended as a query string. +- `dashboard` is a target dashboard reference. When set, the link URL is generated as + `/dashboard/` and `params` are appended as a query string. In Cube Cloud + this is the target dashboard's **slug** (set in the dashboard's options and resolved + within the current deployment); choosing the link drills in-app to that dashboard with + `params` applied as equality filters. Links surface in the table **cell context menu**. Optionally, a link might use the `icon` parameter to reference an icon from a [supported -icon set][link-tabler] to be displayed alongside the link label. +icon set][link-tabler] to be displayed alongside the link label. Use the icon's kebab-case +name without any prefix (e.g. `brand-google`, `external-link`, `layout-dashboard`, `send`); +browse the available names at [tabler.io/icons][link-tabler]. When omitted, a default link +icon is shown. Optionally, a link might use the `target` parameter to specify [where to open it][link-target]: `blank` (default) to open in a new tab/window or `self` to open in the same tab/window.