Mercurial > libervia-web

annotate doc/web_framework/css_framework.rst @ 1518:eb00d593801d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
refactoring: rename `libervia` to `libervia.web` + update imports following backend changes
author Goffi <goffi@goffi.org>
date Fri, 02 Jun 2023 16:49:28 +0200
parents 4648a333b33f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
1 Libervia CSS Framework
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
2 ======================
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
3
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
4
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
5 Libervia comes with generic CSS styling which is thought to be re-usable. If you create a new theme/site, you don't have to use it and can use something totally different, but building on top of Libervia CSS make theming more easy and consistent as you can re-use existant components without changing the classes.
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
6
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Bases
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
8 -----
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
9 All CSS files must be in the ``static`` directory of your theme. Following names are assumed to be in this directory.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
10
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
11 Libervia may link one to several style sheets when it renders a template. It will always links the following file (if they exist):
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
12 - ``fonts.css`` (fonts loading)
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
13 - ``styles.css`` (main CSS style, see below)
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
14 - ``styles_extra`` (customizations of main style)
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
15
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
16 Then it will link styles relative to the current theme (where path is joined with a ``_``). For instance, if your template is ``blog/article.html``, the following files will be linked (in this order, and if they exists):
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
17 - ``blog.css``
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
18 - ``blog_article.css``
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
19
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
20 You can suffix any style sheet (but ``fonts.css``) with ``_noscript``: this suffixed file will be loaded only when javascript is not available, allowing to adapt your template to such case.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
21
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
22 The main CSS styling is ``styles.css``, it contains styles for every major elements used in Libervia.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
23 CSS in Libervia follows ``BEM`` (Block Element Modifier) conventions.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
24
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
25 If you create a new theme, you should not touch ``styles.css``, but work on ``styles_extra.css`` instead. The later doesn't exist in default Libervia theme on purpose.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
26
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
27 There are a few "magic" classes, which imply some DOM modification when Javascript is enabled, see below.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
28 Last but not least, there is also a "state system", i.e. classes which are dynamically changed during runtime.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
29
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
30 Magic Classes
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
31 -------------
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
32 Magic classes are classes which imply a modification of DOM when the page is loaded and Javascript is activated.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
33 The modification is done by a script launched by ``base/base.html``.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
34 There are only a few of them:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
35
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
36 box--expand
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
37 When this class is applied, the box will be folded when higher than 250px, and 2 "expand zone" (buttons)
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
38 will be added on top and bottom of the box to expand/reduce it.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
39
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
40 state_init
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
41 This is linked to state system (see below). When applied, the element will keep the ``state_init`` class until
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
42 clicked for the first time, then it will apply other magic classes effects if suitable.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
43
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
44 State System
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
45 ------------
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
46 A basic state system is used to do some dynamic operation (like (un)folding a box). The two main states are:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
47
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
48 state_init
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
49 This class is present until first clicked
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
50
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
51 state_clicked
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
52 This state is used with some magic classes (e.g. ``box-expand``) or when a clicking method from ``common.js``
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
53 is used on an element (e.g. ``clicked_cls``). The classes is toggled on each click.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
54
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
55 Some classes are used to manipulate elements according to state:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
56
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
57 show_if_init
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
58 Display this class only if in ``state_init``.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
59
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
60 show_if_parent_clicked
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
61 display this class only if **parent** is in ``state_clicked``
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
62
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
63 show_if_parent_not_clicked
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
64 display this class only if **parent** is **not** in ``state_clicked``
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
65
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
66 show_if_grandparent_clicked
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
67 display this class only if **grandparent** is in ``state_clicked``
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
68
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
69 show_if_grandparent_not_clicked
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
70 display this class only if **grandparent** is **not** in ``state_clicked``