Skip to content

Commit df69019

Browse files
petschkipetschki
committed
barceloneta based theme doc
1 parent 5602ffc commit df69019

File tree

1 file changed

+296
-16
lines changed

1 file changed

+296
-16
lines changed

‎docs/classic-ui/theming/barceloneta.md‎

Lines changed: 296 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -30,40 +30,320 @@ See https://github.com/plone/documentation/issues/1286
3030

3131
(classic-ui-theming-barceloneta-theme-package-label)=
3232

33-
## Theme package
33+
## Create a Classic UI theme addon package
3434

35-
- Generated theme package can be uploaded as a .zip file.
35+
Create a Classic UI theme addon with `plonecli`:
36+
37+
```shell
38+
plonecli create addon plonetheme.themebasedonbarceloneta
39+
```
40+
41+
Then change the working directory into the created package and add the
42+
basic theme structure with:
43+
44+
```shell
45+
cd plonetheme.themebasedonbarceloneta
46+
plonecli add theme_barceloneta
47+
```
48+
49+
Give your theme a name and optionally commit the changes.
50+
After that the theming structure is setup and ready for customization.
3651

3752

3853
(classic-ui-theming-barceloneta-theme-structure-label)=
3954

4055
## Theme structure
4156

42-
### `base.scss`
57+
All the theming relevant files are now located inside `src/plonetheme/themebasedonbarceloneta/theme/`:
58+
59+
```
60+
./src/plonetheme/themebasedonbarceloneta/theme/
61+
├── barceloneta-apple-touch-icon-114x114-precomposed.png
62+
├── barceloneta-apple-touch-icon-144x144-precomposed.png
63+
├── barceloneta-apple-touch-icon-57x57-precomposed.png
64+
├── barceloneta-apple-touch-icon-72x72-precomposed.png
65+
├── barceloneta-apple-touch-icon-precomposed.png
66+
├── barceloneta-apple-touch-icon.png
67+
├── barceloneta-favicon.ico
68+
├── index.html
69+
├── manifest.cfg
70+
├── package.json
71+
├── preview.png
72+
├── rules.xml
73+
├── scss
74+
│ ├── _custom.scss
75+
│ ├── _maps.scss
76+
│ ├── _variables.scss
77+
│ └── theme.scss
78+
├── styles
79+
│ ├── theme.css
80+
│ └── theme.min.css
81+
└── tinymce-templates
82+
├── README.rst
83+
├── card-group.html
84+
└── list.html
85+
```
86+
87+
### `index.html`
88+
89+
- Basic HTML structure for the site layout.
90+
91+
### `manifest.cfg`
92+
93+
- Basic theme configuration for the backend.
94+
95+
### `package.json`
96+
97+
- npm package configuration which defines all requirements for theming
98+
with barceloneta.
99+
100+
### `rules.xml`
101+
102+
- Diazo rules which translate the `index.html` and fills it with content
103+
from the backend.
104+
105+
### `scss/_custom.scss`
106+
107+
- Custom SCSS rules for your theme.
108+
109+
### `scss/_maps.scss`
110+
111+
- Override Bootstrap mapping variables here.
112+
113+
### `scss/_variables.scss`
43114

44-
- Basics required for backend
115+
- Override Bootstrap and/or Barceloneta variables here.
45116

46-
### `barceloneta.scss`
117+
### `scss/theme.scss`
47118

48-
- Barceloneta theme basics
119+
- Base theme file which follows "Option B" of customizing Bootstrap imports
120+
to enable custom variable and map injections. Note that the order of these imports is mandatory to ensure overriding the defaults. See https://getbootstrap.com/docs/5.3/customize/sass/#importing
49121

122+
### `styles/theme.css[.min]`
123+
124+
- Compiled CSS styles.
125+
126+
### `tinymce-templates/*.html`
127+
128+
- HTML snippets for the TinyMCE `template` plugin.
129+
130+
131+
(classic-ui-theming-barceloneta-npm-package-label)=
50132

51133
## npm package
52134

