diff --git a/docs/developer-guide/customize-theme.md b/docs/developer-guide/customize-theme.md index 38ec8bed18..3a65083d3d 100644 --- a/docs/developer-guide/customize-theme.md +++ b/docs/developer-guide/customize-theme.md @@ -3,181 +3,13 @@ The look and feel is completely customizable either using one of the included themes, or building your own. Themes are built using [less](http://lesscss.org/). You can find the default theme here: [https://github.com/geosolutions-it/MapStore2/tree/master/web/client/themes/default](https://github.com/geosolutions-it/MapStore2/tree/master/web/client/themes/default) -## Theme Structure +## Custom theme for a downstream project -```text -. -+-- themes/ -| +-- theme-name/ -| +-- icons/ -| +-- icons.eot -| +-- icons.svg -| +-- icons.ttf -| +-- icons.woff -| +-- icons.woff2 -| +-- img/ -| +-- less/ -| +-- mixins/ -| +-- bootstrap.less -| +-- css-properties.less -| +-- theme.less -| +-- mapstore.less -| +-- common.less -| +-- style-module.less -| +-- .less files for all the other modules -| +-- base.less -| +-- bootstrap-theme.less -| +-- bootstrap-variables.less -| +-- icons.less -| +-- ms2-theme.less -| +-- ms-variables.less -| +-- theme.less -| +-- variables.less -``` - -`theme.less` is the entry point for all the main imports and it needs to be properly required in `buildConfig.js` or in your `webpack.config.js` in the themeEntries. - -`theme.less` imports - -|file|description| -|----------|------| -|base.less|contains a declaration of font colors and background defined for data-ms2-container attribute which is usually the body tag| -|icons.less|contains font-face declaration for glyphs, it extends the bootstrap glyphicons to use custom MapStore icons| -|bootstrap-theme.less|contains all the less style for bootstrap components| -|ms2-theme.less|contains all the less style for MapStore components| -|variable.less|contains the import of mapstore variables and the override of bootstrap variables| - -below an example of entry configuration: - -```js -entry: { - ...other entries, - 'themes/theme-name': path.join(__dirname, 'path-to', 'theme-name', 'theme.less') -}, -``` - -MapStore uses a `themeEntries` function to automatically create the entries for default themes that can be found under the `web/client/themes` directory - -```js -const themeEntries = require('./themes.js').themeEntries; - -entry: { - ...other entries, - ...themeEntries -}, -``` - -Default themes in [`web/client/themes`](https://github.com/geosolutions-it/MapStore2/tree/master/web/client/themes) directory are useful to have an overview of the structure described above. - -Note: we suggest to place the theme folder inside a `themes` directory for MapStore project - -### Structure of .less files - -Each less file that represent a MapStore plugin or component is composed by two sections: - -- **Theme section** includes all the styles and classes that should change based on css variables. All the new declared selector must be included in a special function called `#ms-components-theme`. The `#ms-components-theme` function provide access to all the available variables of the theme via the `@theme-vars` argument. - -- **Layout section** includes all the styles and classes that should not change in a simple customization. - -Example: - -```less -// ************** -// Theme -// ************** -#ms-components-theme(@theme-vars) { - // here all the selectors related to the theme - // use the mixins declared in the web/client/theme/default/less/mixins/css-properties.less - // to use one of the @theme-vars - - // eg: use the main background and text colors to paint my plugin - .my-plugin-class { - .color-var(@theme-vars[main-color]); - .background-color-var(@theme-vars[main-bg]); - } -} - -// ************** -// Layout -// ************** - -// eg: fill all the available space in the parent container with my plugin -.my-plugin-class { - position: absolute; - height: 100%; - width: 100%; -} - -// here -``` - -### ms-variables.less - -MapStore uses basic less variables to change theme colors, buttons sizes and fonts. -It possible also to override bootstrap less variable for advanced customization. -Basic variables can be found in the ms-variable.less file - -New declarations in MapStore should have the following structure: - -global: `@ms-rule-value` - -local: `@ms-name-of-plugin--rule-value` - -- `@ms` suffix for MapStore variable -- `name-of-plugin` for local variable it's important to write the name of plugin in kebab-case -- `rule-value` value to use in compiled CSS, some examples: - - `color` generic color variable - - `text-color` color for text - - `background-color` color for background - - `border-color` color for border - -### less/ directory - -The `less/` directory contains all the modules needed to create the final CSS of MapStore. - -Each file in this directory is related to a specific plugin or component and the files are named based on the plugin's name are referring to. - -`common.less` file can be used for generic styles. - -### inline styles - -Inline styles should be applied only for values that change dynamically during the lifecycle of the application, all others style should be moved to the related .less file. - -The main reason of this choice is to allow easier overrides of styles in custom projects. - -## Add New Theme - -To support a new theme for mapstore product: - -1. create a new folder in the themes folder with the name of your theme -1. create less files in the folder (at least `theme.less`, as the main file and `variables.less`, to customize standard variables) -1. add the new theme to the [index file](https://github.com/geosolutions-it/MapStore2/blob/master/web/client/themes/index.js), with the id corresponding to the theme folder name - -If you are not using themeEntries a new entry needs to be added in the `buildConfig.js` - -You can then switch your application to use the theme adding a new section in the `appConfig.js` file: - -```json -initialState: { - defaultState: { - ... - theme: { - selectedTheme: { - id: - } - }, - ... - } -} -``` - -## Custom Theme for project - -In a mapstore project normally the theme configuration is placed in the `themes/` directory +In a [MapStore downstream project](mapstore-projects.md) normally the theme configuration is placed in the `themes/` directory Styles can be overridden declaring the same rules in a less module placed in a new project. -Below steps to configure a custom theme and override styles: +Below steps to configure a custom theme to override styles of the default theme: - add the following files to the themes folder of the project: @@ -202,14 +34,14 @@ Below steps to configure a custom theme and override styles: - update webpack configuration to use the custom style (webpack.config.js, prod-webpack.config.js) ```diff -module.exports = require('./MapStore2/buildConfig')( - { +module.exports = require('./MapStore2/build/buildConfig')({ + bundles:{ '__PROJECTNAME__': path.join(__dirname, "js", "app"), '__PROJECTNAME__-embedded': path.join(__dirname, "MapStore2", "web", "client", "product", "embedded"), '__PROJECTNAME__-api': path.join(__dirname, "MapStore2", "web", "client", "product", "api") }, - themeEntries, -+ { ++ themeEntries: { + "themes/default": path.join(__dirname, "themes", "default", "theme.less") + }, ... @@ -231,7 +63,7 @@ module.exports = require('./MapStore2/buildConfig')( } ``` -## Custom Theme for contexts +## Custom theme for contexts You can configure a list of themes to be used inside a context. @@ -434,3 +266,77 @@ Note: These three styles are an example on how is possible to approach on the ma */ }, ``` + +### Structure of .less files + +Each less file that represent a MapStore plugin or component is composed by two sections: + +- **Theme section** includes all the styles and classes that should change based on css variables. All the new declared selector must be included in a special function called `#ms-components-theme`. The `#ms-components-theme` function provide access to all the available variables of the theme via the `@theme-vars` argument. + +- **Layout section** includes all the styles and classes that should not change in a simple customization. + +Example: + +```less +// ************** +// Theme +// ************** +#ms-components-theme(@theme-vars) { + // here all the selectors related to the theme + // use the mixins declared in the web/client/theme/default/less/mixins/css-properties.less + // to use one of the @theme-vars + + // eg: use the main background and text colors to paint my plugin + .my-plugin-class { + .color-var(@theme-vars[main-color]); + .background-color-var(@theme-vars[main-bg]); + } +} + +// ************** +// Layout +// ************** + +// eg: fill all the available space in the parent container with my plugin +.my-plugin-class { + position: absolute; + height: 100%; + width: 100%; +} + +// here +``` + +### ms-variables.less + +MapStore uses basic less variables to change theme colors, buttons sizes and fonts. +It possible also to override bootstrap less variable for advanced customization. +Basic variables can be found in the ms-variable.less file + +New declarations in MapStore should have the following structure: + +global: `@ms-rule-value` + +local: `@ms-name-of-plugin--rule-value` + +- `@ms` suffix for MapStore variable +- `name-of-plugin` for local variable it's important to write the name of plugin in kebab-case +- `rule-value` value to use in compiled CSS, some examples: + - `color` generic color variable + - `text-color` color for text + - `background-color` color for background + - `border-color` color for border + +### less/ directory + +The `less/` directory contains all the modules needed to create the final CSS of MapStore. + +Each file in this directory is related to a specific plugin or component and the files are named based on the plugin's name are referring to. + +`common.less` file can be used for generic styles. + +### inline styles + +Inline styles should be applied only for values that change dynamically during the lifecycle of the application, all others style should be moved to the related .less file. + +The main reason of this choice is to allow easier overrides of styles in custom projects.