@@ -1,7 +1,6 @@
1 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Theming
2 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- =======
1 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ # Skinning the Fossil Web Interface
3 2 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
4 3 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
Every HTML page generated by Fossil has the following basic structure:
5 4 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
6 5 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
<blockquote><table border=1 cellpadding=10><tbody>
7 6 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
<tr><td style='background-color:lightblue;text-align:center;'>Header</td></tr>
@@ -37,17 +36,14 @@
37 36 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
this material automatically unless it sees that you have provided your
38 37 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
own HTML document header within the skin’s Header section.
39 38 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
40 39 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
This design lets most users get the benefit of Fossil’s automatic HTML
41 40 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
document header, which takes care of quite a few different things for
42 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- you, while still allowing you to override if at need. For example, you
43 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- might not agree with Fossil’s default [Content Security Policy][csp]
44 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- which gets set in a `<meta>` tag within this default document header, so
45 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- you could provide your own, which would suppress that code.
41 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ you, while still allowing you to [override if at need](#headfoot).
46 42 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
47 43 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
When overriding the default document header, you might want to use some
48 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- of the TH1 variables documented below such as `$stylesheet_url`
44 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ of the [TH1 variables documented below](#vars) such as `$stylesheet_url`
49 45 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
to avoid hand-writing code that Fossil can generate for you.
50 46 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
51 47 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
The middle "content" section comprises the bulk of most pages and
52 48 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
contains the actual Fossil-generated data
53 49 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
that the user is interested in seeing. The text of this content
@@ -54,14 +50,12 @@
54 50 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
section is not normally configurable. The content text can be styled
55 51 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
using CSS, but it is otherwise fixed. Hence it is the header, the footer,
56 52 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
and the CSS that determine the look of a repository.
57 53 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
We call the bundle of built-in CSS, header, and footer a "skin".
58 54 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
59 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
60 55 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
61 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Built-in Skins
56 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## <a name="builtin"></a>Built-in Skins
62 57 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
63 58 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
Fossil comes with several built-in skins. The sources to these built-ins can
64 59 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
be found in the Fossil source tree under the skins/ folder. The skins/
65 60 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
folder contains a separate subfolder for each built-in skin, with each
66 61 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
subfolders holding four files, "css.txt", "details.txt",
@@ -75,12 +69,12 @@
75 69 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
line option can be used for the
76 70 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
[fossil ui](../../../help?cmd=ui) or
77 71 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
[fossil server](../../../help?cmd=server) commands to force that particular
78 72 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
instance of Fossil to use the specified built-in skin.
79 73 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
80 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Sharing Skins
74 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+
75 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## <a name="sharing"></a>Sharing Skins
81 76 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
82 77 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
The skin of a repository is not part of the versioned state and does not
83 78 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
"push" or "pull" like checked-in files. The skin is local to the
84 79 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
repository. However, skins can be shared between repositories using
85 80 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
the [fossil config](../../../help?cmd=configuration) command.
@@ -104,12 +98,12 @@
104 98 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
necessary.
105 99 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
106 100 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
When cloning a repository, the skin of new repository is initialized to
107 101 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
the skin of the repository from which it was cloned.
108 102 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
109 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Header and Footer Processing
103 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+
104 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## <a name="headfoot"></a>Header and Footer Processing
110 105 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
111 106 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
The `header.txt` and `footer.txt` files of a skin are merely the HTML text
112 107 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
of the header and footer, except that before being prepended and appended to
113 108 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
the content, their text content is run through a
114 109 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
[TH1 interpreter](./th1.md) that might adjust the text as follows:
@@ -120,11 +114,11 @@
120 114 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
or to inhibit or enable the output of subsequent text.
121 115 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
122 116 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
* Text of the form "$NAME" or "$<NAME>" is replaced with
123 117 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
the value of the TH1 variable NAME.
124 118 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
125 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Above, we saw the first few lines of a typical header file:
119 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ Above, we saw the first few lines of a typical Fossil skin header:
126 120 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
127 121 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
<div class="header">
128 122 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
<div class="title"><h1>$<project_name></h1>$<title>/div>
129 123 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
130 124 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
After variables are substituted by TH1, that will look more like this:
@@ -136,17 +130,19 @@
136 130 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
137 131 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
The same TH1 interpreter is used for both the header and the footer
138 132 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
and for all scripts contained within them both. Hence, any global
139 133 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
TH1 variables that are set by the header are available to the footer.
140 134 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
141 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- As pointed out at the start of this document, Fossil provides the HTML
135 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ Fossil provides the HTML
142 136 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
document container tags `<html>`, `<head>`, and their inner content when
143 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- your skin’s header and footer don’t include them.
137 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ your skin’s header and footer don’t include them. This default header
138 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ declares the repository’s Content Security Policy (CSP) which is well
139 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ worth understanding, but since it is not strictly about skinning, we
140 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ cover that in [a separate document](./defcsp.md).
144 141 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
145 142 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
146 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Customizing the ≡ Hamburger Menu
143 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## <a name="menu"></a>Customizing the ≡ Hamburger Menu
147 144 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
148 145 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
The menu bar of the default skin has an entry to open a drop-down menu with
149 146 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
additional navigation links, represented by the ≡ button (hence the name
150 147 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
"hamburger menu"). The Javascript logic to open and close the hamburger menu
151 148 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
when the button is clicked is contained in the optional Javascript part (js.txt)
@@ -200,12 +196,12 @@
200 196 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
The custom `data-anim-ms` attribute can be added to the panel element to direct
201 197 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
the Javascript logic to override the default menu animation duration of 400 ms.
202 198 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
A faster animation duration of 80-200 ms may be preferred for smaller menus. The
203 199 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
animation is disabled by setting the attribute to `"0"`.
204 200 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
205 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- TH1 Variables
201 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+
202 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## <a name="vars"></a>TH1 Variables
206 203 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
207 204 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
Before expanding the TH1 within the header and footer, Fossil first
208 205 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
initializes a number of TH1 variables to values that depend on
209 206 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
repository settings and the specific page being generated.
210 207 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
@@ -242,11 +238,18 @@
242 238 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
Examples: "timeline", "doc/trunk/README.txt", "wiki".
243 239 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
244 240 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
* **csrf_token** - A token used to prevent cross-site request forgery.
245 241 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
246 242 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
* **default_csp** - The content to be used within the default header
247 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- for the "Content-Security-Policy" meta tag.
243 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ for the "Content-Security-Policy" `<meta>` tag. You can use
244 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ [Fossil’s default CSP](./defcsp.md) from this variable in your
245 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ [own custom `<head>`](#headfoot). Alternately, you can override
246 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ the default CSP from the [`th1-setup` script](./th1-hooks.md),
247 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ which runs before TH1 processing happens during skin processing,
248 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ allowing you to set a custom CSP without recompiling Fossil or
249 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ providing a hand-written `<head>` section in the Header section
250 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ of a custom skin.
248 251 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
249 252 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
* **nonce** - The value of the cryptographic nonce for the request
250 253 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
being processed.
251 254 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
252 255 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
* **release_version** - The release version of Fossil. Ex: "1.31"
@@ -275,12 +278,12 @@
275 278 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
All of the above are variables in the sense that either the header or the
276 279 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
footer is free to change or erase them. But they should probably be treated
277 280 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
as constants. New predefined values are likely to be added in future
278 281 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
releases of Fossil.
279 282 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
280 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- Suggested Skin Customization Procedure
283 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+
284 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## <a name="procedure"></a>Suggested Skin Customization Procedure
281 285 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
282 286 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
Developers are free, of course, to develop new skins using any method they
283 287 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
want, but the following is a technique that has worked well in the past and
284 288 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
can serve as a starting point for future work:
285 289 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
@@ -309,9 +312,9 @@
309 312 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
4. Copy/paste the resulting css.txt, details.txt,
310 313 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
header.txt, and footer.txt files
311 314 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
into the CSS, details, header, and footer configuration screens
312 315 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
under the Admin/Skins menu.
313 316 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
314 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
- See Also
317 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+
318 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
+ ## See Also
315 319 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
316 320 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
* [Customizing the Timeline Graph](customgraph.md)
317 321 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
318 322 { copied = false; pop = false }, 1000)" :class="copied && 'copied'">Copy link Copied!
A DDED www/defcsp.md