53-
- npm package with files required for Plone
54-
- dependencies required by theme to compile
135+
To compile the SCSS code you have to install the required dependencies with `npm`
136+
and run the package script `build` inside the `theme/` folder:
137+
138+
```shell
139+
npm install
140+
npm run build
141+
```
142+
143+
During theme development you can run:
144+
145+
```shell
146+
npm run watch
147+
```
148+
149+
this compiles the SCSS resources on the fly when you change something inside
150+
the `scss/` folder.
151+
152+
153+
(classic-ui-theming-barceloneta-customize-components-label)=
154+
155+
## Customize Bootstrap and Barceloneta components
156+
157+
The base `theme/theme.scss` file provides all imports of the dependent Bootstrap
158+
and Barceloneta resources to build the default Classic UI theme.
159+
As a convenience `bobtemplates.plone` has created three files to customize
160+
variables, maps and custom SCSS code.
161+
162+
```
163+
scss/_custom.scss
164+
scss/_maps.scss
165+
scss/_variables.scss
166+
```
167+
168+
### SCSS and root variables
169+
170+
- show example how to override variables
171+
- complete list of variables below
172+
173+
### Properties
174+
175+
If you want to disable rounded corners for borders:
55176

177+
```scss
178+
$enabled-rounded: false;
179+
```
180+
181+
A complete list of all properties see below. (Link?)
182+
183+
TODO: screenshot?
184+
185+
186+
### Maps
187+
188+
Maps are key value pairs to make CSS generation easier. As an example this is the workflow colors map:
189+
190+
```scss
191+
$state-colors: (
192+
"draft": $state-draft-color,
193+
"pending": $state-pending-color,
194+
"private": $state-private-color,
195+
"internal": $state-internal-color,
196+
"internally-published": $state-internally-published-color,
197+
) !default;
198+
```
199+
200+
If you have a custom workflow state you can add your state color to the default map:
201+
202+
```scss
203+
$custom-state-colors: (
204+
"my-custom-state-id": #ff0000;
205+
);
206+
207+
// Merge the maps
208+
$state-colors: map-merge($state-colors, $custom-colors);
209+
```
210+
211+
212+
### Custom CSS code
213+
214+
Inside the file `theme/_custom.scss` you can write all your custom CSS/Sass code
215+
to adapt the theme to your needs. Feel free to add more files inside the `scss/` folder to make your code more readable. Don't forget to import your custom files in `scss/theme.scss`.
216+
217+
218+
(classic-ui-theming-barceloneta-default-variables-properties-label)=
219+
220+
## Default variables and properties
221+
222+
The following variables and properties are defined in Bootstrap and customized by Barceloneta.
223+
224+
### Component variables
225+
226+
```scss
227+
// Barceloneta settings
228+
229+
$primary: $plone-link-color!default;
230+
$light: $plone-light-color!default;
231+
$dark: $plone-dark-color!default;
56232

57-
## Bootstrap components
233+
$spacer: 1rem!default; // not changed but needed to calc other definitions
58234

59-
- Default components are extended with some custom components, such as a select or dropdown menu.
60-
- We use Boostrap variables in these cases.
61235

236+
// Grid columns
237+
// Set the number of columns and specify the width of the gutters.
62238

63-
## Add-ons and templates
239+
// $grid-columns: 12 !default;
240+
// $grid-gutter-width: 1.5rem !default;
241+
// $grid-row-columns: 6 !default;
64242

65-
Make life easy with...
243+
$grid-main-breakpoint: lg!default;
244+
$nav-main-breakpoint: $grid-main-breakpoint!default;
66245

67-
- use Bootstrap markup
68-
- use Bootstrap components
69-
- use Bootstrap variables
246+
$navbar-barceloneta-background: $primary!default;
247+
248+
$navbar-padding-y: 0 !default;
249+
$navbar-padding-x: 0 !default;
250+
$navbar-nav-link-padding-y: $spacer * .75 !default;
251+
$navbar-nav-link-padding-x: $spacer !default;
252+
253+
$navbar-light-color: rgba($black, .55) !default;
254+
$navbar-light-active-color: rgba($black, .7) !default;
255+
$navbar-light-active-background: rgba($black, .2) !default;
256+
$navbar-light-hover-color: rgba($black, .9) !default;
257+
$navbar-light-hover-background: rgba($black, .3) !default;
258+
259+
$navbar-dark-color: rgba($white, 1) !default;
260+
$navbar-dark-active-color: rgba($white, 1) !default;
261+
$navbar-dark-active-background: rgba($white, .2) !default;
262+
$navbar-dark-hover-color: rgba($white, 1) !default;
263+
$navbar-dark-hover-background: rgba($white, .3) !default;
264+
265+
$navbar-barceloneta-color: rgba($white, 1) !default;
266+
$navbar-barceloneta-active-color: rgba($white, 1) !default;
267+
$navbar-barceloneta-active-background: rgba($black, .2) !default;
268+
$navbar-barceloneta-hover-color: rgba($white, 1) !default;
269+
$navbar-barceloneta-hover-background: rgba($black, .3) !default;
270+
271+
272+
$plone-portlet-navtree-maxlevel: 5!default;
273+
274+
275+
// Typography
276+
// While Plone Logo uses the DIN Font, we use Roboto, which was designed for Android and so mobile optimized
277+
// A free DIN variant is available here (TTF only): https://www.1001fonts.com/alte-din-1451-mittelschrift-font.html
278+
$font-family-sans-serif: "Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif!default;
279+
$font-family-condensed: "Roboto Condensed", "Arial Narrow", sans-serif!default; //just on toolbar
280+
$font-family-serif: Georgia, "Times New Roman", Times, serif!default;
281+
// $font-family-base: var(--bs-font-sans-serif) !default;
282+
// $font-family-code: var(--bs-font-monospace) !default;
283+
284+
// Include Roboto as webfont
285+
$enable-roboto-webfont: true !default;
286+
287+
// $font-size-base: 1rem !default; // Assumes the browser default, typically `16px`
288+
// $font-size-sm: $font-size-base * .875 !default;
289+
// $font-size-lg: $font-size-base * 1.25 !default;
290+
291+
$font-weight-lighter: lighter !default;
292+
$font-weight-light: 300 !default;
293+
$font-weight-normal: 400 !default;
294+
$font-weight-semibold: 600 !default;
295+
$font-weight-bold: 700 !default;
296+
$font-weight-bolder: bolder !default;
297+
298+
// $font-weight-base: $font-weight-normal !default;
299+
300+
// $line-height-base: 1.5 !default;
301+
// $line-height-sm: 1.25 !default;
302+
// $line-height-lg: 2 !default;
303+
304+
// $h1-font-size: $font-size-base * 2.5 !default;
305+
// $h2-font-size: $font-size-base * 2 !default;
306+
// $h3-font-size: $font-size-base * 1.75 !default;
307+
// $h4-font-size: $font-size-base * 1.5 !default;
308+
// $h5-font-size: $font-size-base * 1.25 !default;
309+
// $h6-font-size: $font-size-base !default;
310+
311+
// $headings-margin-bottom: $spacer * .5 !default;
312+
// $headings-font-family: null !default;
313+
// $headings-font-style: null !default;
314+
$headings-font-weight: $font-weight-normal !default;
315+
// $headings-line-height: 1.2 !default;
316+
// $headings-color: null !default;
317+
318+
// Breadcrumbs
319+
$breadcrumb-margin-bottom: 2rem !default;
320+
$breadcrumb-bg: var(--bs-secondary-bg) !default;
321+
$breadcrumb-padding-y: $spacer * 0.5 !default;
322+
$breadcrumb-padding-x: $spacer * 1 !default;
323+
324+
325+
// Footer
326+
$footer-bg: $gray-900 !default;
327+
$footer-color: $gray-300 !default;
328+
```
329+
330+
### Properties
331+
332+
```scss
333+
$enable-caret: true !default;
334+
$enable-rounded: true !default;
335+
$enable-shadows: false !default;
336+
$enable-gradients: false !default;
337+
$enable-transitions: true !default;
338+
$enable-reduced-motion: true !default;
339+
$enable-smooth-scroll: true !default;
340+
$enable-grid-classes: true !default;
341+
$enable-container-classes: true !default;
342+
$enable-cssgrid: false !default;
343+
$enable-button-pointers: true !default;
344+
$enable-rfs: true !default;
345+
$enable-validation-icons: true !default;
346+
$enable-negative-margins: true !default;
347+
$enable-deprecation-messages: true !default;
348+
$enable-important-utilities: false !default;
349+
```

0 commit comments

Comments
 (0)