diff --git a/data-apps/external-connections.mdx b/data-apps/external-connections.mdx index ff4f7820..45ffbe42 100644 --- a/data-apps/external-connections.mdx +++ b/data-apps/external-connections.mdx @@ -9,6 +9,8 @@ A data app can also fetch from third-party HTTP APIs — for example, your own p External connections are managed under **Project Settings → Data app connections** on the project. +[Project chart types](/explore/chart-types/custom-project-charts#linking-external-connections) link connections the same way, so a chart type can call an API or show images from a URL field. + ## Configuring a connection A connection is scoped to a project and stores: @@ -18,9 +20,11 @@ A connection is scoped to a project and stores: - **Allowed methods** - which of `GET`, `POST`, `PUT`, `PATCH`, `DELETE` the app can use. New connections default to `GET` only; broaden the set only for APIs that actually need writes. - **Allowed paths** - optional path prefixes that further restrict where under the base URL the app can call. - **Auth** - see [Auth types](#auth-types) below. +- **Who can link it** - **Admins only**, or **Data app and chart type builders** so editors can attach the connection from the builder. +- **Public images** - the **Allow public images in linked apps** toggle lets linked apps and chart types load images straight from the origin, in `` tags or CSS. Off by default; enable it only for trusted public image or tile hosts. - **Instructions** - see [Usage instructions](#usage-instructions) below. -Configuring a connection (create, edit, delete) requires the admin-only `manage:ExternalConnection` scope. Viewing the list — so an app builder can pick a connection to link — is available to Interactive Viewer and above. +Configuring a connection (create, edit, delete) requires the admin-only `manage:ExternalConnection` scope. Viewing the list — so an app builder can pick a connection to link — is available to Interactive Viewer and above, and only shows connections set to **Data app and chart type builders**; admins see all of them. ## Auth types diff --git a/explore/chart-types/custom-project-charts.mdx b/explore/chart-types/custom-project-charts.mdx index bb6b85d6..4f837705 100644 --- a/explore/chart-types/custom-project-charts.mdx +++ b/explore/chart-types/custom-project-charts.mdx @@ -6,7 +6,7 @@ doc-type: reference icon: "shape" --- -Project chart types are reusable chart types you build for your project. You describe the chart you want, Lightdash builds it, and anyone in the project can then use it like a built-in chart type. Pick **Custom** in the chart type menu, then choose the chart type in the **Custom chart type** picker. +Project chart types are reusable chart types you build for your project. You describe the chart you want, Lightdash builds it, and anyone in the project can then use it like a built-in chart type. Open **Configure** in the Explorer, click **Change**, and pick it from the **Project** group of the chart type picker. For a one-off chart written directly as a Vega-Lite spec, see [Custom Vega charts](/explore/chart-types/custom-vega-charts). @@ -58,12 +58,64 @@ Name and describe the chart type in the header - that's what people see in the g /> -You can also start one from any chart, without leaving the Explorer: pick **Custom** as the chart type and choose **Create new chart type** in the picker. +You can also start one from any chart, without leaving the Explorer: open **Configure**, click **Change**, and choose **Create new chart type** in the **Project** group. The builder opens in the chart panel and previews against your query's real results. Chart types can also be developed on your machine and uploaded with the CLI. See [Chart types as code](#chart-types-as-code). +## Linking external connections + +Chart types render in the same sandbox as data apps, so they can only reach the network through [external connections](/data-apps/external-connections). That covers two cases: calling a third-party API while the chart renders, and showing images from a URL field in your results. Without a linked connection, the sandbox blocks images from any other origin. + +A project admin registers the connection once, then whoever builds the chart type links it from the builder. + + + + Go to **Project Settings → Data app connections** and click **Add connection**. Enter the **Base URL** of the host the chart type needs to reach and pick the auth method that host requires. A public image host needs **None**. + + + If the chart type shows images, turn on **Allow public images in linked apps**. Linked chart types can then load images straight from that origin, in `` tags or CSS. Leave it off for hosts you only call for data. + + + Set **Who can link this connection?** to **Data app and chart type builders** so editors can attach it from the builder. **Admins only** keeps it out of everyone else's picker. + + + Open the chart type in the builder, or start a new one, and click **Add external connections** in the prompt bar. Tick the connection, then describe the chart, or send a follow-up prompt such as "show the image from the Image URL input". The link is created when that build runs, so an existing chart type needs at least one follow-up prompt to pick it up. + + + The chart type builder open in the Explorer, with the Add external connections picker showing a linked image host and the chart rendering an icon per bar + The chart type builder open in the Explorer, with the Add external connections picker showing a linked image host and the chart rendering an icon per bar + + + + Click **Preview in explorer**, run a query that includes the image URL field, and map it to the chart type's input. The images should render. + + + The Explorer showing the chart type with its inputs mapped to the query's fields and an icon rendering next to each category + The Explorer showing the chart type with its inputs mapped to the query's fields and an icon rendering next to each category + + + + +Once linked, the connection stays with the chart type across versions and everywhere it renders: the builder preview, the Explorer, saved charts, dashboard tiles, and embedded dashboards. The indicator in the prompt bar counts linked connections. Open it and untick a connection to unlink it. Unlinking only removes the link, so the generated code keeps calling the connection until you build a new version. + ## Using a chart type in a chart @@ -71,7 +123,7 @@ You can also start one from any chart, without leaving the Explorer: pick **Cust Select the dimensions and metrics your chart needs and run the query. You have to run it before you can pick a custom chart type. - Open **Configure**, choose **Custom** in the chart type menu, then pick one from the **Project** group in the **Custom chart type** picker. Only chart types that finished building are listed. + Open **Configure**, click **Change**, then pick one from the **Project** group in the chart type picker. Only chart types that finished building are listed. Each of the chart type's inputs gets a field picker, the same as configuring axes on a bar or line chart. Required inputs can't be cleared. diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-dark.png new file mode 100644 index 00000000..4c9d0321 Binary files /dev/null and b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-explorer-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-explorer-dark.png new file mode 100644 index 00000000..01896c42 Binary files /dev/null and b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-explorer-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-explorer-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-explorer-light.png new file mode 100644 index 00000000..27b91e9d Binary files /dev/null and b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-explorer-light.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-light.png new file mode 100644 index 00000000..3c225d41 Binary files /dev/null and b/images/explore/chart-types/custom-project-charts/custom-chart-types-connections-light.png differ