Module of the Month: SilverGraph

Often, as a developer or product owner, it can be hard to understand the complexity of a project. A way of visualising all the relations in the project helps to understand what is going on and what is attached to what.

This is where Graphviz comes in. I won’t go into the details of installing Graphviz, as it differs for each system, but on the download page*, all environments have an installer package (for now, please see the message at the top, if you can help this awesome open source project, please do!).

Visualise your work

In itself, Graphviz is pretty complex to use, although the documentation is very good. Luckily, there’s SilverGraph to help us out. With SilverGraph in your project and Graphviz installed, getting that awesome project structure out just became a breeze.

Getting started, besides installing Graphviz, is the well known, straight-forward composer require froog/silvergraph and running a build. On top of that, you have to take one more step, namely adding

define('SILVERGRAPH_GRAPHVIZ_PATH', '/usr/local/Cellar/graphviz/2.38.0/bin');

To your _ss_environment file. Where the location of the binary may vary.

Now the fun part starts. Getting your project mapped out. As you can see below, it generates a wonderful visualisation of the framework (although quite large). I have included DataObject and inherited properties in this chart.

Mapping out the whole framework is probably not very useful for your product owner, a more useful chart would be your project. Here’s my personal website mapped out. It’s a pretty simple, straight-forward website. I rely more on trusted modules for this website, than on my own code.

It’s a simple, but functional, website. It shows all relations to external objects and maps out a clear view of what my website’s custom code actually does.

Generating a graph

After defining the path to your dot installation, I found the easiest and most effective way is to use the terminal to generate images. The browser works, but I found it outputs directly to the browser without any context, rendering the actual output often useless.

To get started, run commands as explained in the readme

framework/sake Silvergraph/png location=mysite > mysite.png

And admire the result. The location flag is to identify which part of the project should be mapped. If you don’t pass it in, the whole project, including modules, the framework, cms etc. will be mapped.

The different filetype outputs are dot, svg and png. If your project is large, using SVG or DOT can save you a lot of output. The output of mapping the whole site to PNG is almost 2MB for my simple website, whereas SVG is only 157KB! As an added bonus, SVG is endlessly scalable, so you can zoom in on the part you want to improve or reduce overhead.

The difference in file size for one of the largest projects I’ve worked on.

Sidenote, if you have Microsoft Word installed, Word will be the default application to open dot files (It's the Word template extension), but Word can’t do anything with it because it actually isn’t a Word template.

Exploring the options

On a basic run, inherited properties and DataObject itself are excluded from the output, but rest assured, they can easily be added by using the parameters relations for adding relational information, with levels 0 to 2, where 0 is the least amount and 2 is the highest amount of information.

The fields flag can be set to 0 (no fields at all) to 2, 2 shows all fields on the object, no matter where they come from (e.g. Extensions). 1 (default), prints out the object’s own properties.

Excluding certain objects is just as easy. If, for reasons undisclosed, you do not want a certain object to be mapped, simply exclude it with exclude=SiteTree**.

Communication through visualisation

The greatest asset this mapping will bring you, is the ability to clearly explain why your project is so complex, why takes so much time and why it is so expensive. It will not explain why a project has become so slow or resource heavy (there are many more factors to that). But it will help soften the blow when your project manager asks why your project has become resource heavy. As per fellow SilverStriper Stig Lindqvist:

There is no way to explain experience. You need to experience issues first hand, to understand the issue at hand.

In conclusion

I found this module very helpful in determining where the project we’re working on could be improved, have better relationship handling, etc. It also gives a great insight into the complexity of projects and helps you find pain points.

To conclude this blogpost, here’s the SilverStripe 3.6 Framework, CMS and SiteConfig

Dotted lines are extends, while direct lines are relations.

As per usual, give it a try, contribute and enjoy!

*: If you have the time and capability, please help out Graphviz:

Due to organizational changes, the Graphviz web site will see some modifications in the near future. In particular, it will probably no longer provide binary packages for Windows and Macs. The latter can be obtained via Macports or Home Brew. If someone wants to set up Appveyor for Windows, we would be grateful.

**: Yes, SiteTree contains a lot of sensitive information!

p.s: The large charts are clickable for viewing/downloading

Header image by Dani Smith