dash_tabulator
is a data table component for the Dash Python webapp framework, based on Tabulator.js and used by the Visual Edit webapp.
Being a Dash component, it comes as a Python module that includes a DashTabulator.py
class and minified Javascript code used by Dash to make the component work. Both are generated from the React component’s source code in DashTabulator.react.js
, by webpack
and dash-generate-components
(a Python CLI).
- Pre-requisite: install pyenv-virtualenv. On a Mac:
brew install pyenv pyenv-virtualenv
- Create and activate a Python virtual environment (we use the same Python version as for the Visual Edit plugin, for simplicity):
pyenv virtualenv 3.9.19 dash_tabulator
pyenv activate dash_tabulator
- Install packages:
pip install --upgrade pip
pip install -r requirements.txt
- Pre-requisite: install node 21.2.0 and webpack. On a Mac:
brew install node webpack
- Install packages (going into
node_modules/
):
npm install
-
Reinstall JS dependencies when modifying
packages.json
(for instance when upgrading packages such as Tabulator), and Python dependencies when modifyingrequirements.txt
(this should happen much less frequently). -
Build the node project whenever making changes to the React component's source code. The build command defined in
packages.json
uses:webpack
to bundle all JS code (node modules from above and JS part of the Dash component) intodash_tabulator.min.js
(or.dev.js
when using webpack with--mode development
)dash-generate-components
to create theDashTabulator.py
file and class, to be imported in a Dash webapp; this uses Python, hence the importance of activating the proper Python environment beforehand.
pyenv activate 3.9.19/envs/dash_tabulator
npm run build
- Copy built component (in
dash_tabulator/
) to Visual Edit's Python library:
npm run postbuild
- If you hit an ERR_OSSL_EVP_UNSUPPORTED error while building the node project, it is likely due to this
Run
NODE_OPTIONS=--openssl-legacy-provider npm run build
instead. - Errors when building dash_tabulator at line 79 of dash.development.component_generator.py. This executes a
node
command which fails (dash.extract_meta.js, around lines 137 and 172). Use debug config in VS Code to find out more.
The component code is in src/lib/components/DashTabulator.react.js
. Tabulator is wrapped into a React component, taking in properties that match those of the Dash component in Python: id
, data
, columns
, datasetName
, groupBy
, setProps
, and cellEdited
.
Simple examples of Tabulator in vanilla JS can be found in tabulator_examples/
.
When the React component mounts, in DashTabulator.react.js
, it creates a new instance of the Tabulator library with the given data
, columns
, and groupBy
props. It also sets several options for the table, such as selectable
, layout
, pagination
, movableColumns
, and persistence
.
The columns
prop can include references to JavaScript functions defined in assets/custom_tabulator.js
, which make it easy to customize the data table powered by Tabulator:
minMaxFilterFunction
andminMaxFilterEditor
add a min/max filter to numerical columnsheaderMenu
adds a "Hide" and "Group by" menu to columns, which appears when right-clicking on the column headeritemFormatter
formats items that appear when editing a column with type "list"; if those items are objects withvalue
,label
, and other properties, the label will be shown in bold and other properties will be shown in a new line below the label. This is used for "linked record" columns in Visual Edit's Webapp.
One important feature of DashTabulator.react.js
is that it includes a callback for when a cell is edited. When this happens, the cellEdited
prop is updated with information about the edited cell, including the field name, the editor type, the initial value, the old value, the new value, and the row data. The cellEdited
prop is then passed to the setProps
function, which updates the component's properties and triggers any relevant callbacks. As a result, this information is made available when defining callbacks on cellEdited
in a Dash application that uses DashTabulator.py
.
We use Tabulator's Semantic UI theme and define additional CSS styles in assets/tabulator_dataiku.css
.
The React component also includes some additional functionality for tracking user interactions with the table. For example, when the component is rendered, it requests WT1 to log an event indicating that the data table was displayed; this request is then processed according to your tracking preferences (at the level of your Dataiku instance).
- The
visualedit-display-table
event has the following properties:dataset_name_hash
rows_count
columns_hashed
plugin_version
- The
visualedit-edit-cell
event has the following properties:dataset_name_hash
column_name_hash
column_type
plugin_version
Our component code is a simplified version of what's available in the public dash_tabulator package. The latter uses a react-tabulator library which hasn't been updated to the latest versions of Tabulator. Example usage can be found in this CodeSandbox.
This project was originally generated by the dash-component-boilerplate with the following settings:
- project_name: dash_tabulator
- github_org: dataiku
- description: Tabulator component for Dash
- Select use_async: False
- publish_on_npm: False
- install_dependencies: False
Javascript dependencies are listed in package.json
: it includes dash-extensions
, and we added the latest version of tabulator-tables
.
- The demo app is in
src/demo
and you will import your example component code into your demo app. - Test your code in a Python environment:
- Build your code
$ npm run build
- Run and modify the
usage.py
sample dash app:$ python usage.py
- Build your code
- Write tests for your component.
- A sample test is available in
tests/test_usage.py
, it will loadusage.py
and you can then automate interactions with selenium. - Run the tests with
$ pytest tests
. - The Dash team uses these types of integration tests extensively. Browse the Dash component code on GitHub for more examples of testing (e.g. https://github.com/plotly/dash-core-components)
- A sample test is available in
- Add custom styles to your component by putting your custom CSS files into your distribution folder (
dash_tabulator
).- Make sure that they are referenced in
MANIFEST.in
so that they get properly included when you're ready to publish your component. - Make sure the stylesheets are added to the
_css_dist
dict indash_tabulator/__init__.py
so dash will serve them automatically when the component suite is requested.
- Make sure that they are referenced in
- Review your code
- Create a production build and publish:
-
Build your code:
$ npm run build
-
Create a Python distribution
$ python setup.py sdist bdist_wheel
This will create source and wheel distribution in the generated the
dist/
folder. See PyPA for more information. -
Test your tarball by copying it into a new environment and installing it locally:
$ pip install dash_tabulator-0.0.1.tar.gz
-
If it works, then you can publish the component to NPM and PyPI:
- Publish on PyPI
$ twine upload dist/*
- Cleanup the dist folder (optional)
$ rm -rf dist
- Publish on NPM (Optional if chosen False in
publish_on_npm
)Publishing your component to NPM will make the JavaScript bundles available on the unpkg CDN. By default, Dash serves the component library's CSS and JS locally, but if you choose to publish the package to NPM you can set$ npm publish
serve_locally
toFalse
and you may see faster load times.
- Publish on PyPI
-