diff --git a/app/docs/chart-preview-via-api.mdx b/app/docs/chart-preview-via-api.mdx new file mode 100644 index 0000000000..83b4694124 --- /dev/null +++ b/app/docs/chart-preview-via-api.mdx @@ -0,0 +1,160 @@ + + +While usually you'll want to publish your chart, sometimes you might want to simply preview it, without going through the publishing process. +This could be especially helpful to programatically generate charts based on many different configuration options. +Visualize offers a way to preview charts without publishing them, by using a custom API. + +## iframe + +**Demo**: Visit `/_preview` to see a page with an iframe containing a chart preview. + +This method works by pointing an iframe to the `/preview` page, and posting a message with the chart state to the iframe window on load. + + { + const iframeWindow = iframe?.contentWindow; + if (iframeWindow) { + iframeWindow.postMessage(chartState, "*"); + } +}; +`} +/> + +## POST request + +**Demo**: Visit `/_preview_post` to see a page with two buttons that open a new page with a chart preview after clicking. + +This method works by sending a POST request to `/preview_post` page with chart state when clicking on a form button. +The `/preview_post` page retrieves the content of a request in `getServerSideProps` and renders a preview of a chart. + +It's important to only use one input inside a form (as we split the string by `=`). + + + + +`} +/> + +### Chart config schema + +As the application constantly evolves, the chart config schema might change. +You can find the latest version of the schema in the [config-types.ts](https://github.com/visualize-admin/visualization-tool/blob/main/app/config-types.ts) file. + +An example chart config is shown below. + + + +Note that it's encouraged to visit the Visualize application with &flag_debug==true added to the URL to enable +the debug mode, which will show the chart config directly below the chart that is being edited. It also enables +the "Dump to console" button, which will log the chart config to the browser console, for easier re-use. diff --git a/app/pages/docs/index.tsx b/app/pages/docs/index.tsx index 5f4096d6f5..e93bf781a7 100644 --- a/app/pages/docs/index.tsx +++ b/app/pages/docs/index.tsx @@ -91,6 +91,11 @@ const pages: ConfigPageOrGroup[] = [ title: "RDF to visualize", content: require("@/docs/rdf-to-visualize.mdx"), }, + { + path: "/charts/preview-via-api", + title: "Preview via API", + content: require("@/docs/chart-preview-via-api.mdx"), + }, { path: "/charts/annotations", title: "Annotations",