Package: datasette-dashboards
datasette-dashboardsDatasette plugin providing data dashboards from metadataTry out a live demo athttps://datasette-dashboards-demo.vercel.appWARNING: this plugin is still experimental and not ready for production.
Some breaking changes might happen between releases before reaching a stable version.
Use it at your own risks!InstallationInstall this plugin in the same environment as Datasette:$datasetteinstalldatasette-dashboardsUsageDefine dashboards withinmetadata.yml/metadata.json:plugins:datasette-dashboards:my-dashboard:title:My Dashboarddescription:Showing some nice metricslayout:-[analysis-note,events-count]-[analysis-note,events-source]filters:date_start:name:Date Starttype:datedefault:"2021-01-01"date_end:name:Date Endtype:datecategory:name:My Categorytype:selectoptions:[Option 1,Option 2,Option 3]dynamic_category:name:My Dynamic Categorytype:selectdb:jobsquery:SELECT region FROM jobs ORDER BY region ASCcharts:analysis-note:library:markdowndisplay:|-# Analysis notes> A quick rundown of events statistics and KPIsevents-count:title:Total number of eventsdb:jobsquery:SELECT count(*) as count FROM eventslibrary:metricdisplay:field:countprefix:suffix:events-source:title:Number of events by sourcedb:jobsquery:SELECT source, count(*) as count FROM events WHERE TRUE [[ AND date >= date(:date_start) ]] [[ AND date <= date(:date_end) ]] GROUP BY source ORDER BY count DESClibrary:vega-litedisplay:mark:{type:arc,tooltip:true}encoding:color:{field:source,type:nominal}theta:{field:count,type:quantitative}A new menu entry is now available, pointing at/-/dashboardsto access all defined dashboards.PropertiesDashboard properties:PropertyTypeDescriptiontitlestringDashboard titledescriptionstringDashboard descriptionsettingsobjectDashboard settingslayoutarrayDashboard layoutfiltersobjectDashboard filtersDashboard settings:PropertyTypeDescriptionallow_fullscreenboolAllow dashboard to be toggled in fullscreen  (defaultfalse)autorefreshnumberAuto-refresh timeout in minutesDashboard filters:PropertyTypeDescriptionnamestringFilter display nametypestringFilter type (text,date,number,select)defaultstring,number(optional) Filter default valueminnumber(optional) Filter minimum valuemaxnumber(optional) Filter maximum valuestepnumber(optional) Filter stepping valueoptionslist(optional) Select filter options listdbstring(optional) Dynamic select filter databasequerystring(optional) Dynamic select filter queryCommon chart properties for all chart types:PropertyTypeDescriptiontitlestringChart titledbstringDatabase name against which to run the queryquerystringSQL query to run and extract data fromlibrarystringOne of supported libraries:vega,vega-lite,markdown,metric,table,mapdisplayobjectChart display specification (depend on the used library)To define SQL queries using dashboard filters:SELECT*FROMmytable[[WHEREcol>=:my_filter]]SELECT*FROMmytableWHERETRUE[[ANDcol1=:my_filter_1]][[ANDcol2=:my_filter_2]]Important notes:When aselectfilter has more than 100 options, the dropdown list will be automatically converted to a text filter with autocompletionVega propertiesAvailable configuration forvegacharts:PropertyTypeDescriptionlibrarystringMust be set tovegadisplayobjectVega specification objectNotes about thedisplayproperty:Requires a validVega specification objectSome fields are pre-defined:$schema,description,autosize,data,signalsAll fields are passed along as-is (overriding pre-defined fields if any)Onlymarkandencodingfields are required as the bare-minimumVega-Lite propertiesAvailable configuration forvega-litecharts:PropertyTypeDescriptionlibrarystringMust be set tovega-litedisplayobjectVega specification objectNotes about thedisplayproperty:Requires a validVega-Lite specification objectSome fields are pre-defined:$schema,description,width,view,config,dataAll fields are passed along as-is (overriding pre-defined fields if any)Onlymarkandencodingfields are required as the bare-minimumMarkdown propertiesAvailable configuration formarkdownchart:PropertyTypeDescriptionlibrarystringMust be set tomarkdowndisplaystringMulti-line string containing the Markdown contentNote :Some common properties do not apply and can be omitted:title,db,queryMarkdown rendering is done bydatasette-render-markdownTo configure Markdown rendering, extensions can be enabled inmetadataMetric propertiesAvailable configuration formetricchart:PropertyTypeDescriptionlibrarystringMust be set tometricdisplay.fieldstringNumerical field to be displayed as metricdisplay.prefixstringPrefix to be displayed before metricdisplay.suffixstringPrefix to be displayed after metricNote:Thedisplay.fieldmust reference a single-numerical value from the SQL query
(e.g. numericalnumberfield inSELECT count(*) as number FROM events)Table propertiesThere is no required configured indisplay, so you can either ignored or
leave it empty for table charts.Some advice for a nice table chart:Set proper column names in theSELECTclauseLimit the number of columns in theSELECTclauseLimit the number of rows with theLIMITclauseOrder the rows explicitely with theORDER BYclauseUse SQLite string concatenation operator (||) to format column data (for instance to include HTML markup!)Map propertiesAvailable configuration formapchart:PropertyTypeDescriptionlibrarystringMust be set tomapdisplay.latitude_columnstringName of the latitude column (default:latitude)display.longitude_columnstringName of the latitude column (default:longitude)display.show_latlng_popupbooleanWhether or not to display latitude and longitude values in popup (default:false)Warning: do not try to load more than a thousand rows for a map at the risk of
slugginess and being unreadable. Make sensible use of theLIMITclause to reduce
the number of items to display on the map.Dashboard layoutThe default dashboard layout will present two charts per row (one per row on mobile).
To make use of custom dashboard layout usingCSS Grid Layout,
define thelayoutarray property as a grid / matrix:Each entry represents a row of chartsEach column is referring a chart by its property nameAn empty slot in the grid can be specified using the.(full stop) placeholderWARNINGS:All rows must specify the same number of columnsAll charts must be placed somewhere on the custom layoutHere is a simple 2x3 grid example with 4 different charts:layout:-[chart1,chart2,chart3]-[chart1,chart4,chart4]Here is a more subtle example involving an empty spot at the end of the second row:layout:-[chart1,chart2,chart3]-[chart1,chart4,.]Embedding dashboards and chartsDashboards can be embedded within an HTML page using aniframeelement:<iframesrc="/-/dashboards/my-dashboard/embed?start_date=2023-01-01&end_date=2023-12-31"frameborder="0"width="100%"height="600"allowtransparency></iframe>Same goes for charts:<iframesrc="/-/dashboards/my-dashboard/my-chart/embed?start_date=2023-01-01&end_date=2023-12-31"frameborder="0"width="100%"height="600"allowtransparency></iframe>DevelopmentTo set up this plugin locally, first checkout the code.
Then create a new virtual environment and the required dependencies:poetryinstall
poetryshellTo run the QA suite:black--checkdatasette_dashboardstests
flake8datasette_dashboardstests
mypydatasette_dashboardstests
pytest-v--cov=datasette_dashboards--cov=tests--cov-branch--cov-report=term-missingtestsDemoWith the developmnent environment setup, you can run the demo locally:datasette\--metadatademo/metadata.yml\--template-dirdemo/templates\demo/jobs.dbLicenseLicensed under Apache License, Version 2.0Copyright (c) 2021 - present Romain Clement