Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Backport 2024.01.xx] Fix #10434 update custom theme documentation (#10454) #10456

Merged
merged 1 commit into from
Jul 4, 2024
Merged

[Backport 2024.01.xx] Fix #10434 update custom theme documentation (#10454) #10456

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
256 changes: 81 additions & 175 deletions docs/developer-guide/customize-theme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: <your theme 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:

Expand All @@ -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")
+ },
...
Expand All @@ -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.

Expand Down Expand Up @@ -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.
Loading