Ruby, Scripting, Web Applications

Semi-static CMSs

You know you have a good idea when there are half a dozen implementations of it. All essentially the same but filled with subtle nuance. The latest idea I have stumbled across is the “semi-static” website generator. The idea is so painfully obvious I cannot believe that it has taken us until 2009 to do it properly.

What is a semi-static website? Well it’s actually something like this blog. I spend ages writing and editing the articles but once I publish something I don’t generally change it unless it has factual errors. I need something that allows me to make changes but my content easily but my content doesn’t really benefit in anyway from being stored in a database or being generated dynamically on the fly because it is going to spend most of its life not being changed.

If you look at a lot of CMS systems the same is true. People want to be able to edit and reorganise material easily but they are rarely changing it more than once a week. The majority of the time the pages are static.

If you look at a number of CMS or Wiki systems they are actually quite complicated. Before you can get going and generate your content (which remember is the core of what you want to do) you might have to setup a database and get the application deployed to a webserver.

What the semi-static website generator does is provide a set of scripts that allow you to edit and create content and then “compile” your site. The result is set of static HTML, Javascript and CSS files that can be deployed to your static webserver (which is generally pretty easy to setup, most servers will come with Apache all ready to go).

When you combine it with a bit of DVCS magic deployment is even easier. You just checkin your new pages and then update the webserver copy of the content.

So if you want to get into this kind of content management what options do you have? Well you have a lot of choice indeed. Almost all of them are Ruby projects and they have a certain similarity to the Rails concept of code generation. You will be issuing commands like “create page”, “build site” and so on. You operate at one remove from it.

There are many, many, many choices but for myself I chose three to look at Nanoc, Webby and Jekyll. Nanoc I came across via Proggit and was struck by the simplicity and clarity of the documentation.

Installation of all three is via gems but there are some differences here. Nanoc is a very simple Gem and works with HTML and Erb by default, if you want to use a markup language or different templating language you will have to install the gem yourself. This means it also installs easily under JRuby too.

Webby by comparison is a very noisy install, I think it may have its dependencies slightly wrong as it installs a version of rake, flexmock and rspec which are surely development dependencies rather than anything I as a user would need to use for the framework. It also uses hpricot which means you can’t install it under JRuby.

Jekyll has a similarly demanding set of requirements but will install under JRuby. Jekyll did feel a lot like a personal solution as I was installing it. Textile is great but if I am going to be using Markdown why do I need to install RedCloth?

Overall I liked the nanoc install experience most.

Moving on to using them. Nanoc and Webby are very similar in that they use generators to create new elements in the site. Jekyll seems to use convention instead. At this point it is worth mentioning that there are some big differences between the three products in their intentions. Nanoc is a general website creator but it does have a certain amount of opinion as to how to do that. For example it generates very nice clean website urls by putting each page in a directory by itself and then creating the page as an index.html page within that directory. Make sure you have your webserver configured appropriately.

Webby is pretty flexible but comes with some built-in templates that will be build you a basic page, a tumblog style site, a normal blog and a presentation. That was a pretty neat feature and one the other frameworks didn’t have.

However the negative side to this is that the templating is based on Blueprint; which is both excellent as Blueprint is a great way of designing pages and a pain as Blueprint is actually pretty involved in terms of understanding the grid concept and what the various span-x css classes translate to. I felt that Webby did a great job of offering cross-browser styling that looked good but that in doing so it didn’t make the simple stuff simple. With my trial site my sidebar came out on the bottom of the page and I didn’t really know how to get on the right-hand side of the page. In nanoc I could just float: right it, in Webby I felt I had to understand the grid that had been created for me. I’m not sure it really allowed you to use any CSS knowledge someone might already have but the benefit is you know your site is going to look good across browsers and in print and so on. For more professional site development this might actually sway you to select Webby.

Jekyll is primarily a tool for publishing a blog style site so it has a lot of built-in support for special information relating to posts but in terms of layouts it uses general HTML templating like Nanoc does. It allows  for the creation of little chunks of reusable content across pages via includes but lacks some of the flexibility of Nanoc’s tag helpers. While focussing on blog publishing Jekyll actually encompasses a powerful set of processing tools for content that effectively allows you to use it as CMS. Jekyll is used to process GitPages on GitHub, a real demonstration of its power beyond just blogging.

For what I wanted to do I initially felt that Nanoc was the best choice, it’s flexible, powerful and generates nice sites. Webby is powerful but didn’t expose that power to me in a way that made me feel in-control. However when I started to get to grips with Jekyll I was really amazed at how powerful the use of a few conventions were. Jekyll processes your site’s pages effectively in-place. It can choose to process your files if they match a naming convention (such as having a content extension like textile or markdown) and it uses an embedded YAML section in the file to do things like provide the title of the page or select the layout that the content should be displayed within. While Nanoc produces fancy URLs Jekyll made it easy to build more conventional websites consisting of clusters of pages.

