Gerrit Rebranding – The missing Guide to a customized Look & Feel

Our new Git/Gerrit integration for TeamForge has just been released and it is based on Open Source Gerrit 2.6.1. Its default appearance is quite light and lean (see picture below), but may not fit the visual policies of all our customers.

Gerrit 2.6.1 original look

This blog post covers Gerrit’s rebranding capabilities. All technical information is available in Gerrit’s official release documentation (here) – however it is scattered across different topics and is lacking practical usage examples. The following branding example results in a completely different visual appearance of Gerrit’s Web UI. The specific color choices are just for demonstration purposes not as a fashion statement 😉

Theme definition in gerrit.config

Details of definition are provided here. Sufficient for quick wins (e.g. changing colors of background, menu, text, tables, selection,…) however it is not possible to interfere with Gerrit’s page structure (no possibility to add new links, images,…). It also requires Gerrit service restart before changes are visible. Let’s assume that CollabNet is the customer in question and wants to have Gerrit in Orange-Yellowish theme. Here are the gerrit.config file modifications:

[theme]
backgroundColor = FFFFDD
topMenuColor = FF3322
textColor = FF3322
trimColor = FFBB11
selectionColor = FFDD11
tableEvenRowColor = FFFFFAA

and how change page looks after applying it:

Although there is a possibility to differentiate themes according to whether a user is already logged in, not all parts of the page where changed as it was expected :/ – take a closer look for instance at sub-menu entries (Changes, Drafts,…) – they are still bluish…

CSS power to the rescue

CSS Site Customization (described here) – allows even more advanced modifications of Gerrit’s main page elements (e.g. top menu text color, author name color,…). Changes are reflected immediately on browser refresh. Here is the GerritSite.css (has to be placed in /opt/collabnet/gerrit/etc directory) file content that changes bluish texts to be more consistent with the rest of the page:

a, a:visited {
color: #FF1122 !important;
}

.version, .keyhelp {
color: #FFAA11 !important;
}

and here is the changed page after applying it:

There is still place for improvement.  There is no single CollabNet logo here. By the power of CSS existing icons could be changed and components restructured to some extent – but how about adding a link to the company’s web site?

Additional page’s HTML elements

HTML Headers/Footers (also described here) help in that area. Here is an example of GerritSiteFooter.html file (has to be placed in /opt/collabnet/gerrit/etc directory) that introduces a link:

<a class=”logo_anchor” target=”_blank” href=”http://www.collab.net/”>main page</a>

Modifications to GerritSiteFooter.html are immediately visible (although it could be easily overlooked that is why it was marked in blue) on browser refresh and that’s how they look:

It is not very impressive and the link is barely visible – however by using CSS it might be improved. Here is a modified GerritSiteFooter.html (link’s title was removed)

<a class=”logo_anchor” target=”_blank” href=”http://www.collab.net/”></a>

Combined with a change in GerritSite.css to provide a background picture (note that embedded base64 encoding might have been used here for the image but instead we are referring to a file tf_logo.png we have placed in /opt/collabnet/gerrit/static directory which content is automatically served by Gerrit) to link to CollabNet’s main page:

a, a:visited {
color: #FF1122 !important;
}

.version, .keyhelp {
color: #FFAA11 !important;
}

a.logo_anchor {
display: block;
background-image: url(‘static/tf_logo.png’);
background-repeat: no-repeat;
width: 86px;
height: 30px;
margin: 0 9px;
padding: 0;
}

New clickable logo in page:

Visibility has been improved however one could say again that it should be horizontally aligned with Gerrit’s footer. Here’s an improved version of GerritSite.css:

a, a:visited {
color: #FF1122 !important;
}

.version, .keyhelp {
color: #FFAA11 !important;
}

a.logo_anchor {
display: block;
background-image: url(‘static/tf_logo.png’);
background-repeat: no-repeat;
width: 86px;
height: 30px;
margin: 0 9px;
padding: 0;
}

/* Gerrit’s page elements style modifications */
#gerrit_footer {
width: 95px;
}

#gerrit_btmmenu[style] {
position: relative;
top: -30px;
clear: none !important;
float: right;
}

And here is the final result:

Note that although .cache was not used for the clickable logo it is kind of a static and gets refreshed when a user presses Ctrl+F5 in his/her browser. Another solution is to add the .cache extension to the image file. Whenever the image changes, a new file name has to be chosen and GerritSite.css needs to be updated too.

What comes next? Our header can be easily improved for instance with a gradient by introduction of a GerritSiteHeader.html file (placed also in /opt/collabnet/gerrit/etc directory). The same GerritSite.css file is responsible for styling. GerritSiteHeader.html content:

<div class=”header_gradient”></div>

