Mercurial > libervia-web

annotate doc/web_framework/css_framework.rst @ 1504:409d10211b20

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
server, browser: dynamic pages refactoring: dynamic pages has been reworked, to change the initial basic implementation. Pages are now dynamic by default, and a websocket is established by the first connected page of a session. The socket is used to transmit bridge signals, and then the signal is broadcasted to other tabs using broadcast channel. If the connecting tab is closed, an other one is chosen. Some tests are made to retry connecting in case of problem, and sometimes reload the pages (e.g. if profile is connected). Signals (or other data) are cached during reconnection phase, to avoid lost of data. All previous partial rendering mechanism have been removed, chat page is temporarily not working anymore, but will be eventually redone (one of the goal of this work is to have proper chat).
author Goffi <goffi@goffi.org>
date Wed, 01 Mar 2023 18:02:44 +0100
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``