Artifact f2eaa2435ad521cc9d3f8f7f5d33007b7f2c7c61:
- File www/customskin.md — part of check-in [e214a576ea] at 2015-02-16 19:27:03 on branch trunk — Fix a bug in the markdown_to_html() routine in finding the title of the document. *This change requires a search index rebuild*. Begin adding documentation on how the header/footer mechanism works. (user: drh size: 6860)
Customizing Fossil's Look
Every HTML page generated by Fossil has the following basic structure:
Header Content Footer
The header and footer control the "look" of Fossil pages. Those two sections can be customized separately for each repository to develop a new theme.
The header will normally look something like this:
<html>
<head> ... </head>
<body>
... top banner and menu bar ...
<div class='content'>
And the footer will look something like this:
</div>
... bottom material ...
</body>
</html>
The <head> element in the header will normally reference the /style.css CSS file that Fossil stores internally.
The middle "content" section of Fossil-generated pages is not normally customizable. The appearance of Fossil is mostly governed by the CSS, header, and footer, all of which are changeable on a per-repository basis. We call the bundle of built-in CSS, header, and footer a "skin".
Built-in Skins
Fossil comes with several built-in skins. The sources to these built-ins can be found in the Fossil source tree under the skins/ folder. The skins/ folder contains a separate subfolder for each built-in skin, with each subfolders holding three files, "css.txt", "footer.txt", and "header.txt", that describe the CSS, footer, and header for that skin, respectively.
The skin of a repository can be changed to any of the built-in skins using the web interface by going to the /setup_skin web page (requires Admin privileges) and clicking the appropriate button. Or, the --skin command line option can be used for the fossil ui or fossil server commands to force that particular instance of Fossil to use the specified built-in skin.
Sharing Skins
The skin of a repository is not part of the versioned state and does not "push" or "pull" like checked-in files. The skin is local to the repository. However, skins can be shared between repositories using the fossil config command. The "fossil config push skin" will send the local skin to a remote repository and the "fossil config pull skin" command will import a skin from a remote repository. The "fossil config export skin FILENAME" will export the skin for a repository into a file FILENAME. This file can then be imported into a different repository using the "fossil config import FILENAME" command. Unlike "push" and "pull", the "export" and "import" commands are able to move skins between repositories for different projects. So, for example, if you have a group of related repositories, you can develop a skin for one of them, then get a consistent look across all the repositories by exporting the skin from the first repository and importing into all the others.
The file generated by "fossil config export" could be checked into one of your repositories and versioned, if desired. This will not automatically change the skin when looking backwards in time, but it will provide an historical record of what the skin used to be and allow the historical look of the repositories to be recreated if necessary.
When cloning a repository, the skin of new repository is initialized to the skin of the repository from which it was cloned.
Header And Footer
The header.txt and footer.txt files of a scan are merely the HTML text of the header and footer. Except, that text is allowed to contain embedded TH1 script to modify or change its content. With the header or footer, all text between <th1>...</th1> is run as a TH1 script. And elements of the form <$NAME> are replaced by the value of the NAME variable in TH1.
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.
TH1 Variables
Before expanding the TH1 within the header and footer, Fossil first initializes a number of TH1 variables to values that depend on respository settings and the specific page being generated.
project_name - The project_name variable is filled with the name of the project as configured under the Admin/Configuration menu.
title - The title variable holds the title of the page being generated. This 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".
csrf_token - A token used to prevent cross-site request forgery.
release_version - The release version of Fossil. Ex: "1.31"
manifest_version - A prefix on the SHA1 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.
log_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.