We use Yellowfin as the reporting layer for our MagnumBI platform for many reasons, one of them is customisation. Yellowfin have designed their product so you can change it to match your own style and brand it. By changing colours and pictures we’ve customised the standard login page (top) with a custom colour scheme and new images (bottom):
There’s a few parts that can be branded easily and a whole lot more if you’re willing to experiment. Yellowfin uses java, html and css to run it’s application which means most of it can be tweaked. You need to really think about the level of customisation you want to do, if new versions are released then you need to re-apply all of the changes and the more you customise, the more complex it becomes which generally means more can go wrong. Personally I’d prefer to stick with the standard customisation methods.
The Yellowfin overview page can be found here: http://wiki.yellowfin.com.au/display/USER70/Restyling+Yellowfin
Before you get started there’s a few things to consider:
- You shouldn’t experiment with a production environment. If you want to continue be prepared to restart services and potentially break it (and hopefully fix it again) – it took some experimentation to get to the look and feel we wanted and the web service had to be restarted several times.
- You should have a good understanding of HTML and CSS.
- You need administrator access to the server where your Yellowfin instance is hosted. You will need to be able to access the web hosted files and edit them.
- You should understand how to stop/start services on the server and know which web hosting service you’re using for Yellowfin (Tomcat is the default).
- My guide is based on Linux running Tomcat, it’s a similar process on other hosted solutions but commands and paths will be different. You should understand your environment, specifically how to restart services and where your Yellowfin install path is – for our environment the path is /opt/Yellowfin on the server.
If you’re going to make changes to any system, back it up first. Ideally back up everything and make a copy of all files you’re changing.
You can override the default images without affecting the originals. Just put the replacement files in the customimages folder and they will be used instead.
In our instance the path is /opt/Yellowfin/appserver/webapps/ROOT/customimages
The Yellowfin wiki page can be found here: http://wiki.yellowfin.com.au/pages/viewpage.action?pageId=5505640
CUSTOM LOGIN PAGE
Yellowfin provides good guides in their wiki, this is what I followed to customise our Yellowfin login page:
Yellowfin have provided some example pages which can be found in your application directory, in our case it was /opt/Yellowfin/development/examples/
The file used for the login page is index_mi.jsp
We made a copy of this file and edited it – I used Notepad++ (freeware) to change the code but you can use any tool you prefer, although if you plan to use a visual editor (E.g. Dreamweaver) it’s likely to take a lot of playing with configuration to both permissions and file paths to get it working. In the end it seemed a lot easier to tweak the code in a simple text editor.
At this point it’s up to you what you want to change, it completely depends on the design you’re aiming for but here’s a couple of hints from what we did.
- Change the Title in the HTML Header
- They’ve included most of the CSS classes in this file to make it easier to customise, these are near the top and can be tweaked directly in index_mi.jsp.
- If you want to override one of the inherited styles from a separate CSS file use the tag !important which will use the style you’ve specified rather than any inheritance, assuming you’ve put it in the right place.
- You can add classes at the top of the file with the same name as inherited classes to override them. Once again you may need to use the !important flag
- Find images on the page that you want to change and re-create them using the same dimensions as the original file and put them into the customimages folder.
- You will need to edit web.xml with the name of the new login page. There is a flag called <welcome-file> which needs to be changed to the name of your new login page. Any changes to this file will require a restart of the web hosting service and you should always back it up first! You should put your newly created login page in the /ROOT/ directory.
- If you add any files to customcss or customimages folders, you will need to restart the web hosting service to pick up that these files have been added.
- You don’t need to restart the web hosting service if you’re updating/replacing a file in the same location (except web.xml as it’s a config file). Shift+Refresh in the browser will pick up the changes. It’s only when you’re adding files to override originals it needs to be restarted.
- You must change all references to index_mi.jsp in the custom login page to the new name you’ve used – it appeared twice in our file.
- Uploading files on a Linux install requires Super User rights. We found it easier to copy the files to our home directory then use the command ‘sudo cp [ORIGIN PATH] [DESTINATION PATH]’ to copy it to the Yellowfin directory, but this depends on the security you have setup on your server.
- The easiest way to change the images is to load the standard login page, right click each image and save them. You can then find out the dimensions of the files and recreate them with the same name. In some cases it may be an entirely different image (logo and background) in others it might just be a simple colour change, depends on what you’re after.
- There’s also two hidden parts to the page, the ‘Login Again’ message that happens when you close the page and go back to it before your session has timed out and an error message part which appears when an error occurs i.e. wrong password or multiple concurrent hosts.
The ‘Login Again’ part uses the i4bodytext CSS class to customise.The error part uses the i4error CSS class. I added this class to the top of my index_mi.jsp page with the !important tag to override the default style. This corrected the text colour after changing the page background colour. It also uses an image called error.png if you want to customise this too.
We mainly changed colours and used new images. We removed the footer DIV too so the page looked simple and clean.
Once you’ve configured it as you want it, you just need to upload the new images to the customimages folder, upload the login page to your /ROOT/ folder and update web.xml with the new name. Restart the web hosting service and the new pages should take effect.