Fossil SCM
Trying to improve the documentation for skin development. This is a work-in-progress.
Commit
2698c16b1ca1176f3d16ec5bf534cd4081b87c8480b4b720817a88100279ba0e
Parent
81b3ce3a1350eaa…
2 files changed
+17
-10
+214
-83
+17
-10
| --- skins/README.md | ||
| +++ skins/README.md | ||
| @@ -1,11 +1,16 @@ | ||
| 1 | 1 | Built-in Skins |
| 2 | 2 | ============== |
| 3 | 3 | |
| 4 | 4 | Each subdirectory under this folder describes a built-in "skin". |
| 5 | -There are four files in each subdirectory for the CSS, the "details" | |
| 6 | -file, the footer, and the header for that skin. | |
| 5 | +There are five key files in each subdirectory: | |
| 6 | + | |
| 7 | + * `css.txt` → The CSS for the skin | |
| 8 | + * `details.txt` → Skin-specific settings | |
| 9 | + * `footer.txt` → Text of the Content Footer for each page | |
| 10 | + * `header.txt` → Text of the Content Header for each page | |
| 11 | + * `js.txt` → Javascript included in the Content Footer | |
| 7 | 12 | |
| 8 | 13 | To improve an existing built-in skin, simply edit the appropriate |
| 9 | 14 | files and recompile. |
| 10 | 15 | |
| 11 | 16 | To add a new skin: |
| @@ -13,12 +18,12 @@ | ||
| 13 | 18 | 1. Create a new subdirectory under skins/. (The new directory is |
| 14 | 19 | called "skins/newskin" below but you should use a new original |
| 15 | 20 | name, of course.) |
| 16 | 21 | |
| 17 | 22 | 2. Add files skins/newskin/css.txt, skins/newskin/details.txt, |
| 18 | - skins/newskin/footer.txt and skins/newskin/header.txt. | |
| 19 | - Be sure to "fossil add" these files. | |
| 23 | + skins/newskin/footer.txt, skins/newskin/header.txt, and | |
| 24 | + skins/newskin/js.txt. Be sure to "fossil add" these files. | |
| 20 | 25 | |
| 21 | 26 | 3. Go to the src/ directory and rerun "tclsh makemake.tcl". This |
| 22 | 27 | step rebuilds the various makefiles so that they have dependencies |
| 23 | 28 | on the skin files you just installed. |
| 24 | 29 | |
| @@ -25,21 +30,23 @@ | ||
| 25 | 30 | 4. Edit the BuiltinSkin[] array near the top of the src/skins.c source |
| 26 | 31 | file so that it describes and references the "newskin" skin. |
| 27 | 32 | |
| 28 | 33 | 5. Type "make" to rebuild. |
| 29 | 34 | |
| 35 | +See the [custom skin documentation](../www/customskin.md) for more information. | |
| 36 | + | |
| 30 | 37 | Development Hints |
| 31 | 38 | ----------------- |
| 32 | 39 | |
| 33 | 40 | One way to develop a new skin is to copy the baseline files (css.txt, |
| 34 | -details.txt, footer.txt, and header.txt) into a working directory $WORKDIR | |
| 35 | -then launch Fossil with a command-line option "--skin $WORKDIR". Example: | |
| 41 | +details.txt, footer.txt, header.txt, and js.txt) into a working | |
| 42 | +directory $WORKDIR then launch Fossil with a command-line option | |
| 43 | +"--skin $WORKDIR". Example: | |
| 36 | 44 | |
| 37 | 45 | cp -r skins/default newskin |
| 38 | 46 | fossil ui --skin ./newskin |
| 39 | 47 | |
| 40 | 48 | When the argument to --skin contains one or more '/' characters, the |
| 41 | 49 | appropriate skin files are read from disk from the directory specified. |
| 42 | -So after launching fossil as shown above, you can edit the newskin/css.txt, | |
| 43 | -newskin/details.txt, newskin/footer.txt, and newskin/header.txt files using | |
| 44 | -your favorite text editor, then press Reload on your browser to see | |
| 45 | -immediate results. | |
| 50 | +So after launching fossil as shown above, you can edit the newskin/*.txt | |
| 51 | +files using your favorite text editor, then press Reload on your browser | |
| 52 | +to see immediate results. | |
| 46 | 53 |
| --- skins/README.md | |
| +++ skins/README.md | |
| @@ -1,11 +1,16 @@ | |
| 1 | Built-in Skins |
| 2 | ============== |
| 3 | |
| 4 | Each subdirectory under this folder describes a built-in "skin". |
| 5 | There are four files in each subdirectory for the CSS, the "details" |
| 6 | file, the footer, and the header for that skin. |
| 7 | |
| 8 | To improve an existing built-in skin, simply edit the appropriate |
| 9 | files and recompile. |
| 10 | |
| 11 | To add a new skin: |
| @@ -13,12 +18,12 @@ | |
| 13 | 1. Create a new subdirectory under skins/. (The new directory is |
| 14 | called "skins/newskin" below but you should use a new original |
| 15 | name, of course.) |
| 16 | |
| 17 | 2. Add files skins/newskin/css.txt, skins/newskin/details.txt, |
| 18 | skins/newskin/footer.txt and skins/newskin/header.txt. |
| 19 | Be sure to "fossil add" these files. |
| 20 | |
| 21 | 3. Go to the src/ directory and rerun "tclsh makemake.tcl". This |
| 22 | step rebuilds the various makefiles so that they have dependencies |
| 23 | on the skin files you just installed. |
| 24 | |
| @@ -25,21 +30,23 @@ | |
| 25 | 4. Edit the BuiltinSkin[] array near the top of the src/skins.c source |
| 26 | file so that it describes and references the "newskin" skin. |
| 27 | |
| 28 | 5. Type "make" to rebuild. |
| 29 | |
| 30 | Development Hints |
| 31 | ----------------- |
| 32 | |
| 33 | One way to develop a new skin is to copy the baseline files (css.txt, |
| 34 | details.txt, footer.txt, and header.txt) into a working directory $WORKDIR |
| 35 | then launch Fossil with a command-line option "--skin $WORKDIR". Example: |
| 36 | |
| 37 | cp -r skins/default newskin |
| 38 | fossil ui --skin ./newskin |
| 39 | |
| 40 | When the argument to --skin contains one or more '/' characters, the |
| 41 | appropriate skin files are read from disk from the directory specified. |
| 42 | So after launching fossil as shown above, you can edit the newskin/css.txt, |
| 43 | newskin/details.txt, newskin/footer.txt, and newskin/header.txt files using |
| 44 | your favorite text editor, then press Reload on your browser to see |
| 45 | immediate results. |
| 46 |
| --- skins/README.md | |
| +++ skins/README.md | |
| @@ -1,11 +1,16 @@ | |
| 1 | Built-in Skins |
| 2 | ============== |
| 3 | |
| 4 | Each subdirectory under this folder describes a built-in "skin". |
| 5 | There are five key files in each subdirectory: |
| 6 | |
| 7 | * `css.txt` → The CSS for the skin |
| 8 | * `details.txt` → Skin-specific settings |
| 9 | * `footer.txt` → Text of the Content Footer for each page |
| 10 | * `header.txt` → Text of the Content Header for each page |
| 11 | * `js.txt` → Javascript included in the Content Footer |
| 12 | |
| 13 | To improve an existing built-in skin, simply edit the appropriate |
| 14 | files and recompile. |
| 15 | |
| 16 | To add a new skin: |
| @@ -13,12 +18,12 @@ | |
| 18 | 1. Create a new subdirectory under skins/. (The new directory is |
| 19 | called "skins/newskin" below but you should use a new original |
| 20 | name, of course.) |
| 21 | |
| 22 | 2. Add files skins/newskin/css.txt, skins/newskin/details.txt, |
| 23 | skins/newskin/footer.txt, skins/newskin/header.txt, and |
| 24 | skins/newskin/js.txt. Be sure to "fossil add" these files. |
| 25 | |
| 26 | 3. Go to the src/ directory and rerun "tclsh makemake.tcl". This |
| 27 | step rebuilds the various makefiles so that they have dependencies |
| 28 | on the skin files you just installed. |
| 29 | |
| @@ -25,21 +30,23 @@ | |
| 30 | 4. Edit the BuiltinSkin[] array near the top of the src/skins.c source |
| 31 | file so that it describes and references the "newskin" skin. |
| 32 | |
| 33 | 5. Type "make" to rebuild. |
| 34 | |
| 35 | See the [custom skin documentation](../www/customskin.md) for more information. |
| 36 | |
| 37 | Development Hints |
| 38 | ----------------- |
| 39 | |
| 40 | One way to develop a new skin is to copy the baseline files (css.txt, |
| 41 | details.txt, footer.txt, header.txt, and js.txt) into a working |
| 42 | directory $WORKDIR then launch Fossil with a command-line option |
| 43 | "--skin $WORKDIR". Example: |
| 44 | |
| 45 | cp -r skins/default newskin |
| 46 | fossil ui --skin ./newskin |
| 47 | |
| 48 | When the argument to --skin contains one or more '/' characters, the |
| 49 | appropriate skin files are read from disk from the directory specified. |
| 50 | So after launching fossil as shown above, you can edit the newskin/*.txt |
| 51 | files using your favorite text editor, then press Reload on your browser |
| 52 | to see immediate results. |
| 53 |
+214
-83
| --- www/customskin.md | ||
| +++ www/customskin.md | ||
| @@ -1,85 +1,40 @@ | ||
| 1 | 1 | # Skinning the Fossil Web Interface |
| 2 | 2 | |
| 3 | -Every HTML page generated by Fossil has the following basic structure: | |
| 4 | - | |
| 5 | -<blockquote><table border=1 cellpadding=10><tbody> | |
| 6 | -<tr><td style='background-color:lightblue;text-align:center;'>Header</td></tr> | |
| 7 | -<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 8 | -Fossil-Generated Content</td></tr> | |
| 9 | -<tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr> | |
| 10 | -<tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr> | |
| 11 | -</tbody></table></blockquote> | |
| 12 | - | |
| 13 | -The default header looks something like this: | |
| 14 | - | |
| 15 | - <div class="header"> | |
| 16 | - <div class="title"><h1>$<project_name></h1>$<title></div> | |
| 17 | - ... top banner and menu bar ... | |
| 18 | - | |
| 19 | -The Fossil-generated content section looks like this: | |
| 20 | - | |
| 21 | - <div class="content"> | |
| 22 | - ... generated content here ... | |
| 23 | - </div> | |
| 24 | - | |
| 25 | -And the footer looks like this: | |
| 26 | - | |
| 27 | - <div class="footer"> | |
| 28 | - ... skin-specific stuff here ... | |
| 29 | - </div> | |
| 30 | - <script nonce="$<nonce>"> | |
| 31 | - <th1>styleScript</th1> | |
| 32 | - </script> | |
| 33 | - | |
| 34 | -Notice that there are no `<html>` or `<head>` elements in the header, | |
| 35 | -nor is there an `</html>` closing tag in the footer. Fossil generates | |
| 36 | -this material automatically unless it sees that you have provided your | |
| 37 | -own HTML document header within the skin’s Header section. | |
| 38 | - | |
| 39 | -This design lets most users get the benefit of Fossil’s automatic HTML | |
| 40 | -document header, which takes care of quite a few different things for | |
| 41 | -you, while still allowing you to [override if at need](#headfoot). | |
| 42 | - | |
| 43 | -When overriding the default document header, you might want to use some | |
| 44 | -of the [TH1 variables documented below](#vars) such as `$stylesheet_url` | |
| 45 | -to avoid hand-writing code that Fossil can generate for you. | |
| 46 | - | |
| 47 | -The middle "content" section comprises the bulk of most pages and | |
| 48 | -contains the actual Fossil-generated data | |
| 49 | -that the user is interested in seeing. The text of this content | |
| 50 | -section is not normally configurable. The content text can be styled | |
| 51 | -using CSS, but it is otherwise fixed. Hence it is the header, the footer, | |
| 52 | -and the CSS that determine the look of a repository. | |
| 53 | -We call the bundle of built-in CSS, header, and footer a "skin". | |
| 54 | - | |
| 3 | +The Fossil web interface comes with a pre-configured look and feel. The default | |
| 4 | +look and feel works fine in many situations. However, you may want to change | |
| 5 | +the look and feel (the "skin") of Fossil to better suite your own individual tastes. | |
| 6 | +This document provides background information to aid you in that task. | |
| 55 | 7 | |
| 56 | 8 | ## <a name="builtin"></a>Built-in Skins |
| 57 | 9 | |
| 58 | -Fossil comes with several built-in skins. The sources to these built-ins can | |
| 59 | -be found in the Fossil source tree under the skins/ folder. The skins/ | |
| 10 | +Fossil comes with multiple built-in skins. If the default skin does not | |
| 11 | +suite your tastes, perhaps one of the other built-in skins will work better. | |
| 12 | +If nothing else, the built-in skins can serve as examples or baselines that | |
| 13 | +you can use to develop your own custom skin. | |
| 14 | + | |
| 15 | +The sources to these built-ins can | |
| 16 | +be found in the Fossil source tree under the skins/ folder. The | |
| 17 | +[skins/](/dir?ci=trunk&name=skins) | |
| 60 | 18 | folder contains a separate subfolder for each built-in skin, with each |
| 61 | -subfolders holding four files, "css.txt", "details.txt", | |
| 62 | -"footer.txt", and "header.txt", | |
| 63 | -that describe the CSS, rendering options, | |
| 64 | -footer, and header for that skin, respectively. | |
| 65 | - | |
| 66 | -The skin of a repository can be changed to any of the built-in skins using | |
| 67 | -the web interface by going to the /setup_skin web page (requires Admin | |
| 68 | -privileges) and clicking the appropriate button. Or, the --skin command | |
| 69 | -line option can be used for the | |
| 70 | -[fossil ui](../../../help?cmd=ui) or | |
| 71 | -[fossil server](../../../help?cmd=server) commands to force that particular | |
| 72 | -instance of Fossil to use the specified built-in skin. | |
| 73 | - | |
| 19 | +subfolders holding at least these five files: | |
| 20 | + | |
| 21 | + * css.txt | |
| 22 | + * details.txt | |
| 23 | + * footer.txt | |
| 24 | + * header.txt | |
| 25 | + * js.txt | |
| 26 | + | |
| 27 | +Try out the built-in skins by using the --skin option on the | |
| 28 | +[fossil ui](/help?cmd=ui) or [fossil server](/help?cmd=server) commands. | |
| 74 | 29 | |
| 75 | 30 | ## <a name="sharing"></a>Sharing Skins |
| 76 | 31 | |
| 77 | 32 | The skin of a repository is not part of the versioned state and does not |
| 78 | 33 | "push" or "pull" like checked-in files. The skin is local to the |
| 79 | 34 | repository. However, skins can be shared between repositories using |
| 80 | -the [fossil config](../../../help?cmd=configuration) command. | |
| 35 | +the [fossil config](/help?cmd=configuration) command. | |
| 81 | 36 | The "fossil config push skin" command will send the local skin to a remote |
| 82 | 37 | repository and the "fossil config pull skin" command will import a skin |
| 83 | 38 | from a remote repository. The "fossil config export skin FILENAME" |
| 84 | 39 | will export the skin for a repository into a file FILENAME. This file |
| 85 | 40 | can then be imported into a different repository using the |
| @@ -95,30 +50,214 @@ | ||
| 95 | 50 | automatically change the skin when looking backwards in time, but it |
| 96 | 51 | will provide an historical record of what the skin used to be and |
| 97 | 52 | allow the historical look of the repositories to be recreated if |
| 98 | 53 | necessary. |
| 99 | 54 | |
| 100 | -When cloning a repository, the skin of new repository is initialized to | |
| 55 | +When cloning a repository, the skin of the new repository is initialized to | |
| 101 | 56 | the skin of the repository from which it was cloned. |
| 102 | 57 | |
| 58 | +# Structure Of A Fossil Web Page | |
| 59 | + | |
| 60 | +Every HTML page generated by Fossil has the same basic structure: | |
| 61 | + | |
| 62 | +<blockquote><table border=1 cellpadding=10><tbody> | |
| 63 | +<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 64 | +Fossil-Generated HTML Header</td></tr> | |
| 65 | +<tr><td style='background-color:lightblue;text-align:center;'>Content Header</td></tr> | |
| 66 | +<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 67 | +Fossil-Generated Content</td></tr> | |
| 68 | +<tr><td style='background-color:lightblue;text-align:center;'>Content Footer</td></tr> | |
| 69 | +<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 70 | +Fossil-Generated HTML Footer</td></tr> | |
| 71 | +</tbody></table></blockquote> | |
| 72 | + | |
| 73 | +The green parts are generated by Fossil. The blue parts are things that | |
| 74 | +you, the administrator, get to modify in order to customize the skin. | |
| 75 | + | |
| 76 | +Fossil *usually* (but not always - [see below](#override)) | |
| 77 | +generates the initial HTML Header section of a page. The | |
| 78 | +generated HTML Header will look something like this: | |
| 79 | + | |
| 80 | + <html> | |
| 81 | + <head> | |
| 82 | + <base href="..." /> | |
| 83 | + <meta http-equiv="Content-Security-Policy" content="...." /> | |
| 84 | + <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| 85 | + <title>....</title> | |
| 86 | + <link rel="stylesheet" href="..." type="text/css" /> | |
| 87 | + </head> | |
| 88 | + <body> | |
| 89 | + | |
| 90 | +In most cases, it is best to leave the Fossil-generated HTML Header alone. | |
| 91 | +The configurable part of the skin begins with the Content Header section which | |
| 92 | +should followign the following template: | |
| 93 | + | |
| 94 | + <div class="header"> | |
| 95 | + ... top banner and menu bar ... | |
| 96 | + </div> | |
| 97 | + | |
| 98 | +Note that `<div class="header">` and `</div>` tags must be included in the | |
| 99 | +Content Header text of the skin. In other words, you the administrator need | |
| 100 | +to supply that text as part of your skin customization. | |
| 101 | + | |
| 102 | +The Fossil-generated Content section immediately follows the Content Header. | |
| 103 | +The Content section will looks like this: | |
| 104 | + | |
| 105 | + <div class="content"> | |
| 106 | + ... Fossil-generated content here ... | |
| 107 | + </div> | |
| 108 | + | |
| 109 | +After the Content is the custom Content Footer section which should | |
| 110 | +following this template: | |
| 111 | + | |
| 112 | + <div class="footer"> | |
| 113 | + ... skin-specific stuff here ... | |
| 114 | + </div> | |
| 115 | + <script nonce="$nonce"> | |
| 116 | + <th1>styleScript</th1> | |
| 117 | + </script> | |
| 118 | + | |
| 119 | +As with the Content Header, the template elements of the Content Footer | |
| 120 | +should appear exactly as they are shown. | |
| 121 | + | |
| 122 | +Finally, Fossil always adds its own footer (unless overridden) | |
| 123 | +to close out the generated HTML: | |
| 124 | + | |
| 125 | + </body> | |
| 126 | + </html> | |
| 127 | + | |
| 128 | +## <a name="override"></a>Overriding the HTML Header and Footer | |
| 129 | + | |
| 130 | +Notice that the `<html>`, `<head>`, and opening `<body>` | |
| 131 | +elements at the beginning of the document, | |
| 132 | +and the closing `</body>` and `</html>` elements at the end are automatically | |
| 133 | +generated by Fossil. This is recommended. | |
| 134 | + | |
| 135 | +However, for maximum design flexibility, Fossil allows those elements to be | |
| 136 | +supplied as part of the configurable Content Header and Content Footer. | |
| 137 | +If the Content Header contains the text "`<body`", then Fossil assumes that | |
| 138 | +the Content Header and Content Footer will handle all of the `<html>`, | |
| 139 | +`<head>`, and `<body>` text itself, and the Fossil-generated header and | |
| 140 | +footer will be blank. | |
| 141 | + | |
| 142 | +When overriding the HTML Header in this way, you will probably want to use some | |
| 143 | +of the [TH1 variables documented below](#vars) such as `$stylesheet_url` | |
| 144 | +to avoid hand-writing code that Fossil can generate for you. | |
| 145 | + | |
| 146 | +# Designing, Debugging, and Installing A Custom Skin | |
| 147 | + | |
| 148 | +It is possible to develop a new skin from scratch. But a better and easier | |
| 149 | +approach is to use one of the existing built-in skins as a baseline and | |
| 150 | +make incremental modifications, testing after each step, to obtain the | |
| 151 | +desired result. | |
| 152 | + | |
| 153 | +The skin is controlled by five files: | |
| 154 | + | |
| 155 | +<blockquote><dl> | |
| 156 | +<dt><b>css.txt</b></dt><dd> | |
| 157 | + | |
| 158 | +<p>The css.txt file is the text of the CSS for Fossil. | |
| 159 | +Fossil might add additional CSS elements after the | |
| 160 | +the css.txt file, if it sees that the css.txt omits some | |
| 161 | +CSS components that Fossil needs. But for the most part, | |
| 162 | +the content of the css.txt is the CSS for the page.</dd> | |
| 163 | + | |
| 164 | +<dt><b>details.txt</b><dt><dd> | |
| 165 | + | |
| 166 | +<p>The details.txt file is short list of settings that control | |
| 167 | +the look and feel, mostly of the timeline. The default | |
| 168 | +details.txt file looks like this: | |
| 169 | + | |
| 170 | +<blockquote><pre> | |
| 171 | +timeline-arrowheads: 1 | |
| 172 | +timeline-circle-nodes: 1 | |
| 173 | +timeline-color-graph-lines: 1 | |
| 174 | +white-foreground: 0 | |
| 175 | +</pre></blockquote> | |
| 176 | + | |
| 177 | +The first three setings in details.txt control the appearance | |
| 178 | +of certain aspects of the timeline graph. The number on the | |
| 179 | +right is a boolean - "1" to activate the feature and "0" to | |
| 180 | +disable it. The "white-foreground:" setting should be set to | |
| 181 | +"1" if the page color has light-color text on a darker background, | |
| 182 | +and "0" if the page has dark text on a light-colored background.</dd> | |
| 183 | + | |
| 184 | +<dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> | |
| 185 | + | |
| 186 | +<p>The footer.txt and header.txt files contain the Content Footer | |
| 187 | +and Content Header respectively. Of these, the Content Header is | |
| 188 | +the most important, as it contains the markup used to generate | |
| 189 | +the banner and menu bar for each page. | |
| 190 | + | |
| 191 | +<p>Both the footer.txt and header.txt file are | |
| 192 | +[processed using TH1](#headfoot) prior to being output as | |
| 193 | +part of the overall web page.</dd> | |
| 194 | + | |
| 195 | +<dt><b>js.txt</b></dt><dd> | |
| 196 | + | |
| 197 | +<p>The js.txt file is intended to be javascript. The complete | |
| 198 | +text of this javascript is typically inserted into the Content Footer | |
| 199 | +by this part of the "footer.txt" file: | |
| 200 | + | |
| 201 | +<blockquote><pre> | |
| 202 | +<script nonce="$nonce"> | |
| 203 | + <th1>styleScript</th1> | |
| 204 | +</script> | |
| 205 | +</pre></blockquote> | |
| 206 | + | |
| 207 | +<p>The js.txt file was originally intended to insert javascript | |
| 208 | +that controls the hamburger menu. | |
| 209 | +The footer.txt file probably should contain lines like the | |
| 210 | +above, even if js.txt is empty.</dd> | |
| 211 | +</dl></blockquote> | |
| 212 | + | |
| 213 | +Developing a new skin is simply a matter of creating appropriate | |
| 214 | +versions of these five control files. | |
| 215 | + | |
| 216 | +### Skin Development Using The Web Interface | |
| 217 | + | |
| 218 | +Users with admin privileges can use the Admin/Skin configuration page | |
| 219 | +on the web interface to develop a new skin. The development of a new | |
| 220 | +skin occurs without disrupting the existing skin. So you can work on | |
| 221 | +a new skin for a Fossil instance will the existing skin is still in | |
| 222 | +active use. | |
| 223 | + | |
| 224 | +The new skins is "draft" skin. You initialize one of 9 draft skins | |
| 225 | +to either the current skin or to one of the built-in skins. Then | |
| 226 | +use forms to edit the 5 control files described above. The new | |
| 227 | +skin can be tested after each edit. Finally, once the new skin is | |
| 228 | +working as desired, the draft skin is "published" and becomes the | |
| 229 | +new live skin that most users see. | |
| 230 | + | |
| 231 | +### Skin Development Using A Local Text Editor | |
| 232 | + | |
| 233 | +An alternative approach is to copy the five control files for your | |
| 234 | +baseline skin into a temporary working directory (here called | |
| 235 | +"./newskin") and then launch the [fossil ui](/help?cmd=ui) command | |
| 236 | +with the "--skin ./newskin" option. If the argument to the --skin | |
| 237 | +option contains a "/" character, then the five control files are | |
| 238 | +read out of the directory named. You can then edit the control | |
| 239 | +files in the ./newskin folder using you favorite text editor, and | |
| 240 | +press "Reload" on your browser to see the effects. | |
| 103 | 241 | |
| 104 | 242 | ## <a name="headfoot"></a>Header and Footer Processing |
| 105 | 243 | |
| 106 | -The `header.txt` and `footer.txt` files of a skin are merely the HTML text | |
| 107 | -of the header and footer, except that before being prepended and appended to | |
| 108 | -the content, their text content is run through a | |
| 244 | +The `header.txt` and `footer.txt` control files of a skin are the HTML text | |
| 245 | +of the Contnet Header and Content Footer, except that before being inserted | |
| 246 | +into the output stream, the text is run through a | |
| 109 | 247 | [TH1 interpreter](./th1.md) that might adjust the text as follows: |
| 110 | 248 | |
| 111 | - * All text within <th1>...</th1> is elided from the | |
| 112 | - output and that text is instead run as a TH1 script. That TH1 | |
| 249 | + * All text within <th1>...</th1> is omitted from the | |
| 250 | + output and is instead run as a TH1 script. That TH1 | |
| 113 | 251 | script has the opportunity to insert new text in place of itself, |
| 114 | 252 | or to inhibit or enable the output of subsequent text. |
| 115 | 253 | |
| 116 | 254 | * Text of the form "$NAME" or "$<NAME>" is replaced with |
| 117 | 255 | the value of the TH1 variable NAME. |
| 118 | 256 | |
| 119 | -Above, we saw the first few lines of a typical Fossil skin header: | |
| 257 | +For example, first few lines of a typical Content Header will look | |
| 258 | +like this: | |
| 120 | 259 | |
| 121 | 260 | <div class="header"> |
| 122 | 261 | <div class="title"><h1>$<project_name></h1>$<title>/div> |
| 123 | 262 | |
| 124 | 263 | After variables are substituted by TH1, that will look more like this: |
| @@ -129,18 +268,10 @@ | ||
| 129 | 268 | As you can see, two TH1 variable substitutions were done. |
| 130 | 269 | |
| 131 | 270 | The same TH1 interpreter is used for both the header and the footer |
| 132 | 271 | and for all scripts contained within them both. Hence, any global |
| 133 | 272 | TH1 variables that are set by the header are available to the footer. |
| 134 | - | |
| 135 | -Fossil provides the HTML | |
| 136 | -document container tags `<html>`, `<head>`, and their inner content when | |
| 137 | -your skin’s header and footer don’t include them. This default header | |
| 138 | -declares the repository’s Content Security Policy (CSP) which is well | |
| 139 | -worth understanding, but since it is not strictly about skinning, we | |
| 140 | -cover that in [a separate document](./defcsp.md). | |
| 141 | - | |
| 142 | 273 | |
| 143 | 274 | ## <a name="menu"></a>Customizing the ≡ Hamburger Menu |
| 144 | 275 | |
| 145 | 276 | The menu bar of the default skin has an entry to open a drop-down menu with |
| 146 | 277 | additional navigation links, represented by the ≡ button (hence the name |
| 147 | 278 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -1,85 +1,40 @@ | |
| 1 | # Skinning the Fossil Web Interface |
| 2 | |
| 3 | Every HTML page generated by Fossil has the following basic structure: |
| 4 | |
| 5 | <blockquote><table border=1 cellpadding=10><tbody> |
| 6 | <tr><td style='background-color:lightblue;text-align:center;'>Header</td></tr> |
| 7 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 8 | Fossil-Generated Content</td></tr> |
| 9 | <tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr> |
| 10 | <tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr> |
| 11 | </tbody></table></blockquote> |
| 12 | |
| 13 | The default header looks something like this: |
| 14 | |
| 15 | <div class="header"> |
| 16 | <div class="title"><h1>$<project_name></h1>$<title></div> |
| 17 | ... top banner and menu bar ... |
| 18 | |
| 19 | The Fossil-generated content section looks like this: |
| 20 | |
| 21 | <div class="content"> |
| 22 | ... generated content here ... |
| 23 | </div> |
| 24 | |
| 25 | And the footer looks like this: |
| 26 | |
| 27 | <div class="footer"> |
| 28 | ... skin-specific stuff here ... |
| 29 | </div> |
| 30 | <script nonce="$<nonce>"> |
| 31 | <th1>styleScript</th1> |
| 32 | </script> |
| 33 | |
| 34 | Notice that there are no `<html>` or `<head>` elements in the header, |
| 35 | nor is there an `</html>` closing tag in the footer. Fossil generates |
| 36 | this material automatically unless it sees that you have provided your |
| 37 | own HTML document header within the skin’s Header section. |
| 38 | |
| 39 | This design lets most users get the benefit of Fossil’s automatic HTML |
| 40 | document header, which takes care of quite a few different things for |
| 41 | you, while still allowing you to [override if at need](#headfoot). |
| 42 | |
| 43 | When overriding the default document header, you might want to use some |
| 44 | of the [TH1 variables documented below](#vars) such as `$stylesheet_url` |
| 45 | to avoid hand-writing code that Fossil can generate for you. |
| 46 | |
| 47 | The middle "content" section comprises the bulk of most pages and |
| 48 | contains the actual Fossil-generated data |
| 49 | that the user is interested in seeing. The text of this content |
| 50 | section is not normally configurable. The content text can be styled |
| 51 | using CSS, but it is otherwise fixed. Hence it is the header, the footer, |
| 52 | and the CSS that determine the look of a repository. |
| 53 | We call the bundle of built-in CSS, header, and footer a "skin". |
| 54 | |
| 55 | |
| 56 | ## <a name="builtin"></a>Built-in Skins |
| 57 | |
| 58 | Fossil comes with several built-in skins. The sources to these built-ins can |
| 59 | be found in the Fossil source tree under the skins/ folder. The skins/ |
| 60 | folder contains a separate subfolder for each built-in skin, with each |
| 61 | subfolders holding four files, "css.txt", "details.txt", |
| 62 | "footer.txt", and "header.txt", |
| 63 | that describe the CSS, rendering options, |
| 64 | footer, and header for that skin, respectively. |
| 65 | |
| 66 | The skin of a repository can be changed to any of the built-in skins using |
| 67 | the web interface by going to the /setup_skin web page (requires Admin |
| 68 | privileges) and clicking the appropriate button. Or, the --skin command |
| 69 | line option can be used for the |
| 70 | [fossil ui](../../../help?cmd=ui) or |
| 71 | [fossil server](../../../help?cmd=server) commands to force that particular |
| 72 | instance of Fossil to use the specified built-in skin. |
| 73 | |
| 74 | |
| 75 | ## <a name="sharing"></a>Sharing Skins |
| 76 | |
| 77 | The skin of a repository is not part of the versioned state and does not |
| 78 | "push" or "pull" like checked-in files. The skin is local to the |
| 79 | repository. However, skins can be shared between repositories using |
| 80 | the [fossil config](../../../help?cmd=configuration) command. |
| 81 | The "fossil config push skin" command will send the local skin to a remote |
| 82 | repository and the "fossil config pull skin" command will import a skin |
| 83 | from a remote repository. The "fossil config export skin FILENAME" |
| 84 | will export the skin for a repository into a file FILENAME. This file |
| 85 | can then be imported into a different repository using the |
| @@ -95,30 +50,214 @@ | |
| 95 | automatically change the skin when looking backwards in time, but it |
| 96 | will provide an historical record of what the skin used to be and |
| 97 | allow the historical look of the repositories to be recreated if |
| 98 | necessary. |
| 99 | |
| 100 | When cloning a repository, the skin of new repository is initialized to |
| 101 | the skin of the repository from which it was cloned. |
| 102 | |
| 103 | |
| 104 | ## <a name="headfoot"></a>Header and Footer Processing |
| 105 | |
| 106 | The `header.txt` and `footer.txt` files of a skin are merely the HTML text |
| 107 | of the header and footer, except that before being prepended and appended to |
| 108 | the content, their text content is run through a |
| 109 | [TH1 interpreter](./th1.md) that might adjust the text as follows: |
| 110 | |
| 111 | * All text within <th1>...</th1> is elided from the |
| 112 | output and that text is instead run as a TH1 script. That TH1 |
| 113 | script has the opportunity to insert new text in place of itself, |
| 114 | or to inhibit or enable the output of subsequent text. |
| 115 | |
| 116 | * Text of the form "$NAME" or "$<NAME>" is replaced with |
| 117 | the value of the TH1 variable NAME. |
| 118 | |
| 119 | Above, we saw the first few lines of a typical Fossil skin header: |
| 120 | |
| 121 | <div class="header"> |
| 122 | <div class="title"><h1>$<project_name></h1>$<title>/div> |
| 123 | |
| 124 | After variables are substituted by TH1, that will look more like this: |
| @@ -129,18 +268,10 @@ | |
| 129 | As you can see, two TH1 variable substitutions were done. |
| 130 | |
| 131 | The same TH1 interpreter is used for both the header and the footer |
| 132 | and for all scripts contained within them both. Hence, any global |
| 133 | TH1 variables that are set by the header are available to the footer. |
| 134 | |
| 135 | Fossil provides the HTML |
| 136 | document container tags `<html>`, `<head>`, and their inner content when |
| 137 | your skin’s header and footer don’t include them. This default header |
| 138 | declares the repository’s Content Security Policy (CSP) which is well |
| 139 | worth understanding, but since it is not strictly about skinning, we |
| 140 | cover that in [a separate document](./defcsp.md). |
| 141 | |
| 142 | |
| 143 | ## <a name="menu"></a>Customizing the ≡ Hamburger Menu |
| 144 | |
| 145 | The menu bar of the default skin has an entry to open a drop-down menu with |
| 146 | additional navigation links, represented by the ≡ button (hence the name |
| 147 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -1,85 +1,40 @@ | |
| 1 | # Skinning the Fossil Web Interface |
| 2 | |
| 3 | The Fossil web interface comes with a pre-configured look and feel. The default |
| 4 | look and feel works fine in many situations. However, you may want to change |
| 5 | the look and feel (the "skin") of Fossil to better suite your own individual tastes. |
| 6 | This document provides background information to aid you in that task. |
| 7 | |
| 8 | ## <a name="builtin"></a>Built-in Skins |
| 9 | |
| 10 | Fossil comes with multiple built-in skins. If the default skin does not |
| 11 | suite your tastes, perhaps one of the other built-in skins will work better. |
| 12 | If nothing else, the built-in skins can serve as examples or baselines that |
| 13 | you can use to develop your own custom skin. |
| 14 | |
| 15 | The sources to these built-ins can |
| 16 | be found in the Fossil source tree under the skins/ folder. The |
| 17 | [skins/](/dir?ci=trunk&name=skins) |
| 18 | folder contains a separate subfolder for each built-in skin, with each |
| 19 | subfolders holding at least these five files: |
| 20 | |
| 21 | * css.txt |
| 22 | * details.txt |
| 23 | * footer.txt |
| 24 | * header.txt |
| 25 | * js.txt |
| 26 | |
| 27 | Try out the built-in skins by using the --skin option on the |
| 28 | [fossil ui](/help?cmd=ui) or [fossil server](/help?cmd=server) commands. |
| 29 | |
| 30 | ## <a name="sharing"></a>Sharing Skins |
| 31 | |
| 32 | The skin of a repository is not part of the versioned state and does not |
| 33 | "push" or "pull" like checked-in files. The skin is local to the |
| 34 | repository. However, skins can be shared between repositories using |
| 35 | the [fossil config](/help?cmd=configuration) command. |
| 36 | The "fossil config push skin" command will send the local skin to a remote |
| 37 | repository and the "fossil config pull skin" command will import a skin |
| 38 | from a remote repository. The "fossil config export skin FILENAME" |
| 39 | will export the skin for a repository into a file FILENAME. This file |
| 40 | can then be imported into a different repository using the |
| @@ -95,30 +50,214 @@ | |
| 50 | automatically change the skin when looking backwards in time, but it |
| 51 | will provide an historical record of what the skin used to be and |
| 52 | allow the historical look of the repositories to be recreated if |
| 53 | necessary. |
| 54 | |
| 55 | When cloning a repository, the skin of the new repository is initialized to |
| 56 | the skin of the repository from which it was cloned. |
| 57 | |
| 58 | # Structure Of A Fossil Web Page |
| 59 | |
| 60 | Every HTML page generated by Fossil has the same basic structure: |
| 61 | |
| 62 | <blockquote><table border=1 cellpadding=10><tbody> |
| 63 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 64 | Fossil-Generated HTML Header</td></tr> |
| 65 | <tr><td style='background-color:lightblue;text-align:center;'>Content Header</td></tr> |
| 66 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 67 | Fossil-Generated Content</td></tr> |
| 68 | <tr><td style='background-color:lightblue;text-align:center;'>Content Footer</td></tr> |
| 69 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 70 | Fossil-Generated HTML Footer</td></tr> |
| 71 | </tbody></table></blockquote> |
| 72 | |
| 73 | The green parts are generated by Fossil. The blue parts are things that |
| 74 | you, the administrator, get to modify in order to customize the skin. |
| 75 | |
| 76 | Fossil *usually* (but not always - [see below](#override)) |
| 77 | generates the initial HTML Header section of a page. The |
| 78 | generated HTML Header will look something like this: |
| 79 | |
| 80 | <html> |
| 81 | <head> |
| 82 | <base href="..." /> |
| 83 | <meta http-equiv="Content-Security-Policy" content="...." /> |
| 84 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 85 | <title>....</title> |
| 86 | <link rel="stylesheet" href="..." type="text/css" /> |
| 87 | </head> |
| 88 | <body> |
| 89 | |
| 90 | In most cases, it is best to leave the Fossil-generated HTML Header alone. |
| 91 | The configurable part of the skin begins with the Content Header section which |
| 92 | should followign the following template: |
| 93 | |
| 94 | <div class="header"> |
| 95 | ... top banner and menu bar ... |
| 96 | </div> |
| 97 | |
| 98 | Note that `<div class="header">` and `</div>` tags must be included in the |
| 99 | Content Header text of the skin. In other words, you the administrator need |
| 100 | to supply that text as part of your skin customization. |
| 101 | |
| 102 | The Fossil-generated Content section immediately follows the Content Header. |
| 103 | The Content section will looks like this: |
| 104 | |
| 105 | <div class="content"> |
| 106 | ... Fossil-generated content here ... |
| 107 | </div> |
| 108 | |
| 109 | After the Content is the custom Content Footer section which should |
| 110 | following this template: |
| 111 | |
| 112 | <div class="footer"> |
| 113 | ... skin-specific stuff here ... |
| 114 | </div> |
| 115 | <script nonce="$nonce"> |
| 116 | <th1>styleScript</th1> |
| 117 | </script> |
| 118 | |
| 119 | As with the Content Header, the template elements of the Content Footer |
| 120 | should appear exactly as they are shown. |
| 121 | |
| 122 | Finally, Fossil always adds its own footer (unless overridden) |
| 123 | to close out the generated HTML: |
| 124 | |
| 125 | </body> |
| 126 | </html> |
| 127 | |
| 128 | ## <a name="override"></a>Overriding the HTML Header and Footer |
| 129 | |
| 130 | Notice that the `<html>`, `<head>`, and opening `<body>` |
| 131 | elements at the beginning of the document, |
| 132 | and the closing `</body>` and `</html>` elements at the end are automatically |
| 133 | generated by Fossil. This is recommended. |
| 134 | |
| 135 | However, for maximum design flexibility, Fossil allows those elements to be |
| 136 | supplied as part of the configurable Content Header and Content Footer. |
| 137 | If the Content Header contains the text "`<body`", then Fossil assumes that |
| 138 | the Content Header and Content Footer will handle all of the `<html>`, |
| 139 | `<head>`, and `<body>` text itself, and the Fossil-generated header and |
| 140 | footer will be blank. |
| 141 | |
| 142 | When overriding the HTML Header in this way, you will probably want to use some |
| 143 | of the [TH1 variables documented below](#vars) such as `$stylesheet_url` |
| 144 | to avoid hand-writing code that Fossil can generate for you. |
| 145 | |
| 146 | # Designing, Debugging, and Installing A Custom Skin |
| 147 | |
| 148 | It is possible to develop a new skin from scratch. But a better and easier |
| 149 | approach is to use one of the existing built-in skins as a baseline and |
| 150 | make incremental modifications, testing after each step, to obtain the |
| 151 | desired result. |
| 152 | |
| 153 | The skin is controlled by five files: |
| 154 | |
| 155 | <blockquote><dl> |
| 156 | <dt><b>css.txt</b></dt><dd> |
| 157 | |
| 158 | <p>The css.txt file is the text of the CSS for Fossil. |
| 159 | Fossil might add additional CSS elements after the |
| 160 | the css.txt file, if it sees that the css.txt omits some |
| 161 | CSS components that Fossil needs. But for the most part, |
| 162 | the content of the css.txt is the CSS for the page.</dd> |
| 163 | |
| 164 | <dt><b>details.txt</b><dt><dd> |
| 165 | |
| 166 | <p>The details.txt file is short list of settings that control |
| 167 | the look and feel, mostly of the timeline. The default |
| 168 | details.txt file looks like this: |
| 169 | |
| 170 | <blockquote><pre> |
| 171 | timeline-arrowheads: 1 |
| 172 | timeline-circle-nodes: 1 |
| 173 | timeline-color-graph-lines: 1 |
| 174 | white-foreground: 0 |
| 175 | </pre></blockquote> |
| 176 | |
| 177 | The first three setings in details.txt control the appearance |
| 178 | of certain aspects of the timeline graph. The number on the |
| 179 | right is a boolean - "1" to activate the feature and "0" to |
| 180 | disable it. The "white-foreground:" setting should be set to |
| 181 | "1" if the page color has light-color text on a darker background, |
| 182 | and "0" if the page has dark text on a light-colored background.</dd> |
| 183 | |
| 184 | <dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> |
| 185 | |
| 186 | <p>The footer.txt and header.txt files contain the Content Footer |
| 187 | and Content Header respectively. Of these, the Content Header is |
| 188 | the most important, as it contains the markup used to generate |
| 189 | the banner and menu bar for each page. |
| 190 | |
| 191 | <p>Both the footer.txt and header.txt file are |
| 192 | [processed using TH1](#headfoot) prior to being output as |
| 193 | part of the overall web page.</dd> |
| 194 | |
| 195 | <dt><b>js.txt</b></dt><dd> |
| 196 | |
| 197 | <p>The js.txt file is intended to be javascript. The complete |
| 198 | text of this javascript is typically inserted into the Content Footer |
| 199 | by this part of the "footer.txt" file: |
| 200 | |
| 201 | <blockquote><pre> |
| 202 | <script nonce="$nonce"> |
| 203 | <th1>styleScript</th1> |
| 204 | </script> |
| 205 | </pre></blockquote> |
| 206 | |
| 207 | <p>The js.txt file was originally intended to insert javascript |
| 208 | that controls the hamburger menu. |
| 209 | The footer.txt file probably should contain lines like the |
| 210 | above, even if js.txt is empty.</dd> |
| 211 | </dl></blockquote> |
| 212 | |
| 213 | Developing a new skin is simply a matter of creating appropriate |
| 214 | versions of these five control files. |
| 215 | |
| 216 | ### Skin Development Using The Web Interface |
| 217 | |
| 218 | Users with admin privileges can use the Admin/Skin configuration page |
| 219 | on the web interface to develop a new skin. The development of a new |
| 220 | skin occurs without disrupting the existing skin. So you can work on |
| 221 | a new skin for a Fossil instance will the existing skin is still in |
| 222 | active use. |
| 223 | |
| 224 | The new skins is "draft" skin. You initialize one of 9 draft skins |
| 225 | to either the current skin or to one of the built-in skins. Then |
| 226 | use forms to edit the 5 control files described above. The new |
| 227 | skin can be tested after each edit. Finally, once the new skin is |
| 228 | working as desired, the draft skin is "published" and becomes the |
| 229 | new live skin that most users see. |
| 230 | |
| 231 | ### Skin Development Using A Local Text Editor |
| 232 | |
| 233 | An alternative approach is to copy the five control files for your |
| 234 | baseline skin into a temporary working directory (here called |
| 235 | "./newskin") and then launch the [fossil ui](/help?cmd=ui) command |
| 236 | with the "--skin ./newskin" option. If the argument to the --skin |
| 237 | option contains a "/" character, then the five control files are |
| 238 | read out of the directory named. You can then edit the control |
| 239 | files in the ./newskin folder using you favorite text editor, and |
| 240 | press "Reload" on your browser to see the effects. |
| 241 | |
| 242 | ## <a name="headfoot"></a>Header and Footer Processing |
| 243 | |
| 244 | The `header.txt` and `footer.txt` control files of a skin are the HTML text |
| 245 | of the Contnet Header and Content Footer, except that before being inserted |
| 246 | into the output stream, the text is run through a |
| 247 | [TH1 interpreter](./th1.md) that might adjust the text as follows: |
| 248 | |
| 249 | * All text within <th1>...</th1> is omitted from the |
| 250 | output and is instead run as a TH1 script. That TH1 |
| 251 | script has the opportunity to insert new text in place of itself, |
| 252 | or to inhibit or enable the output of subsequent text. |
| 253 | |
| 254 | * Text of the form "$NAME" or "$<NAME>" is replaced with |
| 255 | the value of the TH1 variable NAME. |
| 256 | |
| 257 | For example, first few lines of a typical Content Header will look |
| 258 | like this: |
| 259 | |
| 260 | <div class="header"> |
| 261 | <div class="title"><h1>$<project_name></h1>$<title>/div> |
| 262 | |
| 263 | After variables are substituted by TH1, that will look more like this: |
| @@ -129,18 +268,10 @@ | |
| 268 | As you can see, two TH1 variable substitutions were done. |
| 269 | |
| 270 | The same TH1 interpreter is used for both the header and the footer |
| 271 | and for all scripts contained within them both. Hence, any global |
| 272 | TH1 variables that are set by the header are available to the footer. |
| 273 | |
| 274 | ## <a name="menu"></a>Customizing the ≡ Hamburger Menu |
| 275 | |
| 276 | The menu bar of the default skin has an entry to open a drop-down menu with |
| 277 | additional navigation links, represented by the ≡ button (hence the name |
| 278 |