Gerrit Theming for Front-end Developers!

Gerrit is a code review tool for git. You can think of it as a self-hosted alternative to github, with a number of server-side extensions to make it handy and useful. It's hosted on Gerrit's Google Code, though I'm not sure how that'll last, as Google Code is going away. Something at Google Source, maybe?

Anyway, an end-user difficulty with Gerrit is that it pretty much looks like ass.

Okay, that's not fair. It doesn't look like ass, it does, however, look like gmail.

So, how does one theme Gerrit so that it doesn't look like ass? You can google, "gerrit theming" (a good example), discover Gerrit is written in Java, using GWT, the Google Web Toolkit, and pull your hair out with how cumbersome adding a CSS framework to it is.

Or, you could exploit the way Gerrit DOES allow customization.

According to the Gerrit documentation, you can have three files:

• <theme-dir>/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.
• <theme-dir>/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.
• <theme-dir>/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.

So, to theme Gerrit, you edit the GerritSiteHeader.html, GerritSiteFooter.html, GerritSite.css files, and boom, you can have your new theme. Easy, right?

No.

There's the first part of the problem: the GerritSite.css file IS NOT THE LAST CSS FILE TO BE INCLUDED.

So, be sure to add !important ALL OVER YOUR NEW GerritSite.css file. That's fine, easy enough, but how do you add things like, nice menu bars, good white space, and a CSS framework?

Well...

The GerritSite.css file is included straight.

This means, you can start your GerritSite.css file with this:

</style>
<script>
</script>
<style>

See that? See those script tags?

Yep.

So... here's what you do.

1. Download jQuery, unzip and find the minimized javascript file.
2. Download a customized version of Bootstrap, with only the components you need. I recommend Grid System, Tables, Forms, Navs, Navbars, and Dropdown.
3. Download the jQuery arrive plugin.

Gerrit uses GWT, which means that everything is a bizarro java javascript single page weirdo application, which also means that the base HTML is stunningly sparse and everything loads via javascript WAAAAAAAAAY after the document is done loading and is ready. You can't use the usual $(document).ready(function(){}); snippet for triggering off events.

Enter the jQuery arrive plugin.

The plugin watches for DOM element creation and triggers events when they show up. Hot damn.

Take the minimized files, and concatenate the javascript together into a new file. The Bootstrap CSS downloads as a minimized file already.

$ cat jquery-1.12.0.min.js bootstrap.min.js arrive.min.js >> min.js

This file is going to be included in the GerritSite.css file, in this order, with these tags:

</style>
<script>
# minimized javascript goes here (min.js)
</script>
<style>
# minimized CSS goes here (bootstrap.min.css)
</style>
<script>
# custom javascript goes here
</script>
<style>
# custom CSS goes here

Save that file in your theme directory (mine is install/etc), and refresh the page.

Once that's done, we are ready to style things in earnest!

Instead of using .ready(), you now want to use .arrive():

$(document).arrive("#gerrit_topmenu .topmenuMenuLeft"), function() {
  // the menus have arrived, manipulate them to add bootstrap styling
});

$(document).arrive("#gerrit_body table.changeTable"), function() {
  // the content has arrived, manipulate it to add bootstrap styling
  $('table.changeTable').addClass('table table-striped')
});

As mentioned, gerrit loads another CSS file after the GerritSite.css file, so you might need to add a large number of !important attributes, which is annoying, and necessary.

More tips, after adding CSS at the bottom of the file and testing during development, be sure to minimize the CSS and any Javascript you've added. This solution added an extra 250kb to my install, so this isn't a lightweight solution.

It is, however, a fantastic way to get easy customization without having to recompile gerrit or, shudder learn GWT.