Jekyll uses a small number of special directories (indicated by a leading underscore) to hold things like layouts, cross-page snippets and posts (if you are using the dated posting functionality). However for a simple site the number of directories and configuration files was significantly less than Nanoc. In fact you could get by with just a master page layout, which would require just one special directory and page within it. Everything that should have been simple was with Jekyll and the result was very close to a conventional website you might have coded by hand but extremely fast to create. It also uses just one command to press the pages and fire up a local server to view the pages. Both Webby and Nanoc seemed to make pressing and previewing slightly harder than it needed to be and at least once I forget to execute the Nanoc commands in the right order.

So, conclusions… Going forward I will be using both Nanoc and Jekyll. Webby I would be willing to consider but I don’t really have a task for it that would reward the additional effort I have to invest in its capabilities. If I just want to bang out pages for a website but minimise my effort and make it easy to abstract common content then I will definitely be using Jekyll. It is a joy to use. For sites that are maybe more based around articles or grouped content then I think I will be using Nanoc. The default URL construction is nice for hierarchical data (as long as you can stand the many directories) and there’s a sense that the configuration files make it easy to make changes that affect the site as a whole. However it does use a lot of scaffolding to achieve the effect and there are a lot of exposed options that could have been reduced by adopting some conventions Jekyll style.

Groovy, Java, Programming, Scripting, Software

Working with Groovy Tests

For my new project Xapper I decided to try and write my tests in Groovy. Previously I had used Groovy scripts to generate data for Java tests but I was curious as to whether it would be easier to write the entire test in Groovy instead of Java.

Overall the experience was a qualified “yes”. When I was initially working with the tests it was possible to invoke them within Eclipse via the GUnit Runner. Trying again with the more recent 1.5.7 plugin, the runner now seems to be the JUnit4 one and it says that it sees no tests, to paraphrase a famous admiral. Without being able to use the runner I ended up running the entire suite via Gant, which was less than ideal, because there is a certain amount of spin-up time compared to using something like RSpec’s spec runner.

I would really like all the major IDEs to get smarter about mixing different languages in the same project. At the moment I think Eclipse is the closest to getting this to work. NetBeans and Intellij have good stories around this but it seems to me to be a real pain to get it working in practice. I want to be able to use Groovy and Java in the same project without having Groovy classes be one of the “final products”. NetBeans use of pre-canned Ant files to build projects is a real pain here.

Despite the pain of running them though I think writing the tests in Groovy is a fantastic idea. It really brought it home to me, how much ceremony there is in conventional Java unit test writing. I felt like my tests improved when I could forget about the type of a result and just assert things about the result.

Since I tend to do TDD it was great to have the test run without having to satisfy the compiler’s demand that methods and classes be there. Instead I was able to work in a Ruby style of backfilling code to satisfy the runtime errors. Now some may regard this a ridiculous technique but it really does allow you to provide a minimum of code to meet the requirement and it does give you the sense that you are making progress as one error after another is squashed.

So why use Groovy rather than JRuby and RSpec (the world’s most enjoyable specification framework)? Well the answer lies in the fact that Groovy is really meant to work with Java. Ruby is a great language and JRuby is a great implementation but Groovy does a better job of dealing with things like annotations and making the most of your existing test libraries.

You also don’t have the same issue of context-switching between different languages. Both Groovy and Scala are similar enough to Java that you can work with them and Java without losing your flow. In Ruby, even simple things like puts versus println can throw you off. Groovy was created to do exactly this kind of job.

If the IDE integration can be sorted out then I don’t see any reason why we should write tests in Java anymore.

Programming, Ruby, Scripting, Web Applications

Sinatra example

Since the Sinatra Project website currently seems to have been hijacked and directed to spam (the RubyForge page seems to be fine and is still a good introduction in its own right) I wanted to post an example of how to get going with Sinatra and also to highlight what makes it such a different approach to web frameworks. Here’s the example code on CodeDumper.

I wrote this with JRuby (for the cross-platform win). You’ll need to install the Sinatra, Haml and Mongrel Gems to get it to run.

It uses two styles, first there is the REST-ful extraction of parameters from the url and then there is the form POST submission. In both cases the code is pretty much the same as Sinatra extracts all parameters into the params hash.

I’ve inlined the Haml to make the example simple but normally the view templates would be extracted out of the code into separate files.

Sinatra is sometimes described as being as a web DSL rather than a web framework, it seems apt as it eschews MVC separation but instead by attaching code to routes directly it allows Controller code to be tiny and to delegate appropriately rather than putting in a heavyweight structure that might result in more frameworking code than actual “doing” code.

