diff --git a/docs/md/SUMMARY.md b/docs/md/SUMMARY.md index 3a161513cc..9e39ef12e6 100644 --- a/docs/md/SUMMARY.md +++ b/docs/md/SUMMARY.md @@ -42,6 +42,7 @@ - [Hosting a `WebSocketServer` in Node.js](./how_to/javascript/nodejs_server.md) - [`perspective-viewer` Custom Element library](./how_to/javascript/viewer.md) - [Theming](./how_to/javascript/theming.md) + - [Custom Themes](./how_to/javascript/custom_themes.md) - [Loading data from a `Table`](./how_to/javascript/loading_data.md) - [Loading data from a virtual `Table`](./how_to/javascript/loading_virtual_data.md) - [Saving and restoring UI state](./how_to/javascript/save_restore.md) diff --git a/docs/md/how_to/javascript/custom_themes.md b/docs/md/how_to/javascript/custom_themes.md new file mode 100644 index 0000000000..baaccb2927 --- /dev/null +++ b/docs/md/how_to/javascript/custom_themes.md @@ -0,0 +1,28 @@ +# Custom themes + +The best way to write a new theme is to +[fork and modify an existing theme](https://github.com/finos/perspective/tree/master/rust/perspective-viewer/src/themes), +which are _just_ collections of regular CSS variables (no preprocessor is +required, though Perspective's own themes use one). `` is +not "themed" by default and will lack icons and label text in addition to colors +and fonts, so starting from an empty theme forces you to define _every_ +theme-able variable to get a functional UI. + +### Icons and Translation + +UI icons are defined by CSS variables provided by +[`@finos/perspective-viewer/dist/css/icons.css`](https://github.com/finos/perspective/blob/master/rust/perspective-viewer/src/themes/icons.less). +These variables must be defined for the UI icons to work - there are no default +icons without a theme. + +UI text is also defined in CSS variables provided by +[`@finos/perspective-viewer/dist/css/intl.css`](https://github.com/finos/perspective/blob/master/rust/perspective-viewer/src/themes/intl.less), +and has identical import requirements. Some _example definitions_ +(automatically-translated sans-editing) can be found +[`@finos/perspective-viewer/dist/css/intl/` folder](https://github.com/finos/perspective/tree/master/rust/perspective-viewer/src/themes/intl). + +Importing the pre-built `themes.css` stylesheet as well as a custom theme will +define Icons and Translation globally as a side-effect. You can still customize +icons in this mode with rules (of the appropriate specificity), _but_ if you do +not still remember to define these variables yourself, your theme will not work +without the base `themes.css` pacage available. diff --git a/examples/blocks/src/editable/index.html b/examples/blocks/src/editable/index.html index 91af59f54d..3cc2e8373b 100644 --- a/examples/blocks/src/editable/index.html +++ b/examples/blocks/src/editable/index.html @@ -2,24 +2,26 @@ - - - - + + + + +