datalab-item-plugin-template

Warning

This repository is still under active development and will have some rough edges. Please raise any issues in the Issue Tracker or contact us via the routes listed at datalab-org.

A Copier template for datalab plugins that register custom item types via the pydatalab.item_types entry point (the sibling of datalab-app-plugin-template, which targets block plugins).

Important

Custom item types are not yet part of a released datalab version; generated plugins currently develop against the ml-evs/custom-items branch of datalab-org/datalab (wired up in the generated pyproject.toml via [tool.uv.sources]).

The generated plugin contains a documented example item model demonstrating the datalab_* schema annotations (references to other items, values with units, enums, multi-line text, field sections, summary projection, ...). By default the datalab web UI renders these fields automatically from their annotations — no JavaScript required. Answer yes to the include_custom_panel question to also scaffold a custom Vue panel (webapp/<ClassName>Panel.vue), which takes over rendering of all the item's custom fields and is bundled into the webapp with invoke dev.collect-plugin-panels.

We recommend using uv to manage Python versions and environments, in which case the template can be used with:

uvx copier copy "git@github.com:Matgenix/datalab-item-plugin-template" <my_plugin>

This will guide you through the process of creating a new repository for your plugin. You can commit the result, alongside the .copier-answers.yml file, to your new repository (after creating it on GitHub or elsewhere):

cd <my_plugin>
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repo-url>

You can also occasionally sync changes from this template by running the following command in your plugin repository:

uvx copier update

Releases of the plugin are created via semantic version tags on GitHub.

Two example uses of this template can be found at datalab-item-plugin-example (fields rendered automatically from schema annotations, no JavaScript) and datalab-item-plugin-example-custom-vue (a custom Vue panel, whose mixed_solutions items are blended from the first example's solutions items — install both together).