Fossil SCM
Update the customskin.md document to explain the latest practices.
Commit
48a4be5058d89792fae9ae348d2d9546dbf3e75e2d8664d46e6ddb2e21f2bf11
Parent
557f51b34bc6cdd…
1 file changed
+68
-24
+68
-24
| --- www/customskin.md | ||
| +++ www/customskin.md | ||
| @@ -7,11 +7,11 @@ | ||
| 7 | 7 | |
| 8 | 8 | ## <a name="builtin"></a>Built-in Skins |
| 9 | 9 | |
| 10 | 10 | Fossil comes with multiple built-in skins. If the default skin does not |
| 11 | 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 | |
| 12 | +If nothing else, the built-in skins can serve as examples or templates that | |
| 13 | 13 | you can use to develop your own custom skin. |
| 14 | 14 | |
| 15 | 15 | The sources to these built-ins can |
| 16 | 16 | be found in the Fossil source tree under the skins/ folder. The |
| 17 | 17 | [skins/](/dir?ci=trunk&name=skins) |
| @@ -125,13 +125,10 @@ | ||
| 125 | 125 | follow this template: |
| 126 | 126 | |
| 127 | 127 | <div class="footer"> |
| 128 | 128 | ... skin-specific stuff here ... |
| 129 | 129 | </div> |
| 130 | - <script nonce="$nonce"> | |
| 131 | - <th1>styleScript</th1> | |
| 132 | - </script> | |
| 133 | 130 | |
| 134 | 131 | As with the Content Header, the template elements of the Content Footer |
| 135 | 132 | should appear exactly as they are shown. |
| 136 | 133 | |
| 137 | 134 | Finally, Fossil always adds its own footer (unless overridden) |
| @@ -181,11 +178,14 @@ | ||
| 181 | 178 | <p>The details.txt file is short list of settings that control |
| 182 | 179 | the look and feel, mostly of the timeline. The default |
| 183 | 180 | details.txt file looks like this: |
| 184 | 181 | |
| 185 | 182 | <blockquote><pre> |
| 183 | +pikchr-background: "" | |
| 184 | +pikchr-fontscale: "" | |
| 186 | 185 | pikchr-foreground: "" |
| 186 | +pikchr-scale: "" | |
| 187 | 187 | timeline-arrowheads: 1 |
| 188 | 188 | timeline-circle-nodes: 1 |
| 189 | 189 | timeline-color-graph-lines: 1 |
| 190 | 190 | white-foreground: 0 |
| 191 | 191 | </pre></blockquote> |
| @@ -199,11 +199,16 @@ | ||
| 199 | 199 | <p> |
| 200 | 200 | If the "pikchr-foreground" setting (added in Fossil 2.14) |
| 201 | 201 | is defined and is not an empty string then it specifies a |
| 202 | 202 | foreground color to use for [pikchr diagrams](./pikchr.md). The |
| 203 | 203 | default pikchr foreground color is black, or white if the |
| 204 | -"white-foreground" boolean is set. | |
| 204 | +"white-foreground" boolean is set. The "pikchr-background" | |
| 205 | +settings does the same for the pikchr diagram background color. | |
| 206 | +If the "pikchr-fontscale" and "pikchr-scale" values are not | |
| 207 | +empty strings, then they should be floating point values (close | |
| 208 | +to 1.0) that specify relative scaling of the fonts in pikchr | |
| 209 | +diagrams and other elements of the diagrams, respectively. | |
| 205 | 210 | </dd> |
| 206 | 211 | |
| 207 | 212 | <dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> |
| 208 | 213 | |
| 209 | 214 | <p>The footer.txt and header.txt files contain the Content Footer |
| @@ -215,24 +220,47 @@ | ||
| 215 | 220 | [processed using TH1](#headfoot) prior to being output as |
| 216 | 221 | part of the overall web page.</dd> |
| 217 | 222 | |
| 218 | 223 | <dt><b>js.txt</b></dt><dd> |
| 219 | 224 | |
| 220 | -<p>The js.txt file is intended to be javascript. The complete | |
| 221 | -text of this javascript is typically inserted into the Content Footer | |
| 222 | -by this part of the "footer.txt" file: | |
| 225 | +<p>The js.txt file is optional. It is intended to be javascript. | |
| 226 | +The complete text of this javascript is might be inserted into | |
| 227 | +the Content Footer, after being processed using TH1, using | |
| 228 | +code like the following in the "footer.txt" file: | |
| 223 | 229 | |
| 224 | 230 | <blockquote><pre> |
| 225 | 231 | <script nonce="$nonce"> |
| 226 | 232 | <th1>styleScript</th1> |
| 227 | 233 | </script> |
| 228 | 234 | </pre></blockquote> |
| 229 | 235 | |
| 230 | -<p>The js.txt file was originally intended to insert javascript | |
| 231 | -that controls the hamburger menu. | |
| 232 | -The footer.txt file probably should contain lines like the | |
| 233 | -above, even if js.txt is empty.</dd> | |
| 236 | +<p>The js.txt file was originally used to insert javascript | |
| 237 | +that controls the hamburger menu in the default skin. More | |
| 238 | +recently, the javascript for the hamburger menu was moved into | |
| 239 | +a separate built-in file. Skins that use the hamburger menu | |
| 240 | +typically cause the javascript to be loaded by including the | |
| 241 | +following TH1 code in the "header.txt" file: | |
| 242 | + | |
| 243 | +<blockquote><pre> | |
| 244 | +<th1>builtin_request_js hbmenu.js</th1> | |
| 245 | +</pre></blockquote> | |
| 246 | + | |
| 247 | +The difference between styleScript and builtin_request_js | |
| 248 | +is that the styleScript command interprets the file | |
| 249 | +using TH1 and injects the content directly into the output | |
| 250 | +stream, whereas the builtin_request_js command inserts the | |
| 251 | +javascript verbatim and does so at some unspecified future time | |
| 252 | +down inside the Fossil-generated footer. The built-in skins | |
| 253 | +of Fossil originally used the styleScript command to load | |
| 254 | +the hamburger menu javascript, but as of version 2.15 switched | |
| 255 | +to using the builtin_request_js method. You can use either | |
| 256 | +approach in custom skins that you right yourself. | |
| 257 | + | |
| 258 | +Note that the "js.txt" file is *not* automatically inserted into | |
| 259 | +the generate HTML for a page. You, the skin designer, must | |
| 260 | +cause the javascript to be inserted by issuing appropriate | |
| 261 | +TH1 commands in the "header.txt" or "footer.txt" files.</dd> | |
| 234 | 262 | </dl></blockquote> |
| 235 | 263 | |
| 236 | 264 | Developing a new skin is simply a matter of creating appropriate |
| 237 | 265 | versions of these five control files. |
| 238 | 266 | |
| @@ -260,10 +288,21 @@ | ||
| 260 | 288 | option contains a "/" character, then the five control files are |
| 261 | 289 | read out of the directory named. You can then edit the control |
| 262 | 290 | files in the ./newskin folder using you favorite text editor, and |
| 263 | 291 | press "Reload" on your browser to see the effects. |
| 264 | 292 | |
| 293 | +### Disabling The Web Browser Cache During Development | |
| 294 | + | |
| 295 | +Fossil is aggressive about asking the web browser to cache | |
| 296 | +resources. While developing a new skin, it is often helpful to | |
| 297 | +put your web browser into developer mode and disable the cache. | |
| 298 | +If you fail to do this, then you might make some change to your skin | |
| 299 | +under development and press "Reload" only to find that the display | |
| 300 | +did not change. After you have finished work your skin, the | |
| 301 | +caches should synchronize with your new design and you can reactivate | |
| 302 | +your web browser's cache and take it out of developer mode. | |
| 303 | + | |
| 265 | 304 | ## <a name="headfoot"></a>Header and Footer Processing |
| 266 | 305 | |
| 267 | 306 | The `header.txt` and `footer.txt` control files of a skin are the HTML text |
| 268 | 307 | of the Content Header and Content Footer, except that before being inserted |
| 269 | 308 | into the output stream, the text is run through a |
| @@ -297,31 +336,36 @@ | ||
| 297 | 336 | ## <a name="menu"></a>Customizing the ≡ Hamburger Menu |
| 298 | 337 | |
| 299 | 338 | The menu bar of the default skin has an entry to open a drop-down menu with |
| 300 | 339 | additional navigation links, represented by the ≡ button (hence the name |
| 301 | 340 | "hamburger menu"). The Javascript logic to open and close the hamburger menu |
| 302 | -when the button is clicked is contained in the optional Javascript part (js.txt) | |
| 303 | -of the default skin. Out of the box, the drop-down menu shows the [Site | |
| 304 | -Map](../../../sitemap), loaded by an AJAX request prior to the first display. | |
| 341 | +when the button is clicked is usually handled by a script named | |
| 342 | +"hbmenu.js" that is one of the [built-in resource files](/test-builtin-list) | |
| 343 | +that are part of Fossil. | |
| 305 | 344 | |
| 306 | 345 | The ≡ button for the hamburger menu is added to the menu bar by the following |
| 307 | -TH1 command in the default skin header.txt, right before the menu bar links: | |
| 346 | +TH1 commands in the `header.txt` file, right before the menu bar links: | |
| 308 | 347 | |
| 309 | - html "<a id='hbbtn' href='#'>☰</a>" | |
| 348 | + html "<a id='hbbtn' href='$home/sitemap'>☰</a>" | |
| 349 | + builtin_request_js hbmenu.js | |
| 310 | 350 | |
| 311 | 351 | The hamburger button can be repositioned between the other menu links (but the |
| 312 | 352 | drop-down menu is always left-aligned with the menu bar), or it can be removed |
| 313 | -by deleting the above statement (the Javascript logic detects this case and | |
| 314 | -remains idle, so it's not necessary to modify the default skin js.txt). | |
| 353 | +by deleting the above statements. The "html" statement inserts the appropriate | |
| 354 | +`<a>` for the hamburger menu button (some skins require something slightly | |
| 355 | +different - for example the ardoise skins wants "`<li><a>`"). The | |
| 356 | +"builtin_request_js hbmenu.js" asks Fossil to include the "hbmenu.js" | |
| 357 | +resource files in the Fossil-generated footer. | |
| 315 | 358 | |
| 316 | -The following empty element at the bottom of the default skin header.txt serves | |
| 317 | -as the panel to hold the drop-down menu elements: | |
| 359 | +The hbmenu.js script requires | |
| 360 | +the following `<div>` element somewhere in your header, in which to build | |
| 361 | +the hamburger menu. | |
| 318 | 362 | |
| 319 | 363 | <div id='hbdrop'></div> |
| 320 | 364 | |
| 321 | 365 | Out of the box, the contents of the panel is populated with the [Site |
| 322 | -Map](../../../sitemap), but only if the panel does not already contain any HTML | |
| 366 | +Map](/sitemap), but only if the panel does not already contain any HTML | |
| 323 | 367 | elements (that is, not just comments, plain text or non-presentational white |
| 324 | 368 | space). So the hamburger menu can be customized by replacing the empty `<div |
| 325 | 369 | id='hbdrop'></div>` element with a menu structure knitted according to the |
| 326 | 370 | following template: |
| 327 | 371 | |
| @@ -447,16 +491,16 @@ | ||
| 447 | 491 | CSS, footer, and header editing screens under the Admin menu will |
| 448 | 492 | work just as well. The important point is that the three files |
| 449 | 493 | be named exactly "css.txt", "footer.txt", and "header.txt" and that |
| 450 | 494 | they all be in the same directory. |
| 451 | 495 | |
| 452 | - 2. Run the [fossil ui](../../../help?cmd=ui) command with an extra | |
| 496 | + 2. Run the [fossil ui](/help?cmd=ui) command with an extra | |
| 453 | 497 | option "--skin SKINDIR" where SKINDIR is the name of the directory |
| 454 | 498 | in which the three txt files were stored in step 1. This will bring |
| 455 | 499 | up the Fossil website using the tree files in SKINDIR. |
| 456 | 500 | |
| 457 | - 3. Edit the four txt files in SKINDIR. After making each small change, | |
| 501 | + 3. Edit the *.txt files in SKINDIR. After making each small change, | |
| 458 | 502 | press Reload on the web browser to see the effect of that change. |
| 459 | 503 | Iterate until the desired look is achieved. |
| 460 | 504 | |
| 461 | 505 | 4. Copy/paste the resulting css.txt, details.txt, |
| 462 | 506 | header.txt, and footer.txt files |
| 463 | 507 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -7,11 +7,11 @@ | |
| 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) |
| @@ -125,13 +125,10 @@ | |
| 125 | follow this template: |
| 126 | |
| 127 | <div class="footer"> |
| 128 | ... skin-specific stuff here ... |
| 129 | </div> |
| 130 | <script nonce="$nonce"> |
| 131 | <th1>styleScript</th1> |
| 132 | </script> |
| 133 | |
| 134 | As with the Content Header, the template elements of the Content Footer |
| 135 | should appear exactly as they are shown. |
| 136 | |
| 137 | Finally, Fossil always adds its own footer (unless overridden) |
| @@ -181,11 +178,14 @@ | |
| 181 | <p>The details.txt file is short list of settings that control |
| 182 | the look and feel, mostly of the timeline. The default |
| 183 | details.txt file looks like this: |
| 184 | |
| 185 | <blockquote><pre> |
| 186 | pikchr-foreground: "" |
| 187 | timeline-arrowheads: 1 |
| 188 | timeline-circle-nodes: 1 |
| 189 | timeline-color-graph-lines: 1 |
| 190 | white-foreground: 0 |
| 191 | </pre></blockquote> |
| @@ -199,11 +199,16 @@ | |
| 199 | <p> |
| 200 | If the "pikchr-foreground" setting (added in Fossil 2.14) |
| 201 | is defined and is not an empty string then it specifies a |
| 202 | foreground color to use for [pikchr diagrams](./pikchr.md). The |
| 203 | default pikchr foreground color is black, or white if the |
| 204 | "white-foreground" boolean is set. |
| 205 | </dd> |
| 206 | |
| 207 | <dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> |
| 208 | |
| 209 | <p>The footer.txt and header.txt files contain the Content Footer |
| @@ -215,24 +220,47 @@ | |
| 215 | [processed using TH1](#headfoot) prior to being output as |
| 216 | part of the overall web page.</dd> |
| 217 | |
| 218 | <dt><b>js.txt</b></dt><dd> |
| 219 | |
| 220 | <p>The js.txt file is intended to be javascript. The complete |
| 221 | text of this javascript is typically inserted into the Content Footer |
| 222 | by this part of the "footer.txt" file: |
| 223 | |
| 224 | <blockquote><pre> |
| 225 | <script nonce="$nonce"> |
| 226 | <th1>styleScript</th1> |
| 227 | </script> |
| 228 | </pre></blockquote> |
| 229 | |
| 230 | <p>The js.txt file was originally intended to insert javascript |
| 231 | that controls the hamburger menu. |
| 232 | The footer.txt file probably should contain lines like the |
| 233 | above, even if js.txt is empty.</dd> |
| 234 | </dl></blockquote> |
| 235 | |
| 236 | Developing a new skin is simply a matter of creating appropriate |
| 237 | versions of these five control files. |
| 238 | |
| @@ -260,10 +288,21 @@ | |
| 260 | option contains a "/" character, then the five control files are |
| 261 | read out of the directory named. You can then edit the control |
| 262 | files in the ./newskin folder using you favorite text editor, and |
| 263 | press "Reload" on your browser to see the effects. |
| 264 | |
| 265 | ## <a name="headfoot"></a>Header and Footer Processing |
| 266 | |
| 267 | The `header.txt` and `footer.txt` control files of a skin are the HTML text |
| 268 | of the Content Header and Content Footer, except that before being inserted |
| 269 | into the output stream, the text is run through a |
| @@ -297,31 +336,36 @@ | |
| 297 | ## <a name="menu"></a>Customizing the ≡ Hamburger Menu |
| 298 | |
| 299 | The menu bar of the default skin has an entry to open a drop-down menu with |
| 300 | additional navigation links, represented by the ≡ button (hence the name |
| 301 | "hamburger menu"). The Javascript logic to open and close the hamburger menu |
| 302 | when the button is clicked is contained in the optional Javascript part (js.txt) |
| 303 | of the default skin. Out of the box, the drop-down menu shows the [Site |
| 304 | Map](../../../sitemap), loaded by an AJAX request prior to the first display. |
| 305 | |
| 306 | The ≡ button for the hamburger menu is added to the menu bar by the following |
| 307 | TH1 command in the default skin header.txt, right before the menu bar links: |
| 308 | |
| 309 | html "<a id='hbbtn' href='#'>☰</a>" |
| 310 | |
| 311 | The hamburger button can be repositioned between the other menu links (but the |
| 312 | drop-down menu is always left-aligned with the menu bar), or it can be removed |
| 313 | by deleting the above statement (the Javascript logic detects this case and |
| 314 | remains idle, so it's not necessary to modify the default skin js.txt). |
| 315 | |
| 316 | The following empty element at the bottom of the default skin header.txt serves |
| 317 | as the panel to hold the drop-down menu elements: |
| 318 | |
| 319 | <div id='hbdrop'></div> |
| 320 | |
| 321 | Out of the box, the contents of the panel is populated with the [Site |
| 322 | Map](../../../sitemap), but only if the panel does not already contain any HTML |
| 323 | elements (that is, not just comments, plain text or non-presentational white |
| 324 | space). So the hamburger menu can be customized by replacing the empty `<div |
| 325 | id='hbdrop'></div>` element with a menu structure knitted according to the |
| 326 | following template: |
| 327 | |
| @@ -447,16 +491,16 @@ | |
| 447 | CSS, footer, and header editing screens under the Admin menu will |
| 448 | work just as well. The important point is that the three files |
| 449 | be named exactly "css.txt", "footer.txt", and "header.txt" and that |
| 450 | they all be in the same directory. |
| 451 | |
| 452 | 2. Run the [fossil ui](../../../help?cmd=ui) command with an extra |
| 453 | option "--skin SKINDIR" where SKINDIR is the name of the directory |
| 454 | in which the three txt files were stored in step 1. This will bring |
| 455 | up the Fossil website using the tree files in SKINDIR. |
| 456 | |
| 457 | 3. Edit the four txt files in SKINDIR. After making each small change, |
| 458 | press Reload on the web browser to see the effect of that change. |
| 459 | Iterate until the desired look is achieved. |
| 460 | |
| 461 | 4. Copy/paste the resulting css.txt, details.txt, |
| 462 | header.txt, and footer.txt files |
| 463 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -7,11 +7,11 @@ | |
| 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 templates 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) |
| @@ -125,13 +125,10 @@ | |
| 125 | follow this template: |
| 126 | |
| 127 | <div class="footer"> |
| 128 | ... skin-specific stuff here ... |
| 129 | </div> |
| 130 | |
| 131 | As with the Content Header, the template elements of the Content Footer |
| 132 | should appear exactly as they are shown. |
| 133 | |
| 134 | Finally, Fossil always adds its own footer (unless overridden) |
| @@ -181,11 +178,14 @@ | |
| 178 | <p>The details.txt file is short list of settings that control |
| 179 | the look and feel, mostly of the timeline. The default |
| 180 | details.txt file looks like this: |
| 181 | |
| 182 | <blockquote><pre> |
| 183 | pikchr-background: "" |
| 184 | pikchr-fontscale: "" |
| 185 | pikchr-foreground: "" |
| 186 | pikchr-scale: "" |
| 187 | timeline-arrowheads: 1 |
| 188 | timeline-circle-nodes: 1 |
| 189 | timeline-color-graph-lines: 1 |
| 190 | white-foreground: 0 |
| 191 | </pre></blockquote> |
| @@ -199,11 +199,16 @@ | |
| 199 | <p> |
| 200 | If the "pikchr-foreground" setting (added in Fossil 2.14) |
| 201 | is defined and is not an empty string then it specifies a |
| 202 | foreground color to use for [pikchr diagrams](./pikchr.md). The |
| 203 | default pikchr foreground color is black, or white if the |
| 204 | "white-foreground" boolean is set. The "pikchr-background" |
| 205 | settings does the same for the pikchr diagram background color. |
| 206 | If the "pikchr-fontscale" and "pikchr-scale" values are not |
| 207 | empty strings, then they should be floating point values (close |
| 208 | to 1.0) that specify relative scaling of the fonts in pikchr |
| 209 | diagrams and other elements of the diagrams, respectively. |
| 210 | </dd> |
| 211 | |
| 212 | <dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> |
| 213 | |
| 214 | <p>The footer.txt and header.txt files contain the Content Footer |
| @@ -215,24 +220,47 @@ | |
| 220 | [processed using TH1](#headfoot) prior to being output as |
| 221 | part of the overall web page.</dd> |
| 222 | |
| 223 | <dt><b>js.txt</b></dt><dd> |
| 224 | |
| 225 | <p>The js.txt file is optional. It is intended to be javascript. |
| 226 | The complete text of this javascript is might be inserted into |
| 227 | the Content Footer, after being processed using TH1, using |
| 228 | code like the following in the "footer.txt" file: |
| 229 | |
| 230 | <blockquote><pre> |
| 231 | <script nonce="$nonce"> |
| 232 | <th1>styleScript</th1> |
| 233 | </script> |
| 234 | </pre></blockquote> |
| 235 | |
| 236 | <p>The js.txt file was originally used to insert javascript |
| 237 | that controls the hamburger menu in the default skin. More |
| 238 | recently, the javascript for the hamburger menu was moved into |
| 239 | a separate built-in file. Skins that use the hamburger menu |
| 240 | typically cause the javascript to be loaded by including the |
| 241 | following TH1 code in the "header.txt" file: |
| 242 | |
| 243 | <blockquote><pre> |
| 244 | <th1>builtin_request_js hbmenu.js</th1> |
| 245 | </pre></blockquote> |
| 246 | |
| 247 | The difference between styleScript and builtin_request_js |
| 248 | is that the styleScript command interprets the file |
| 249 | using TH1 and injects the content directly into the output |
| 250 | stream, whereas the builtin_request_js command inserts the |
| 251 | javascript verbatim and does so at some unspecified future time |
| 252 | down inside the Fossil-generated footer. The built-in skins |
| 253 | of Fossil originally used the styleScript command to load |
| 254 | the hamburger menu javascript, but as of version 2.15 switched |
| 255 | to using the builtin_request_js method. You can use either |
| 256 | approach in custom skins that you right yourself. |
| 257 | |
| 258 | Note that the "js.txt" file is *not* automatically inserted into |
| 259 | the generate HTML for a page. You, the skin designer, must |
| 260 | cause the javascript to be inserted by issuing appropriate |
| 261 | TH1 commands in the "header.txt" or "footer.txt" files.</dd> |
| 262 | </dl></blockquote> |
| 263 | |
| 264 | Developing a new skin is simply a matter of creating appropriate |
| 265 | versions of these five control files. |
| 266 | |
| @@ -260,10 +288,21 @@ | |
| 288 | option contains a "/" character, then the five control files are |
| 289 | read out of the directory named. You can then edit the control |
| 290 | files in the ./newskin folder using you favorite text editor, and |
| 291 | press "Reload" on your browser to see the effects. |
| 292 | |
| 293 | ### Disabling The Web Browser Cache During Development |
| 294 | |
| 295 | Fossil is aggressive about asking the web browser to cache |
| 296 | resources. While developing a new skin, it is often helpful to |
| 297 | put your web browser into developer mode and disable the cache. |
| 298 | If you fail to do this, then you might make some change to your skin |
| 299 | under development and press "Reload" only to find that the display |
| 300 | did not change. After you have finished work your skin, the |
| 301 | caches should synchronize with your new design and you can reactivate |
| 302 | your web browser's cache and take it out of developer mode. |
| 303 | |
| 304 | ## <a name="headfoot"></a>Header and Footer Processing |
| 305 | |
| 306 | The `header.txt` and `footer.txt` control files of a skin are the HTML text |
| 307 | of the Content Header and Content Footer, except that before being inserted |
| 308 | into the output stream, the text is run through a |
| @@ -297,31 +336,36 @@ | |
| 336 | ## <a name="menu"></a>Customizing the ≡ Hamburger Menu |
| 337 | |
| 338 | The menu bar of the default skin has an entry to open a drop-down menu with |
| 339 | additional navigation links, represented by the ≡ button (hence the name |
| 340 | "hamburger menu"). The Javascript logic to open and close the hamburger menu |
| 341 | when the button is clicked is usually handled by a script named |
| 342 | "hbmenu.js" that is one of the [built-in resource files](/test-builtin-list) |
| 343 | that are part of Fossil. |
| 344 | |
| 345 | The ≡ button for the hamburger menu is added to the menu bar by the following |
| 346 | TH1 commands in the `header.txt` file, right before the menu bar links: |
| 347 | |
| 348 | html "<a id='hbbtn' href='$home/sitemap'>☰</a>" |
| 349 | builtin_request_js hbmenu.js |
| 350 | |
| 351 | The hamburger button can be repositioned between the other menu links (but the |
| 352 | drop-down menu is always left-aligned with the menu bar), or it can be removed |
| 353 | by deleting the above statements. The "html" statement inserts the appropriate |
| 354 | `<a>` for the hamburger menu button (some skins require something slightly |
| 355 | different - for example the ardoise skins wants "`<li><a>`"). The |
| 356 | "builtin_request_js hbmenu.js" asks Fossil to include the "hbmenu.js" |
| 357 | resource files in the Fossil-generated footer. |
| 358 | |
| 359 | The hbmenu.js script requires |
| 360 | the following `<div>` element somewhere in your header, in which to build |
| 361 | the hamburger menu. |
| 362 | |
| 363 | <div id='hbdrop'></div> |
| 364 | |
| 365 | Out of the box, the contents of the panel is populated with the [Site |
| 366 | Map](/sitemap), but only if the panel does not already contain any HTML |
| 367 | elements (that is, not just comments, plain text or non-presentational white |
| 368 | space). So the hamburger menu can be customized by replacing the empty `<div |
| 369 | id='hbdrop'></div>` element with a menu structure knitted according to the |
| 370 | following template: |
| 371 | |
| @@ -447,16 +491,16 @@ | |
| 491 | CSS, footer, and header editing screens under the Admin menu will |
| 492 | work just as well. The important point is that the three files |
| 493 | be named exactly "css.txt", "footer.txt", and "header.txt" and that |
| 494 | they all be in the same directory. |
| 495 | |
| 496 | 2. Run the [fossil ui](/help?cmd=ui) command with an extra |
| 497 | option "--skin SKINDIR" where SKINDIR is the name of the directory |
| 498 | in which the three txt files were stored in step 1. This will bring |
| 499 | up the Fossil website using the tree files in SKINDIR. |
| 500 | |
| 501 | 3. Edit the *.txt files in SKINDIR. After making each small change, |
| 502 | press Reload on the web browser to see the effect of that change. |
| 503 | Iterate until the desired look is achieved. |
| 504 | |
| 505 | 4. Copy/paste the resulting css.txt, details.txt, |
| 506 | header.txt, and footer.txt files |
| 507 |