Merlin Reports

 

I use Merlin as my primary project management tool. Merlin offers a neat plug-in interface for its reporting. Unfortunately, that interface is not documented and it takes a little doing to create your own reports.


This article shows how to create your own report in Merlin. You will need some working knowledge of XSLT and the process requires some fiddling with files on your machine. This article is set up as a tutorial and gives you a step-by-step guide to creating a very simple report of your own. Once you managed to get that up, I’m sure that you will be able add more elaborate and more useful reports.




A word of caution: it is entirely possible for you to create a plug-in that will crash Merlin when you load it or when you use it to generate a report.


First, we will look at how Merlin generates reports and where all the necessary files are stored. We will play around with Merlin’s standard features a bit to find out what is stored where. Next, we’ll set up our own report, based on of of Merlin’s standard reports. The report will generate a list of activities for each team member, rather than for just one team member or for the entire team.


How Merlin Generates Reports

Internally, Merlin uses XML to store your projects and project data. The advantage of using XML is that it can be transformed into practically any other file format using XSLT. As you might expect, this is precisely what Merlin does. Merlin’s reporting engine can take an XSLT style sheet and transform the project XML file into some other format.


Consider for example the “Next due Activities” report. Let’s dissect that report and its sources. Please open one of your projects in Merlin and generate a “Next due Activities” report .




The window that opens is actually a web browser, most likely an embedded Safari window. In the report, press the right mouse button. From this menu, we may reach two important files of this report.




The most important file is actually the second one in the menu: the XML file. It is the source file for the XSLT transformation. We will refer to this file as the “project XML file” in the remainder of this article.


The other file, which that menu simply refers to as the HTML file was used to render the report you have just generated and clicked on.


In the menu, pick the option to reveal the project XML file in the finder. This will take you to some random folder deep inside the temporary directories on your machine. There are many files in this folder, but one is highlighted in the finder. This file is the project XML file. Below is a screen shot of the information of one of my project XML files.



Merlin overwrites this file every time you generate a new report and that file is then fed into the XSLT processor to generate the report HTML. You can find that HTML in the folder named “MerlinReports”. In that folder you will find the HTML, CSS style sheets and images of all the reports that you have generated.


Please consider taking a little time to browse around to get a feel for what is where in the temporary folder. Use your favourite text editor to look at the project XML file. In fact, you may want to keep an editor with that XML file open all the time while you are developing your own XSLT style sheet.


Now that we’ve looked at the intermediate files and the output files for a report, where are the XSLT style sheets that generate this report stored? There are actually two places; inside the Merlin application folder and in your application support directory.


Merlin’s own plug-ins are stored in the folder “Merlin.app/Contents/PlugIns”.


Each plug-in is a package of it own. If you enter that folder, you will see that the reports have been laid out with internationalisation in mind.


Deep inside the plug-in package, we finally find what we have been looking for: the XSLT style sheet.


If terminals are not your thing, you can follow the path using a finder window. Right-click on the Merlin application in /Applications and use “show package contents” to reveal the contents of that application. Do the same to reveal the contents of NextDueActivities.mrept.


The file named Report.xslt is the file that drives the report generation process.


Creating Your Own Plug-in

The object of all this digging was to learn how we could create our own reports, so let’s start doing that now. The remainder of this article takes you through that process.


Before you barge in and change the Report.xslt that we have just found, please consider that that file is replaced every time you update the Merlin application. Also, if we change this file, we will no longer be able to generate the standard reports, which may inconvenience other users on your machine. Instead of changing the standard report, let’s create a copy of the standard report and edit that to suit our taste.


Merlin also searches the folder “~/Library/Application Support/Merlin/Reports” for plug-ins. That folder is not scrubbed when a new version of Merlin is released and it does not inconvenience other users to add your own plug-ins there.


Suppose we want to create a report that lists the activities for each team member in a separate table, rather than piling all activities into a single table. We will start by cloning the “Next due Activities” report and adding our own content later.


Clone the Report

Open a terminal to issue the commands below. Don’t forget the -R flag to the cp command, to copy the entire directory and its contents. If you prefer to use the finder, you can create the Reports folder and copy the report with your mouse.



