-
-
Notifications
You must be signed in to change notification settings - Fork 686
/
custom-styling.md
158 lines (118 loc) · 5.26 KB
/
custom-styling.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
---
myst:
html_meta:
"description": "Styling a Volto website using Semantic UI."
"property=og:description": "Styling a Volto website using Semantic UI."
"property=og:title": "Custom Styling"
"keywords": "Volto, Plone, frontend, React, Custom, Styling, Semantic UI, LESS, Pastanaga"
---
# Custom Styling
## Semantic UI
For styling our website in Volto we use Semantic UI. It uses LESS as
the underlying technology. By default Volto uses the Pastanaga theme but any
theme can be used. A theme has the following folder structure:
- assets
- collections
- elements
- globals
- modules
- views
## Variables and overrides files
The assets folder contains all the images and fonts. The other folders contain
LESS files. Those less files are separate for each UI component. For example we
have separate files for buttons. Each UI component has 2 files: a `.variables`
file and an `.overrides` file. The `.variables` file contains all the
predefined variables which you can override in your theme. If you want to do
more specific customizations you can use the `.overrides` file to write your own LESS.
```{tip}
You can find the default definitions for all the available variables in the
default theme components (the site component in the example) in two ways, by using the source code:
`node_modules/semantic-ui-less/themes/default/globals/site.variables`
or by checking it out on Github:
https://github.com/Semantic-Org/Semantic-UI-LESS/blob/master/themes/default/globals/site.variables
```
```{tip}
Similarly, you can take a look at the default styling on the default
definitions, by using the source code:
`node_modules/semantic-ui-less/definitions/globals/site.less`
or by checking it out on Github:
https://github.com/Semantic-Org/Semantic-UI-LESS/blob/master/definitions/globals/site.less
```
In the globals folder we have the `site.variables` and `site.overrides` files
which contain the site wide styling. If you want to customize something in the
site component, you should create the `globals` folder and place inside one (or
both) files (including the matching folder structure) in your theme folder.
## Pastanaga UI Theme
Volto implements Pastanaga UI theme, a new theme for Content Management Systems
created and designed by [Albert Casado](https://twitter.com/albertcasado).
For more info:
* https://pastanaga.io
* https://github.com/plone/pastanaga
* https://2017.ploneconf.org/talks/pastanaga-ui-resistance-is-futile
Volto look and feel is a Semantic UI theme that implements Pastanaga UI, called
`pastanaga` and can be found in the Volto `theme/themes/pastanaga` directory.
```{tip}
You can find it in the source code:
`node_modules/@plone/volto/theme/themes/pastanaga`
or on Github:
https://github.com/plone/volto/tree/master/theme/themes/pastanaga
```
Pastanaga Theme is an example on how to customize the default Semantic UI look
and feel.
## Examples: Changing Base Font
We start by creating the file `theme/globals/site.variables`.
In this file we can override any value.
We do not need to copy the whole file from Volto core.
We can add variables we would like to change.
When we want to change the base font, we add the following:
```less
@fontName : 'Comic Sans MS';
```
The font 'Comic Sans MS' needs to be either installed on you machine or provided with your app.
To provide the font with your app, the following steps are necessary:
1. Get your font and copy the files to `/theme/assets/fonts/<font name with space replaced by _>`.
1. Usually the font provider gives you ready made font-face instructions.
Copy these font-face code lines to `/theme/typography.css`.
There are a lot of font providers.
If you choose Google fonts, check [google-webfonts-helper](https://gwfh.mranftl.com/fonts) to generate `font-face` CSS code and download font files to include in your project.
1. Add to the end of `/theme/theme.config` a function to load your font-faces:
```less
.loadThemeFonts() {
@import "./typography.css";
}
```
1. Call this load function in `/theme/globals/site.overrides`:
```less
.loadThemeFonts();
```
1. In `/theme/globals/site.variables` you can now override both, the font for headings (h1, h2, h3, …) and the font for the rest.
```less
// Do not override @fontName!
// @fontName: 'Raleway', 'Helvetica Neue', Arial, Helvetica, sans-serif;
@pageFont: 'Raleway', 'Helvetica Neue', Arial, Helvetica, sans-serif;
@headerFont: 'Rubic Microbe', 'Helvetica Neue', Arial, Helvetica, sans-serif;
```
Voilà.
Start your Volto app if you created new files.
````{tip}
For testing purpose you can refrain from installing the font and from providing the font with your app if the font is a Google font.
With the following two lines you tell Volto to load the font "Montserrat" from `fonts.google.com`.
```less
@fontName : 'Montserrat';
@importGoogleFonts : true;
```
````
## Changing The Breadcrumbs
Change the breadcrumbs so that the divider is pink in `theme/collections/breadcrumb.variables`:
```less
@dividerColor: @pink;
```
## Using Overrides
For features which are not supported in Semantic UI through the variables, we
can use the overrides files. Update the breadcrumbs so that the links are
underlined, then in `theme/collections/breadcrumb.overrides`:
```less
.ui.breadcrumb a {
text-decoration: underline;
}
```