GerritSite.css update (only added lines were provided):

div.header_gradient {
height: 70px;
width: 100%;
background: #ff3322; /* Old browsers */
background: -moz-linear-gradient(top,  #ff3322 0%, #ff7c00 33%, #ffa73d 61%, #ffffdd 100%); /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#ff3322), color-stop(33%,#ff7c00), color-stop(61%,#ffa73d), color-stop(100%,#ffffdd)); /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* Opera 11.10+ */
background: -ms-linear-gradient(top,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* IE10+ */
background: linear-gradient(to bottom,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr=’#ff3322′, endColorstr=’#ffffdd’,GradientType=0 ); /
}

Page with gradient:

Once again further CSS changes are required in order to move our gradient to the very top of the page. Here is the gradient’s part of GerritSite.css with updates:

div.header_gradient {
position: absolute;
top: 0px;
z-index: -1;
height: 70px;
width: 100%;
background: #ff3322; /* Old browsers */
background: -moz-linear-gradient(top,  #ff3322 0%, #ff7c00 33%, #ffa73d 61%, #ffffdd 100%); /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#ff3322), color-stop(33%,#ff7c00), color-stop(61%,#ffa73d), color-stop(100%,#ffffdd)); /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* Opera 11.10+ */
background: -ms-linear-gradient(top,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* IE10+ */
background: linear-gradient(to bottom,  #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr=’#ff3322′, endColorstr=’#ffffdd’,GradientType=0 ); /
}

and our page with the gradient on top:

At this point Gerrit’s theme was changed to a new color palette and one could say that job was done – however…

Gerrit Theme vs integration with GitWeb

Here is GitWeb’s page capture:

This page contains the same header/footer elements that were introduced for Gerrit site page and this is unfortunate. Some elements (marked with yellow) were transferred from the new theme. Let’s take a look into Firebug (or similar) to see the page structure:

Site footer and header elements are part of the page (highlighted in yellow) and GerritSite.css is also included (as a part of the header section not visible in this picture). I don’t want to judge if this behavior is correct or not – it is clear that the same mechanism is used to generate both pages yet GitWeb Cache one contains “orphaned” elements of the regular Gerrit main page.
In order to solve it let’s look once again at Gerrit’s main page but with Firebug enabled:

As one may see (yellow highlights) when Gerrit’s main page is rendered, header and footer elements are part of corresponding page template elements (gerrit_header and gerrit_footer) and they are orphaned (part of the body in previous picture) when GitWeb site is rendered. This page structure difference allows to enable/disable theme elements depending on the page type. Here is an updated GerritSite.css that handles both pages respectively (note that in contrast to regular GerritSite.css changes updates to GitWeb’s UI require a Gerrit restart). The footer part contains two entries – one that hides the logo when it is not needed followed by one that shows it when needed (i.e. it is a part of gerrit_footer):

a.logo_anchor {
display: none;
visibility: hidden;
}

div#gerrit_footer a.logo_anchor {
display: block;
visibility: visible;
background-image: url(‘static/tf_logo.png’);
background-repeat: no-repeat;
width: 86px;
height: 30px;
margin: 0 9px;
padding: 0;
}

The header part contains also two entries now:

div.header_gradient {
display: none;
visibility: hidden;
}

div#gerrit_header div.header_gradient {
position: absolute;
top: 0px;
z-index: -1;
height: 70px;
width: 100%;
background: #ff3322; /* Old browsers */
background: -moz-linear-gradient(top, #ff3322 0%, #ff7c00 33%, #ffa73d 61%, #ffffdd 100%); /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#ff3322), color-stop(33%,#ff7c00), color-stop(61%,#ffa73d), color-stop(100%,#ffffdd)); /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top, #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top, #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* Opera 11.10+ */
background: -ms-linear-gradient(top, #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* IE10+ */
background: linear-gradient(to bottom, #ff3322 0%,#ff7c00 33%,#ffa73d 61%,#ffffdd 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr=’#ff3322′, endColorstr=’#ffffdd’,GradientType=0 ); /
}

In both cases the same trick is used: Enable (make visible) elements only when they are part of the corresponding Gerrit main page template (gerrit_header or gerrit_footer) – in all other cases disable them.

Summary

Although our example was quite simple we hope we were able to demonstrate that Gerrit has a powerful rebranding mechanism which does not require any source code changes, modification of existing files or service restarts. If GitWeb was restyled independently, one needs to pay some attention when to display additionally introduced elements but the practices shown in this blog should be applicable for all major use cases. All modified files are part of the orange_theme attachment.

Tagged with: , , ,
Posted in Git, TeamForge

Leave a Reply

Your email address will not be published. Required fields are marked *

*