Using you favourite text editor, open the file named “InfoPlist.strings”. You can find that file inside the folder named “English.lproj” inside the plug-in package. Don’t accidentally edit “Info.plist”, that file is not the one that Merlin uses.


In “InfoPlist.strings”, change the values of the properties to show what you would like the report to show up as in Merlin. Below is a screen shot of my edited version.


Now open Merlin and open the report selection menu. You will see your new report in the list of reports that Merlin may generate.




Customise the Report

Of course, if you generate the report now, it will come out identical to the report that we cloned. We have not actually changed the actual XSLT style sheet yet.


The changes to the style sheet that make the team layout work are quite large. Therefore I have uploaded a modified version of the style sheet. You can download my copy, or edit the XSLT to suit your needs.


You do not have to restart Merlin or even reopen the report for every change you make. Simply edit the file, press “save” in your editor and click “refresh” on the report viewer to see the effect of your edits.


Add Images and Bling

Sometimes we want to add our own graphic elements to the reports, or use alternate CSS style sheets. You can place such graphics and style sheets in the folder named “English.lproj”. Merlin will automatically copy them into the “rcs” folder of the generated web page.


For example, if you want to add an image named “person.png” to the page, copy it into the folder named “English.lproj” and use an HTML image tag as follows: <img src="rsc/person.png” /> to place it on the generated page.


Other than that, remember that you are actually generating a regular HTML page. This means that you have access to all the great things that HTML, CSS and even JavaScript have to offer.


Printing Page Breaks

You will probably want to print the report and hand out worksheets to each of the the project’s participants. If you insert the following snippet of CSS in the head element of your generated document, it will print out each participant’s work on a separate page.


    <style type="text/css">

      h1 {

        page-break-before: always;

      }

    </style>


I found this on HTML Goodies.


Debugging Your Report

As you are working to perfect your report, you may make a few mistakes. One moment everything looks great and the next moment you run into half-rendered pages and cryptic error messages. Here are some tips to help you get unstuck.


Back up your known-good reports. Don’t edit your only working copy of the XSLT file.


If you screw up the XSLT, the report viewer will give you the XSLT error message. Read such messages carefully and search the web for possible causes of such errors.


Download the source XML and study it carefully. Perhaps you have made some assumptions about its structure that are not true? In particular, note that the XML format is different for individual Merlin projects and combined projects.


Find a dedicated XSLT editor. I have no advise for you what tool to use, since I use a Java development environment myself. That’s no reason for you to subject yourself to the same abuse, though. :-)


Download the source XML and run the XSLT engine manually. I use Saxon and Eclipse for most of my testing. Find what works well for you.


Combining Projects for Reporting

Sometimes you want to generate a report that spans multiple Merlin projects. Unfortunately, my XSLT sample assumes that you only use it on stand-alone projects and not on combined projects. In fact, my report template does not even deal well with combined projects or even nested activities.


The problem is quite easy to see when you open a single project using the option "Open XML in external editor" from the report and do the same for a combined project.


single report, source XML:


  <Project>

    <title>Some Project</title>

    ...

    <Activity ...>

      <title>some work to do</title>

    ...


Combined report, source XML


  <Project>

    <title>Untitled</title>

    <Activity ...>

      <title>Some Project</title>

      ...

      <Activity ...>

        <title>some work to do</title>

    ...


Notice how "Some Project" is the top-level name in the individual project and how it is nested in its own activity element in a combined project. You can actually see the same happening in Merlin itself, where projects are also shown as nested activities to the project, rather than top-level elements.


If you want to create a report for combined projects, you will have to rewrite some of the report XSLT to handle this better. My report template is just too basic. You could start out by changing the report to simply iterate over the team members and finding all activities that they are assigned to, instead of looking only at top level activities.

 
photo: Nick Benjaminszhttp://www.sxc.hu/profile/KillR-B
if you find this interesting, terrible or just would like to know more, e-mail memailto:kjkoster@kjkoster.org?subject=
web statistics
http://java-monitor.com/