However one of the things I really like is something you can’t show in a code fragment and that is the ability to dynamically interact with your web application on the fly. Start up Sinatra, change the code of the file you’re running and your changes are reflected immediately. End the compile, deploy, view cycle! It kind of makes web programming fun again.

Programming, Ruby, Scripting, Web Applications

Sinatra and Haml

On Monday I was meant to be learning how to use the Grails framework (following up the impressive Grails site that Sky has launched) but I instead got distracted into scratching another itch, using Sinatra with JRuby. Since I was doing a little REST application I thought I would also give Haml a go as it promised a far easier way of generating HTML responses.

Installing both Gems was easy as ever and Sinatra was really easy to understand conceptually. Put the HTTP method name, the URI pattern you want to match and then the return value of the block is what goes back to the client in the response.

So for example to map “/hello” to the plain text response “Hello World” you simply have.

get "/hello" do
  "Hello World"

Fire up the script (with necessary requires) and a HTTP server is set up and running. It really couldn’t be simpler. You can use a :symbol in the URI matcher and then access it through the params hash. Within half an hour I was starting to add resources into my served HTML and I felt like master of the REST UNIVERSE.

Sinatra is a really smart piece of code that makes it simple to write a basic web application. I have loads of ideas of how it could be useful but one of my first thoughts was that it actually does a good job of solving the issue of GUI platforms.

My next project is to see how it works with posting data back to the app but on the face of it it all seems straight-forward.

Haml is another story. It is undoubtedly a good idea and on the right track. A DSL for creating HTML the method html for example creates a block html tag  while p “Hello World” creates a paragraph tag with the parameter as the content. Hash parameters sent to the method become attributes of the class.

It is much quicker than generating the HTML by hand but often not by much. That is because Haml has not found the same easy metaphor for code and content that Sinatra has. It is very picky, constantly harping about two-space indentation (no more, no less, don’t dare use tabs you bastardo!) for example, it sometimes throws a stack trace that failed to make it to Sinatra leading to a blank screen on the browser and hunt into the console for a clue as to what has gone wrong.

The documentation is to poor to figure out why the library doesn’t accept what you are doing and I am still baffled as to whether the module handles inline tags or whether you are meant to devolve all of that to Textile. Passing parameters to Haml templates seems unnecessarily complex (the only way I could get it to work is with normal string interpolation, it’s a solution but it seems to break the DSL concept) and mixing inline formatting with parameters baffles me still.

Haml makes more sense to me than RHTML style templating but its claim to simplicity and enjoyment seems to come only with a deep understanding and long experience with using it. It took me 20 minutes to fall in love with Sinatra but it took 20 minutes for me to get a working Haml page. And I didn’t enjoy myself doing it.

Groovy, Java, Python, Ruby, Scripting

Groovy or JRuby?

Martin Fowler blogged about the question a couple of days ago and ever since I have pondering that maybe it is not really the right question to ask.

I currently toodle between Jython, JRuby and Groovy for various reasons and I am an expert in none. The interesting thing I have found is that it is hard to pick one and just focus on that. To some extent they overlap heavily: they are all cross-platfrom, they are all dynamic, they all integrate with Java API stack I’ve committed to memory.

The first thing to say is that I am interested in scripting languages for prototyping and admin style scripting. I have never used Rails and the Grails data-model means that you need a specific kind of project to work on. If you want to use a particular product and that is only on one platform then that kind of makes your decision for you.

Each language has its own strengths, from my point of view I would categorise them in the following way. Jython has Python’s readability and solid language design, JRuby has Sun’s support, excellent community contributed library code and is very dynamic, Groovy is mini-Java, so it’s easy to learn and most importantly it has a functioning interactive console.

The last point might seem a bit weird, what about jirb and jython‘s interactive mode? Well Martin makes a very important point in his post about the purpose of these ports. Both JRuby and Jython aim to stay faithful to their source languages and be able to run code from their parent C implementations while expanding the API by accessing the Java libraries. Groovy on the other hand stays close to Java syntax and is the only one of the three that allows you to cut and paste code from a regular Java application and then play around with it in an interactive session. That is a very powerful and compelling feature.

Almost all the Groovy I do either comes from wanting to leverage or understand a piece of Java code.

All my Jython work on the other hand is about wanting to automate administration or manual tasks in a clear and concise fashion. Python’s dynamic data structures help, but so does zxJDBC the Jython specific database library that mixes DBI with JDBC to create a highly portable but simple database connectivity solution with no boilerplate!

JRuby on the other hand is something that only really comes up because Alpha Geeks love it. The syntax is gnarled and there is a significant learning curve before someone from a Java background can get “The Ruby Way” of things. The new integration of JRuby into NetBeans though makes developing in the language a comparative snap and I would suspect that JRuby will be a valid choice of application development language alongside Java now. The choice will be driven by the problems you are trying to solve not because one language is inherently “better” than the other.