{"id":13585861,"url":"https://github.com/rclement/datasette-dashboards","last_synced_at":"2025-04-06T15:13:37.399Z","repository":{"id":38216506,"uuid":"361014273","full_name":"rclement/datasette-dashboards","owner":"rclement","description":"Datasette plugin providing data dashboards from metadata","archived":false,"fork":false,"pushed_at":"2024-05-19T22:51:22.000Z","size":5995,"stargazers_count":132,"open_issues_count":17,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-20T18:57:15.855Z","etag":null,"topics":["dashboards","data-visualization","datasette","datasette-io","datasette-plugin","sql","vega-lite"],"latest_commit_sha":null,"homepage":"https://datasette-dashboards-demo.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rclement.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-23T21:56:48.000Z","updated_at":"2024-06-04T19:07:43.439Z","dependencies_parsed_at":"2023-12-09T14:29:25.862Z","dependency_job_id":"1f4b032b-320c-4cc0-91e5-75b23d80f1ab","html_url":"https://github.com/rclement/datasette-dashboards","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclement%2Fdatasette-dashboards","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclement%2Fdatasette-dashboards/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclement%2Fdatasette-dashboards/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclement%2Fdatasette-dashboards/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rclement","download_url":"https://codeload.github.com/rclement/datasette-dashboards/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247500469,"owners_count":20948880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dashboards","data-visualization","datasette","datasette-io","datasette-plugin","sql","vega-lite"],"created_at":"2024-08-01T15:05:11.375Z","updated_at":"2025-04-06T15:13:37.371Z","avatar_url":"https://github.com/rclement.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# datasette-dashboards\n\n\u003e Datasette plugin providing data dashboards from metadata\n\n[![PyPI](https://img.shields.io/pypi/v/datasette-dashboards.svg)](https://pypi.org/project/datasette-dashboards/)\n[![CI/CD](https://github.com/rclement/datasette-dashboards/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/rclement/datasette-dashboards/actions/workflows/ci-cd.yml)\n[![Coverage Status](https://img.shields.io/codecov/c/github/rclement/datasette-dashboards)](https://codecov.io/gh/rclement/datasette-dashboards)\n[![License](https://img.shields.io/github/license/rclement/datasette-dashboards)](https://github.com/rclement/datasette-dashboards/blob/master/LICENSE)\n\nTry out a live demo at [https://datasette-dashboards-demo.vercel.app](https://datasette-dashboards-demo.vercel.app/-/dashboards)\n\n**WARNING**: this plugin is still experimental and not ready for production.\nSome breaking changes might happen between releases before reaching a stable version.\nUse it at your own risks!\n\n![Datasette Dashboards Demo](https://raw.githubusercontent.com/rclement/datasette-dashboards/master/demo/datasette-dashboards-demo.png)\n\n## Installation\n\nInstall this plugin in the same environment as Datasette:\n\n```bash\n$ datasette install datasette-dashboards\n```\n\n## Usage\n\nDefine dashboards within `metadata.yml` / `metadata.json`:\n\n```yaml\nplugins:\n  datasette-dashboards:\n    my-dashboard:\n      title: My Dashboard\n      description: Showing some nice metrics\n      layout:\n        - [analysis-note, events-count]\n        - [analysis-note, events-source]\n      filters:\n        date_start:\n          name: Date Start\n          type: date\n          default: \"2021-01-01\"\n        date_end:\n          name: Date End\n          type: date\n        category:\n          name: My Category\n          type: select\n          options: [Option 1, Option 2, Option 3]\n        dynamic_category:\n          name: My Dynamic Category\n          type: select\n          db: jobs\n          query: SELECT region FROM jobs ORDER BY region ASC\n      charts:\n        analysis-note:\n          library: markdown\n          display: |-\n            # Analysis notes\n            \u003e A quick rundown of events statistics and KPIs\n\n        events-count:\n          title: Total number of events\n          db: jobs\n          query: SELECT count(*) as count FROM events\n          library: metric\n          display:\n            field: count\n            prefix:\n            suffix:\n\n        events-source:\n          title: Number of events by source\n          db: jobs\n          query: SELECT source, count(*) as count FROM events WHERE TRUE [[ AND date \u003e= date(:date_start) ]] [[ AND date \u003c= date(:date_end) ]] GROUP BY source ORDER BY count DESC\n          library: vega-lite\n          display:\n            mark: { type: arc, tooltip: true }\n            encoding:\n              color: { field: source, type: nominal }\n              theta: { field: count, type: quantitative }\n```\n\nA new menu entry is now available, pointing at `/-/dashboards` to access all defined dashboards.\n\n### Properties\n\nDashboard properties:\n\n| Property      | Type     | Description           |\n| ------------- | -------- | --------------------- |\n| `title`       | `string` | Dashboard title       |\n| `description` | `string` | Dashboard description |\n| `settings`    | `object` | Dashboard settings    |\n| `layout`      | `array`  | Dashboard layout      |\n| `filters`     | `object` | Dashboard filters     |\n\nDashboard settings:\n\n| Property           | Type     | Description                                                    |\n| ------------------ | -------- | -------------------------------------------------------------- |\n| `allow_fullscreen` | `bool`   | Allow dashboard to be toggled in fullscreen  (default `false`) |\n| `autorefresh`      | `number` | Auto-refresh timeout in minutes                                |\n\nDashboard filters:\n\n| Property  | Type               | Description                                      |\n| --------- | ------------------ | ------------------------------------------------ |\n| `name`    | `string`           | Filter display name                              |\n| `type`    | `string`           | Filter type (`text`, `date`, `number`, `select`) |\n| `default` | `string`, `number` | (optional) Filter default value                  |\n| `min`     | `number`           | (optional) Filter minimum value                  |\n| `max`     | `number`           | (optional) Filter maximum value                  |\n| `step`    | `number`           | (optional) Filter stepping value                 |\n| `options` | `list`             | (optional) Select filter options list            |\n| `db`      | `string`           | (optional) Dynamic select filter database        |\n| `query`   | `string`           | (optional) Dynamic select filter query           |\n\nCommon chart properties for all chart types:\n\n| Property  | Type     | Description                                                                           |\n| --------- | -------- | ------------------------------------------------------------------------------------- |\n| `title`   | `string` | Chart title                                                                           |\n| `db`      | `string` | Database name against which to run the query                                          |\n| `query`   | `string` | SQL query to run and extract data from                                                |\n| `library` | `string` | One of supported libraries: `vega`, `vega-lite`, `markdown`, `metric`, `table`, `map` |\n| `display` | `object` | Chart display specification (depend on the used library)                              |\n\nTo define SQL queries using dashboard filters:\n\n```sql\nSELECT * FROM mytable [[ WHERE col \u003e= :my_filter ]]\n```\n\n```sql\nSELECT * FROM mytable WHERE TRUE [[ AND col1 = :my_filter_1 ]] [[ AND col2 = :my_filter_2 ]]\n```\n\n**Important notes:**\n\n- When a `select` filter has more than 100 options, the dropdown list will be automatically converted to a text filter with autocompletion\n\n#### Vega properties\n\nAvailable configuration for `vega` charts:\n\n| Property  | Type     | Description               |\n| --------- | -------- | ------------------------- |\n| `library` | `string` | Must be set to `vega`     |\n| `display` | `object` | Vega specification object |\n\nNotes about the `display` property:\n\n- Requires a valid [Vega specification object](https://vega.github.io/vega/docs/)\n- Some fields are pre-defined: `$schema`, `description`, `autosize`, `data`, `signals`\n- All fields are passed along as-is (overriding pre-defined fields if any)\n- Only `mark` and `encoding` fields are required as the bare-minimum\n\n#### Vega-Lite properties\n\nAvailable configuration for `vega-lite` charts:\n\n| Property  | Type     | Description                |\n| --------- | -------- | -------------------------- |\n| `library` | `string` | Must be set to `vega-lite` |\n| `display` | `object` | Vega specification object  |\n\nNotes about the `display` property:\n\n- Requires a valid [Vega-Lite specification object](https://vega.github.io/vega-lite/docs/)\n- Some fields are pre-defined: `$schema`, `description`, `width`, `view`, `config`, `data`\n- All fields are passed along as-is (overriding pre-defined fields if any)\n- Only `mark` and `encoding` fields are required as the bare-minimum\n\n#### Markdown properties\n\nAvailable configuration for `markdown` chart:\n\n| Property  | Type     | Description                                       |\n| --------- | -------- | ------------------------------------------------- |\n| `library` | `string` | Must be set to `markdown`                         |\n| `display` | `string` | Multi-line string containing the Markdown content |\n\nNote :\n\n- Some common properties do not apply and can be omitted: `title`, `db`, `query`\n- Markdown rendering is done by [`datasette-render-markdown`](https://datasette.io/plugins/datasette-render-markdown)\n- To configure Markdown rendering, extensions can be enabled in [metadata](https://datasette.io/plugins/datasette-render-markdown#user-content-markdown-extensions)\n\n#### Metric properties\n\nAvailable configuration for `metric` chart:\n\n| Property         | Type     | Description                               |\n| ---------------- | -------- | ----------------------------------------- |\n| `library`        | `string` | Must be set to `metric`                   |\n| `display.field`  | `string` | Numerical field to be displayed as metric |\n| `display.prefix` | `string` | Prefix to be displayed before metric      |\n| `display.suffix` | `string` | Prefix to be displayed after metric       |\n\nNote:\n\n- The `display.field` must reference a single-numerical value from the SQL query\n  (e.g. numerical `number` field in `SELECT count(*) as number FROM events`)\n\n#### Table properties\n\nThere is no required configured in `display`, so you can either ignored or\nleave it empty for table charts.\n\nSome advice for a nice table chart:\n\n- Set proper column names in the `SELECT` clause\n- Limit the number of columns in the `SELECT` clause\n- Limit the number of rows with the `LIMIT` clause\n- Order the rows explicitely with the `ORDER BY` clause\n- Use SQLite string concatenation operator (`||`) to format column data (for instance to include HTML markup!)\n\n#### Map properties\n\nAvailable configuration for `map` chart:\n\n| Property                    | Type      | Description                                                                         |\n| --------------------------- | --------- | ----------------------------------------------------------------------------------- |\n| `library`                   | `string`  | Must be set to `map`                                                                |\n| `display.latitude_column`   | `string`  | Name of the latitude column (default: `latitude`)                                   |\n| `display.longitude_column`  | `string`  | Name of the latitude column (default: `longitude`)                                  |\n| `display.show_latlng_popup` | `boolean` | Whether or not to display latitude and longitude values in popup (default: `false`) |\n\n**Warning**: do not try to load more than a thousand rows for a map at the risk of\nslugginess and being unreadable. Make sensible use of the `LIMIT` clause to reduce\nthe number of items to display on the map.\n\n### Dashboard layout\n\nThe default dashboard layout will present two charts per row (one per row on mobile).\nTo make use of custom dashboard layout using [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout),\ndefine the `layout` array property as a grid / matrix:\n\n- Each entry represents a row of charts\n- Each column is referring a chart by its property name\n- An empty slot in the grid can be specified using the `.` (_full stop_) placeholder\n\n**WARNINGS**:\n- All rows must specify the same number of columns\n- All charts must be placed somewhere on the custom layout\n\nHere is a simple 2x3 grid example with 4 different charts:\n\n```yaml\nlayout:\n  - [chart1, chart2, chart3]\n  - [chart1, chart4, chart4]\n```\n\nHere is a more subtle example involving an empty spot at the end of the second row:\n\n```yaml\nlayout:\n  - [chart1, chart2, chart3]\n  - [chart1, chart4, .]\n```\n\n### Embedding dashboards and charts\n\nDashboards can be embedded within an HTML page using an `iframe` element:\n\n```html\n\u003ciframe\n  src=\"/-/dashboards/my-dashboard/embed?start_date=2023-01-01\u0026end_date=2023-12-31\"\n  frameborder=\"0\"\n  width=\"100%\"\n  height=\"600\"\n  allowtransparency\n\u003e\n\u003c/iframe\u003e\n```\n\nSame goes for charts:\n\n```html\n\u003ciframe\n  src=\"/-/dashboards/my-dashboard/my-chart/embed?start_date=2023-01-01\u0026end_date=2023-12-31\"\n  frameborder=\"0\"\n  width=\"100%\"\n  height=\"600\"\n  allowtransparency\n\u003e\n\u003c/iframe\u003e\n```\n\n## Development\n\nTo set up this plugin locally, first checkout the code.\nThen create a new virtual environment and the required dependencies:\n\n```bash\npoetry install\npoetry shell\n```\n\nTo run the QA suite:\n\n```bash\nblack --check datasette_dashboards tests\nflake8 datasette_dashboards tests\nmypy datasette_dashboards tests\npytest -v --cov=datasette_dashboards --cov=tests --cov-branch --cov-report=term-missing tests\n```\n\n## Updating JS dependencies\n\nExternal JS dependencies are tracked and bundled using NPM and `package.json` (`package-lock.json` is not needed here):\n\n```bash\nnpm install --no-package-lock\n```\n\n## Demo\n\nWith the developmnent environment setup, you can run the demo locally:\n\n```bash\ndatasette \\\n  --metadata demo/metadata.yml \\\n  --template-dir demo/templates \\\n  demo/jobs.db\n```\n\n## License\n\nLicensed under Apache License, Version 2.0\n\nCopyright (c) 2021 - present Romain Clement\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frclement%2Fdatasette-dashboards","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frclement%2Fdatasette-dashboards","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frclement%2Fdatasette-dashboards/lists"}