| Gerrit2 - Site Customization |
| ============================ |
| |
| Gerrit2 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 |
| ------------------ |
| |
| 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 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, 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.) |
| |
| 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 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. |
| |
| 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> |
| <!-- /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 |
| `/Gerrit#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. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |