Styling and Theming
The look and feel is completely customizable either using one of the included themes, or building your own. Themes are built using less.
You can find the default theme here: https://github.com/geosolutions-it/MapStore2/tree/master/web/client/themes/default
Custom theme for a downstream project
In a MapStore downstream project 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 to override styles of the default theme:
- add the following files to the themes folder of the project:
.
+-- themes/
| +-- default/
| +-- less/
| +-- my-custom-module.less
| +-- theme.less
| +-- variables.less
- import in
theme.less
all the needed less module
@import "../../MapStore2/web/client/themes/default/theme.less";
@import "./variables.less";
@import "./less/my-custom-module.less";
- update webpack configuration to use the custom style (webpack.config.js, prod-webpack.config.js)
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")
+ },
...
- update
variables.less
to override existing variables
/* change primary color to blue */
@ms-primary: #0000ff;
- update
my-custom-module.less
to override existing rules or add new rules
/* change the background color of the page*/
.page {
background-color: #d9e6ff;
}
Custom theme for contexts
You can configure a list of themes to be used inside a context.
In order to do that you have to:
- create the themes in the
themes/
folder as described below - edit ContextCreator plugin in the
localConfig.json
example
{
"name": "ContextCreator",
"cfg": {
"documentationBaseURL": "https://mapstore.geosolutionsgroup.com/mapstore/docs/api/plugins",
"backToPageDestRoute": "/context-manager",
"backToPageConfirmationMessage": "contextCreator.undo",
"themes": [{
"id": "complete-theme-override",
"type": "link",
"href": "dist/themes/complete-theme-override.css",
"defaultVariables": {
"ms-main-color": "#000000",
"ms-main-bg": "#FFFFFF",
"ms-primary-contrast": "#FFFFFF",
"ms-primary": "#078aa3",
"ms-success-contrast": "#FFFFFF",
"ms-success": "#398439"
}
},
{
"id": "partial-theme-override",
"type": "link",
"href": "dist/themes/partial-theme-override.css"
},
{
"id": "only-css-variables",
"type": "link",
"href": "dist/themes/only-css-variables.css"
}
],
"basicVariables": {
"ms-main-color": "#000000",
"ms-main-bg": "#FFFFFF",
"ms-primary-contrast": "#FFFFFF",
"ms-primary": "#078aa3",
"ms-success-contrast": "#FFFFFF",
"ms-success": "#398439"
}
}
}
for each theme you can define:
- id id of the theme equal to its name
- type values can be
- link will require a href property
- href path to find the css once built
- defaultVariables variables of the theme used to initialize the pickers (optional)
basicVariables these are the variables used as default values if a theme is not selected (optional)
Suggested ways to create a custom theme for a context
Complete theme override
This example will create a complete css file and is not recommended if you want a light version and you just need to customize the variables (for this check next paragraph)
Add the following files to the themes folder of the project
+-- themes/
| +-- theme-name/
| +-- theme.less
| +-- variables.less
in theme.less
put
/*
* This example will contain a complete mapstore theme with some customization
* it will be selectable inside context theme step selector
*/
/*
* it includes the main theme and this will recompile the whole theme
*/
@import "../../MapStore2/web/client/themes/default/theme.less";
/*
* it includes some changes to css variables
*/
@import "./variables.less";
/*
* Note: You can always expand it with new less/css rules
*/
in variables.less
you can put the mapstore variables customizations
/*
* A variable that will override the default css one
*/
@ms-primary: #2E13FE;
Only css variables
This example is perfect if you just want to customize a few colors of the theme
+-- themes/
| +-- theme-name/
| +-- theme.less
| +-- variables.less
in theme.less
put
/*
* This example is the lightest version of all three examples
* it will be selectable inside context theme step selector
* this examples is limited to changing the css variables only,
* but you can always expand it as we did for partial-theme-override
*/
/*
* This will import as (reference) https://lesscss.org/features/#import-atrules-feature-reference
* It's used to import external files, but without adding the imported styles
* to the compiled output unless referenced.
*
*/
@import (reference) "../../MapStore2/web/client/themes/default/theme.less";
/*
* it includes some changes to css variables
*/
@import "./variables.less";
/*
* this will create only one class with the :root selector inside
* it's important to place the variable overrides before calling the css-variable mixin generator
* which is called .get-root-css-variables
*/
.get-root-css-variables(@ms-theme-vars);
/*
* Note: You can always expand it with new less/css rules
*/
In the variables.less
you can do put your variable customizations
partial theme override
+-- themes/
| +-- theme-name/
| +-- less/
| +-- plugin-name.less
/*
* We can use this method when we want to customize some part of the theme
* without the need to include the theme in its completeness
*/
/*
* here you can apply some other overrides, like the size of thumbnails for backgrounds
*/
@import "./less/drawer-menu.less";
/*
* Note: You can always expand it with new less/css rules
*/
Note: These three styles are an example on how is possible to approach on the mapstore customizations. You could extend/combine them together to create a more complex theme.
Tips
- When you develop locally
- and you want to reduce the building time
- and you don't need themes that are not the default theme
- then you can comment this in the
webpack-config.js
{
["themes/default"]: path.join(__dirname, "themes", "default", "theme.less")
/*,
["themes/complete-theme-override"]: path.join(__dirname, "themes", "complete-theme-override", "theme.less"),
["themes/partial-theme-override"]: path.join(__dirname, "themes", "partial-theme-override", "theme.less"),
["themes/only-css-variables"]: path.join(__dirname, "themes", "only-css-variables", "theme.less")
*/
},
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:
// **************
// 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 variablename-of-plugin
for local variable it's important to write the name of plugin in kebab-caserule-value
value to use in compiled CSS, some examples:color
generic color variabletext-color
color for textbackground-color
color for backgroundborder-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.