Prior to Fossil 2.24, we used +generic `

` elements to mark up these sections of the header, but we +switched to these semantic tag names to give browser accessibility +features more freedom to do intelligent things with the page content. +Those who made custom skins based on the old way of doing things will +need to track this change when upgrading, else the corresponding CSS +will mistarget the page header elements. Also, if you’re using Fossil’s +chat feature, failing to track this change will cause it to miscalculate +the message area size, resulting in double scrollbars. Simply diffing +your custom header in the skin editor against the stock version should +be sufficient to show what you need to change.

+ + +

+ ... +

+ + + +See the stock skins’ headers for ideas of what to put in place of the +ellipses. + +The Fossil-generated Content section immediately follows this Header. +It will look like this: + +

+ ... Fossil-generated content here ... +

+ +After the Content is the custom Skin Footer section which should +follow this template: + + + +As with the `

` change called out above, this, too, is a breaking +change in Fossil 2.24. + +Finally, Fossil always adds its own footer (unless overridden) +to close out the generated HTML: + + + + +## Changing the Main Menu Contents + +The actual text content of the skin’s main menu is not +part of the skin proper if you’re using one of the stock skins. +If you look at the Header section of the skin, you’ll find a +`

` element whose contents are set by a short +[TH1](./th1.md) script from the contents of the **Main Menu** section of +the Setup → Configuration screen. + +This feature allows the main menu contents to stay the same across +different skins, so you no longer have to reapply menu customizations +when trying different skins. + +See the [`capexpr`](./th1.md#capexpr) section of the TH1 docs for help +on interpreting the default contents of this block. + + +## Overriding the HTML Header and Footer + +Notice that the ``, ``, and opening `` +elements at the beginning of the document, +and the closing `` and `` elements at the end are automatically +generated by Fossil. This is recommended. + +However, for maximum design flexibility, Fossil allows those elements to be +supplied as part of the configurable Skin Header and Skin Footer. +If the Skin Header contains the text "``, +``, and `` text itself, and the Fossil-generated header and +footer will be blank. + +When overriding the HTML Header in this way, you will probably want to use some +of the [TH1 variables documented below](#vars) such as `$stylesheet_url` +to avoid hand-writing code that Fossil can generate for you. + +# Designing, Debugging, and Installing A Custom Skin + +It is possible to develop a new skin from scratch. But a better and easier +approach is to use one of the existing built-in skins as a baseline and +make incremental modifications, testing after each step, to obtain the +desired result. + +The skin is controlled by five files: + +

css.txt

The css.txt file is the text of the CSS for Fossil. +Fossil might add additional CSS elements after +the css.txt file, if it sees that the css.txt omits some +CSS components that Fossil needs. But for the most part, +the content of the css.txt is the CSS for the page.

details.txt

+ +

The details.txt file is short list of settings that control +the look and feel, mostly of the timeline. The default +details.txt file looks like this: + +

+pikchr-background:          ""
+pikchr-fontscale:           ""
+pikchr-foreground:          ""
+pikchr-scale:               ""
+timeline-arrowheads:        1
+timeline-circle-nodes:      1
+timeline-color-graph-lines: 1
+white-foreground:           0
+

+ +The three "timeline-" settings in details.txt control the appearance +of certain aspects of the timeline graph. The number on the +right is a boolean - "1" to activate the feature and "0" to +disable it. The "white-foreground:" setting should be set to +"1" if the page color has light-color text on a darker background, +and "0" if the page has dark text on a light-colored background. + +If the "pikchr-foreground" setting +is defined and is not an empty string then it specifies a +foreground color to use for [pikchr diagrams](./pikchr.md). The +default pikchr foreground color is black, or white if the +"white-foreground" boolean is set. The "pikchr-background" +settings does the same for the pikchr diagram background color. +If the "pikchr-fontscale" and "pikchr-scale" values are not +empty strings, then they should be floating point values (close +to 1.0) that specify relative scaling of the fonts in pikchr +diagrams and other elements of the diagrams, respectively. +

footer.txt and header.txt

The footer.txt and header.txt files contain the Skin Footer +and Skin Header respectively. Of these, the Skin Header is +the most important, as it contains the markup used to generate +the banner and menu bar for each page. + +Both the footer.txt and header.txt file are +[processed using TH1](#headfoot) prior to being output as +part of the overall web page.

js.txt

The js.txt file is optional. It is intended to be javascript. +The complete text of this javascript might be inserted into +the Skin Footer, after being processed using TH1, using +code like the following in the "footer.txt" file: + +

+<script nonce="$nonce">
+  <th1>styleScript</th1>
+</script>
+

+ +The js.txt file was originally used to insert javascript +that controls the hamburger menu in the default skin. More +recently, the javascript for the hamburger menu was moved into +a separate built-in file. Skins that use the hamburger menu +typically cause the javascript to be loaded by including the +following TH1 code in the "header.txt" file: + +

+<th1>builtin_request_js hbmenu.js</th1>
+

+ +The difference between `styleScript` and `builtin_request_js` +is that the `styleScript` command interprets the file +using TH1 and injects the content directly into the output +stream, whereas the `builtin_request_js` command inserts the +Javascript verbatim and does so at some unspecified future time +down inside the Fossil-generated footer. +You can use either +approach in custom skins that you create. + +Note that the "js.txt" file is *not* automatically inserted into +the generate HTML for a page. You, the skin designer, must +cause the javascript to be inserted by issuing appropriate +TH1 commands in the "header.txt" or "footer.txt" files.

+ +Developing a new skin is simply a matter of creating appropriate +versions of these five control files. + +### Skin Development Using The Web Interface + +Users with admin privileges can use the Admin/Skin configuration page +on the web interface to develop a new skin. The development of a new +skin occurs without disrupting the existing skin. So you can work on +a new skin for a Fossil instance while the existing skin is still in +active use. + +The new skin is a "draft" skin. You initialize one of 9 draft skins +to either the current skin or to one of the built-in skins. Then +use forms to edit the 5 control files described above. The new +skin can be tested after each edit. Finally, once the new skin is +working as desired, the draft skin is "published" and becomes the +new live skin that most users see. + +### Skin Development Using A Local Text Editor + +An alternative approach is to copy the five control files for your +baseline skin into a temporary working directory (here called +"./newskin") and then launch the [fossil ui](/help/ui) command +with the "--skin ./newskin" option. If the argument to the --skin +option contains a "/" character, then the five control files are +read out of the directory named. You can then edit the control +files in the ./newskin folder using you favorite text editor, and +press "Reload" on your browser to see the effects. + + +### Disabling The Web Browser Cache During Development + +Fossil is aggressive about asking the web browser to cache +resources. While developing a new skin, it is often helpful to +put your web browser into developer mode and disable the cache. +If you fail to do this, then you might make some change to your skin +under development and press "Reload" only to find that the display +did not change. After you have finished work your skin, the +caches should synchronize with your new design and you can reactivate +your web browser's cache and take it out of developer mode. + +## Header and Footer Processing + +The `header.txt` and `footer.txt` control files of a skin are the HTML text +of the Skin Header and Skin Footer, except that before being inserted +into the output stream, the text is run through a +[TH1 interpreter](./th1.md) that might adjust the text as follows: + + * All text within <th1>...</th1> is omitted from the + output and is instead run as a TH1 script. That TH1 + script has the opportunity to insert new text in place of itself, + or to inhibit or enable the output of subsequent text. + + * Text of the form "$NAME" or "$<NAME>" is replaced with + the value of the TH1 variable NAME. See the [TH1 Variables](#vars) + section for more information on the two possible variable formats. + +For example, first few lines of a typical Skin Header will look +like this: + +

$

$/div> + +After variables are substituted by TH1, that will look more like this: + + <header> + <div class="title"><h1>Project Name</h1>Page Title</div> + +As you can see, two TH1 variable substitutions were done. + +The same TH1 interpreter is used for both the header and the footer +and for all scripts contained within them both. Hence, any global +TH1 variables that are set by the header are available to the footer. + +## <a id="menu"></a>Customizing the ≡ Hamburger Menu + +The menu bar of the default skin has an entry to open a drop-down menu with +additional navigation links, represented by the ≡ button (hence the name +"hamburger menu"). The Javascript logic to open and close the hamburger menu +when the button is clicked is usually handled by a script named +"hbmenu.js" that is one of the [built-in resource files](/test-builtin-files) +that are part of Fossil. + +The ≡ button for the hamburger menu is added to the menu bar by the following +TH1 commands in the `header.txt` file, right before the menu bar links: + + html "<a id='hbbtn' href='$home/sitemap'>☰</a>" + builtin_request_js hbmenu.js + +The hamburger button can be repositioned between the other menu links (but the +drop-down menu is always left-aligned with the menu bar), or it can be removed +by deleting the above statements. The "html" statement inserts the appropriate +`<a>` for the hamburger menu button (some skins require something slightly +different - for example the ardoise skins wants "`<li><a>`"). The +"builtin_request_js hbmenu.js" asks Fossil to include the "hbmenu.js" +resource files in the Fossil-generated footer. + +The hbmenu.js script requires +the following `<div>` element somewhere in your header, in which to build +the hamburger menu. + + <div id='hbdrop'></div> + +Out of the box, the contents of the panel is populated with the [Site +Map](/sitemap), but only if the panel does not already contain any HTML +elements (that is, not just comments, plain text or non-presentational white +space). So the hamburger menu can be customized by replacing the empty `<div +id='hbdrop'></div>` element with a menu structure knitted according to the +following template: + + <div id="hbdrop" data-anim-ms="400"> + <ul class="columns" style="column-width: 20em; column-count: auto"> +  + <li> + <a href="$home$index_page">Link: Home</a> + <ul> + <li><a href="$home/timeline">Link: Timeline</a></li> + <li><a href="$home/dir?ci=tip">Link: File List</a></li> + </ul> + </li> +  + <li> + Heading Text + <ul> + <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li> + <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li> + </ul> + </li> +  + </ul> + </div> + +The custom `data-anim-ms` attribute can be added to the panel element to direct +the Javascript logic to override the default menu animation duration of 400 ms. +A faster animation duration of 80-200 ms may be preferred for smaller menus. The +animation is disabled by setting the attribute to `"0"`. + + +## <a id="vars"></a>TH1 Variables + +Before expanding the TH1 within the header and footer, Fossil first +initializes a number of TH1 variables to values that depend on +repository settings and the specific page being generated. + +Variables holding text that is loaded from "external, potentially untrusted" +sources (including the repository settings) are treated as [tainted strings] +(./th1.md#taint) and must be noted in the `$<NAME>` form, instead of `$NAME`, +or they may trigger an error (see the linked document for details). The +`$<NAME>` form corresponds to the TH1 statement `puts [ htmlize "$NAME" ]`, +where the [htmlize](./th1.md#htmlize) function escapes the tainted string, +making it safe for output in HTML code. + + + * **`project_name`** - The project_name variable is filled with the + name of the project as configured under the Admin/Configuration + menu. This is a [tainted string](./th1.md#taint) variable and must + be used as `$<project_name>`. + + * **`project_description`** - The project_description variable is + filled with the description of the project as configured under + the Admin/Configuration menu. This is a [tainted string] + (./th1.md#taint) variable and must be used as `$<project_description>`. + + * **`mainmenu`** - The mainmenu variable contains a TCL list with the main + menu entries. See the [mainmenu](/help/mainmenu) setting for details. + + * **`title`** - The title variable holds the title of the page being + generated. + + The title variable is special in that it is deleted after + the header script runs and before the footer script. This is + necessary to avoid a conflict with a variable by the same name used + in my ticket-screen scripts. + + * **`baseurl`** - The root of the URL namespace for this server. + + * **`secureurl`** - The same as $baseurl except that if the scheme is + "http:" it is changed to "https:" + + * **`home`** - The $baseurl without the scheme and hostname. For example, + if the $baseurl is "http://projectX.com/cgi-bin/fossil" then the + $home will be just "/cgi-bin/fossil". + + * **`index_page`** - The landing page URI as + specified by the Admin/Configuration setup page. + + * **`current_page`** - The name of the page currently being processed, + without the leading "/" and without query parameters. + Examples: "timeline", "doc/trunk/README.txt", "wiki". + + * **`current_checkin`** - The [check-in name](./checkin_names.wiki) to + which the current + [/ci](/help/www/ci), + [/dir](/help/www/dir), + [/tree](/help/www/tree), + [/timeline](/help/www/timeline) or + [/vinfo](/help/www/vinfo) + page refers, or undefined for all other pages. This variable is + derived from query parameters and is therefore a [tainted string] + (./th1.md#taint). + + * **`csrf_token`** - A token used to prevent cross-site request forgery. + + * **`default_csp`** - [Fossil’s default CSP](./defcsp.md) unless + [overridden by custom TH1 code](./defcsp.md#th1). Useful within + the skin for inserting the CSP into a `<meta>` tag within [a + custom `<head>` element](#headfoot). + + * **`nonce`** - The value of the cryptographic nonce for the request + being processed. + + * **`release_version`** - The release version of Fossil. Ex: "1.31" + + * **`manifest_version`** - A prefix on the check-in hash of the + specific version of fossil that is running. Ex: "\[47bb6432a1\]" + + * **`manifest_date`** - The date of the source-code check-in for the + version of fossil that is running. + + * **`compiler_name`** - The name and version of the compiler used to + build the fossil executable. + + * **`login`** - This variable only exists if the user has logged in. + The value is the username of the user. + + * **`stylesheet_url`** - A URL for the internal style-sheet maintained + by Fossil. + + * **`logo_image_url`** - A URL for the logo image for this project, as + configured on the Admin/Logo page. + + * **`background_image_url`** - A URL for a background image for this + project, as configured on the Admin/Logo page. + +All of the above are variables in the sense that either the header or the +footer is free to change or erase them. But they should probably be treated +as constants. New predefined values are likely to be added in future +releases of Fossil. + + +## <a id="procedure"></a>Suggested Skin Customization Procedure + +Developers are free, of course, to develop new skins using any method they +want, but the following is a technique that has worked well in the past and +can serve as a starting point for future work: + + 1. Select a built-in skin that is closest to the desired look. Make + copies of the css, footer, and header into files name "css.txt", + "details.txt", + "footer.txt", and "header.txt" in some temporary directory. + + If the Fossil source code is available, then these three files can + be copied directly out of one of the subdirectories under skins. If + sources are not easily at hand, then a copy/paste out of the + CSS, footer, and header editing screens under the Admin menu will + work just as well. The important point is that the three files + be named exactly "css.txt", "footer.txt", and "header.txt" and that + they all be in the same directory. + + 2. Run the [fossil ui](/help/ui) command with an extra + option "--skin SKINDIR" where SKINDIR is the name of the directory + in which the three txt files were stored in step 1. This will bring + up the Fossil website using the tree files in SKINDIR. + + 3. Edit the *.txt files in SKINDIR. After making each small change, + press Reload on the web browser to see the effect of that change. + Iterate until the desired look is achieved. + + 4. Copy/paste the resulting css.txt, details.txt, + header.txt, and footer.txt files + into the CSS, details, header, and footer configuration screens + under the Admin/Skins menu. Alternately, import them using the + process described below. + +An alternative to step 4 is to convert the skin files into a form +which can be imported into a repository using `fossil config import`. +It requires compiling [a small tool from the fossil source +tree](/file/tools/skintxt2config.c): + +> +``` +$ cc -o s2c /path/to/fossil/checkout/tools/skintxt2config.c +``` + +With that in place, the custom skin files can be converted with: + +> +``` +$ ./s2c yourskin/*.txt > skin.config +``` + +It can be imported into an arbitrary fossil repository with: + +> +``` +$ fossil config import skin.config +``` + +And it can be pushed to a remote repository with: + +> +``` +$ fossil config push skin +``` + +That approach has proven to be an effective way to locally develop +skin changes then push them to a "live" site. + + +## See Also + +* [Customizing the Timeline Graph](customgraph.md) -- cgit v1.3.1