Gerrit2 - Site Customization

At startup Gerrit reads the following files (if they exist) and uses them to customize the HTML page it sends to clients:

• $site_path/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.

• $site_path/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.

• $site_path/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.

If any of these files are created, deleted or modified you need to restart the web application to make the changes take effect.

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 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, only files are 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.)

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 the Gerrit server has been restarted.

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 Gerrit restart 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.

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>
<!-- /standard analytics code -->

<script type="text/javascript">
  window.onload = function() {
    gerrit_addHistoryHook(function (s) {
      pageTracker._trackPageview(s.replace(/#/, '/'))
    });
  };
</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_addHistoryHook 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 /change,123 be passed to these functions, which in turn are handed off to Google Analytics for tracking. Our example hook above replaces with / because Analytics won't track anchors.

The window.onload callback is necessary to ensure that the gerrit_addHistoryHook function has actually been defined by the page. Because GWT loads the module asynchronously any <script> block in the header or footer will execute before Gerrit has defined the function and is ready to register the hook callback.