3fbdf98c9a
Project-specific themes were only implemented in the GWT UI, which has been removed. Remove the ThemeInfo entity, and no longer include the 'theme' field in the ConfigInfo entity returned by the project config REST API endpoint. This is a breaking change for any client that still uses that endpoint. The custom site header HTML, footer HTML, and CSS files are still used by login screens and the internally managed Gitweb server. Update the theme documentation to mention this. PolyGerrit has site-wide theme support, but it is not documented in the existing config-themes.txt, and adding it is not within the scope of this change. Change-Id: Ibe824a9416fac65bd365407b8ce22e03515b5b52
134 lines
4.6 KiB
Plaintext
134 lines
4.6 KiB
Plaintext
= Gerrit Code Review - Themes
|
|
|
|
Gerrit supports some customization of the HTML it sends to
|
|
the browser, allowing organizations to alter the look and
|
|
feel of the application to fit with their general scheme.
|
|
|
|
== HTML Header/Footer and CSS
|
|
|
|
The HTML header, footer and CSS may be customized for login
|
|
screens (LDAP, OAuth, OpenId) and the internally managed
|
|
Gitweb servlet.
|
|
|
|
At startup Gerrit reads the following files (if they exist) and
|
|
uses them to customize the HTML page it sends to clients:
|
|
|
|
* `etc/GerritSiteHeader.html`
|
|
+
|
|
HTML is inserted below the menu bar, but above any page content.
|
|
This is a good location for an organizational logo, or links to
|
|
other systems like bug tracking.
|
|
|
|
* `etc/GerritSiteFooter.html`
|
|
+
|
|
HTML is inserted at the bottom of the page, below all other content,
|
|
but just above the footer rule and the "Powered by Gerrit Code
|
|
Review (v....)" message shown at the extreme bottom.
|
|
|
|
* `etc/GerritSite.css`
|
|
+
|
|
The CSS rules are inlined into the top of the HTML page, inside
|
|
of a `<style>` tag. These rules can be used to support styling
|
|
the elements within either the header or the footer.
|
|
|
|
The *.html files must be valid XHTML, with one root element,
|
|
typically a single `<div>` tag. The server parses it as XML, and
|
|
then inserts the root element into the host page. If a file has
|
|
more than one root level element, Gerrit will not start.
|
|
|
|
== Static Images
|
|
|
|
Static image files can also be served from `'$site_path'/static`,
|
|
and may be referenced in `GerritSite{Header,Footer}.html`
|
|
or `GerritSite.css` by the relative URL `static/$name`
|
|
(e.g. `static/logo.png`).
|
|
|
|
To simplify security management, files are only served from
|
|
`'$site_path'/static`. Subdirectories are explicitly forbidden from
|
|
being served from this location by enforcing the rule that file names
|
|
cannot contain `/` or `\`. (Client requests for `static/foo/bar`
|
|
will result in 404 Not Found responses.)
|
|
|
|
== HTTP Caching
|
|
|
|
The header, footer, and CSS files are inlined into the host page,
|
|
which is always sent with a no-cache header. Clients will see any
|
|
changes immediately after they are made.
|
|
|
|
Assets under `'$site_path'/static` whose file name matches one of the
|
|
following patterns are served with a 1 year expiration, permitting
|
|
very aggressive caching by clients and edge-proxies:
|
|
|
|
* `*.cache.html`
|
|
* `*.cache.gif`
|
|
* `*.cache.png`
|
|
* `*.cache.css`
|
|
* `*.cache.jar`
|
|
* `*.cache.swf`
|
|
|
|
All other assets under `'$site_path'/static` are served with a 5
|
|
minute expire, permitting some (limited) caching. It may take up
|
|
to 5 minutes after making a change, before clients see the changes.
|
|
|
|
It is recommended that static images used in the site header
|
|
or footer be named with a unique caching file name, for example
|
|
`my_logo1.cache.png`, to allow browsers to take advantage of their
|
|
disk cache. If the image needs to be modified, create a new file,
|
|
`my_logo2.cache.png` and update the header (or footer) HTML to
|
|
reference the new image path.
|
|
|
|
== Google Analytics Integration
|
|
|
|
To connect Gerrit to Google Analytics add the following to your
|
|
`GerritSiteFooter.html`:
|
|
|
|
----
|
|
<div>
|
|
<!-- standard analytics code -->
|
|
<script type="text/javascript">
|
|
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
|
|
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
|
|
</script>
|
|
<script type="text/javascript">
|
|
var pageTracker = _gat._getTracker("UA-nnnnnnn-n");
|
|
pageTracker._trackPageview();
|
|
</script>
|
|
be <!-- /standard analytics code -->
|
|
|
|
<script type="text/javascript">
|
|
window.onload = function() {
|
|
var p = window.location.pathname;
|
|
Gerrit.on('history', function (s) {
|
|
pageTracker._trackPageview(p + '/' + s)
|
|
});
|
|
};
|
|
</script>
|
|
</div>
|
|
----
|
|
|
|
Please consult the Google Analytics documentation for the correct
|
|
setup code (the first two script tags). The above is shown only
|
|
as a reference example.
|
|
|
|
If your footer is otherwise empty, wrap all of the script tags into
|
|
a single `<div>` tag (like above) to ensure it is a well-formed
|
|
XHTML document file.
|
|
|
|
The global function `Gerrit.on("history")` accepts functions that
|
|
accept a string parameter. These functions are put into a list and
|
|
invoked any time Gerrit shifts URLs. You'll see page names like
|
|
`/c/123` be passed to these functions, which in turn are handed off
|
|
to Google Analytics for tracking. Our example hook above uses '/'
|
|
instead of '#' because Analytics won't track anchors.
|
|
|
|
The `window.onload` callback is necessary to ensure that the
|
|
`Gerrit.on()` function has actually been defined by the
|
|
page.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|