This is a follow-up to Alias’ second round report of his “Mojo vs Dancer” contest. You can find my follow-up to the first round here.

Dancer – Bootstrapping a website

Since my review last week, a couple of new releases of Dancer hit the CPAN claiming to fix installation on Win32. Just to prove it, I’ve done this week’s testing on my conference presentation laptop instead of my desktop machine.

Dancer installed first time cleanly on the new machine. And the hello world script from last week runs correctly. So all good there.

The first round of the contest put some light on something we weren’t aware of: support for Win32 environments. Indeed, none of the core developers of the project are Windows users. We did work last week on that, and started a basic-yet-strict QA procedure to avoid test regressions.

Our GitHub repository is now splitted into two main branches: master is dedicated to prepare CPAN releases. Only documentation, packaging and bugfix commits are allowed there. New features are developed in the devel branch, and when we want to release a new major version of Dancer, we’ll start by packaging some DEVELOPER releases from the devel branch before merging it into the master branch.

So we now have a sane development/release cycle, thanks to the packaging/QA issues enlightened by Alias’ first report.

After a more-complete-than-last-week read through the main Dancer search.cpan.org page one thing jumps out quite sharply about the Dancer API in general. And this is that it isn’t object-oriented, which is something or a rare thing these days.

Indeed, this a choice that goes in the same way as Sinatra does: provide powerful, expressive and intuitive syntactic sugar to the end user to avoid as much as possible administrative code. This is – if you ask me – one of the best idea of Sinatra, and I clearly want it to be a key-feautre of Dancer.

Or at least, it doesn’t LOOK object-oriented. Judging from the distribution page there’s plenty of classes and I’m sure the internals are all done largely in an OO fashion.

You’re absolutely right, everyting inside Dancer’s internals are made in an OO fashion, Dancer::Object is the base-class of every object you can find, and some abstract class are also heavily used for engine (see Dancer::Engine, Dancer::Template::Abstract or even Dancer::Session::Asbtract if you want to see some examples).

This is also for this reason why I chose to provide access to the params and request objects through function calls, rather than forcing the user to unroll @_ in the route handlers:

For instance, this route handler…

get '/' => sub {
    my ($request) = @_;
    $request->params->{foo};
};

…becomes with Dancer syntax:

get '/' => sub {
    params->{foo};
};

So yes, Dancer is a DSL and it’s a major design choice behind the project (so don’t expect it to change in the future).

The main API that you get with “use Dancer” sports a similar kind of “Do What I Mean” command interface that reminds me a bit of the Module::Install command interface.

This means that the code to show the index template is going to look like this.

get ‘/’ => sub {
    template ‘index’;
};

I’m not entirely sure what I think about this idea, despite the fact that I’m the maintainer of M:I and created it’s Domain Specific Language inteface. This kind of thing usually raises red flags.

I can see this API strategy either descending into API chaos or becoming one of Dancer’s best and most loved features. Or quite possibly both depending on the scale of the project.

For the moment, given Dancer is meant to be taking a micro-framework approach (which should be optimised more for small websites) I’m willing to suspend my disbelief and run with it until I can make a better judgement.

Well, considering the success of Sinatra, I won’t reconsider this API choice, this to me one of the key-feature of micro-framework: allowing expressive-yet-powerful syntax. If you have to deal with objects everywhere in your application code, you can’t have the benefits of lightweight DSL syntax.

The documentation in general is oddly structured. For a command-oriented API like this I would expect to find documentation for each of the available commands. This section of the documentation does exist, but it doesn’t contain a list of all the commands.

Instead, some of the commands are described down in sub-headings related to a logical area instead. And if you look at the table of contents on the search.cpan page the logical grouping doesn’t appear very, well, logical.

There’s some other indications the documentation has built up in bits and pieces rather than being addressed in a complete fashion. Some features are glossed over quickly, leaving me a bit stumped still. Other go into way more detail than is needed for a small website to the point of information overload.

Yes, we’re totally aware of that, and we started a complete documentation rewrite in the development branch.

We target a full and complete rewrite of the docs for the next major release: 1.2. When this rewrite is complete, we’ll have the following documentation structure:

• Dancer : evry syntactic keyword will be documented here, this will be the documentation of all exported symbols
• Dancer::Tutorial will provide the user with concrete, step-by-step example in order to start working with Dancer
• Dancer::Cookbook will be a good assistant for anyone who wants to solve common issues you can face when developing a web application
• Finally, Dancer::Deployment will provide help and configuration examples for deployment issues, most of the time involving Plack and webservers

The section on config files seems to suggest I should make three config files, a global config and then a pair of development/production config files that overlay the global. And these files go in different directories for some reason, unless I “put it all at the top of the program” (without saying how I embed this YAML in the program). A bit later on I realised they meant embed via the “set” command.

This is an idea that comes from Rails, which I like and decided to port into Dancer’s conventions: You can set common and global configuration in a single file (here named config.yml. But if you want to be able to switch between different configuration contexts easily (like development to a production) then you can use environment configuration files.

When starting your Dancer app, you can choose which environment you want to enable, dancer will then first load the config.yml file, and then the environment-specific one.

This is pretty convinient for switching log levels, or even the strictness of the code. But again, all of this is optional, you can go without configuration files, putting all your settings along with your code, using – as you spoted it – the set keyword.

Overall, I think the documentation is reasonably thorough but just needs some love to clean it up into a more learning-friendly structure, with some sections shrunk down in the main Dancer page to just the most basic and common uses and references out to other pages for using more advanced features.

As I said above, this is a work-in-progress in the devel branch and should be released, if not with 1.18 (the next stable release), with 1.2.

Stuck on something I wasn’t sure about, I resorted to running the built in skeleton generator (mentioned prominently on the Dancer::Cookbook page) to at least get a better idea of what I was supposed to be doing.

C:\Users\Adam>dancer -a top100
+ top100
+ top100\views
+ top100\views\index.tt
+ top100\views\layouts
+ top100\views\layouts\main.tt
+ top100\environments
+ top100\environments\development.yml
+ top100\environments\production.yml
+ top100\config.yml
+ top100\app.psgi
+ top100\public
+ top100\public\css
+ top100\public\css\style.css
+ top100\public\css\error.css
+ top100\public\images
+ top100\public\404.html
+ top100\public\dispatch.fcgi
+ top100\public\dispatch.cgi
+ top100\public\500.html
+ top100\top100.pm
+ top100\top100.pl

For a few seconds this shocked me, because compared to the simplicity of helloworld.pl this is a lot more files.

Well, I understand it can shock you if you expect to build your app with only one Perl script, but wait, you’re asking the scaffolding script to… well scaffold something! :) So yes, it creates a full-featured application skeleton, and that’s what it’s designed for.

We could imagine some kinds of scaffolding-levels maybe though, in order to let the user choose which features they want in their scaffolded application.

At this point I hadn’t even remotely considered the idea of site-customising my error pages, and there’s 5 entirely different types of Perl application files in this list. I (newbie me) don’t even know what PSGI is, let alone why I need one. And don’t get why I have a dispatch.cgi in addition to my top100.pl script.

Frankly, I don’t even really WANT to know what all these things are (yet?). But this did at least confirm where all the files should be living and the demo app did actually start and run properly. So in my case, it solved the problem I needed to solve.

But I certainly don’t want to use it as the basis of my Top 100 site. It’s just a bit overwhelming for my level of experience, and I don’t want to have to go exploring and work out what all these different files do, so I know which ones are safe to delete.

Well, the scaffolding tool is here to makes your life easier if you want to build a full-featured application with Dancer. So yes, it provides you with any file you might need for Plack deployment, layout design, and error pages customizations. It’s designed for that actually.

Templating was largely straight forward, mostly because the docs do everything to steer me towards Template Toolkit short of installing it for me (yes, you have to install Template Toolkit yourself to get the generated skeleton website working).

I suspect the reason for this is because their embedded default templates are not PARTICULARLY featured. The documentation sums up the feature set of the built in templates as the following.

< % var1 %>

No other features are described, making Template Toolkit the obvious choice.:)

Indeed the default template engine that comes with Dancer is utterly limited, and that was also a choice. If the user wants complex template support, they have to upgrade to a powerful template engine, and CPAN has plenty of them.

I’m totally fine with this, but what I’m not entirely sure about is why on earth they have chosen to make Dancer’s default tag style for Template Toolkit different to Template Toolkit’s default tag style for Template Toolkit.

The only reason I could uncover from the documentation is that it makes TT compatible with their built in template engine. The one whose list of features is “variables”.

The only other guess other than “we like it more that way” I can make are that it’s done to be compatible with Sinatra, the Ruby toolkit I’ve never heard of but which I’m told was the inspiration for Dancer.

Yes, I must say this was a bad idea, my fault here. At the very begining of Dance’s development I was really in the idea of porting Sinatra into Perl, and I thought it should be a good idea to use the same template tags as they do in Rubyland. Time said it wasn’t, as every Perl developer expect TT to use [% %]. So we might consider going back on this, in the future, but that would mean some backward compatibility issues, which is something I want to avoid.

Switching it back to regular Template Toolkit tag style requires a slightly annoying block of config file entries I can easily imagine myself repeating in every Dancer program I will ever write.

To help you in gauging my annoyance level on this topic, allow me to show you now the complete working Dancer application at the end of this week.

#!/usr/bin/perl
 
use Dancer;
use Template;
use CPANDB {
    maxage => 3600 * 24 * 7,
};
 
# Configuration block
set template => ‘template_toolkit’;
set engines  => {
    template_toolkit => {
        start_tag => ‘[%',
        stop_tag  => '%]‘,
    },
};
 
# Route block
get ‘/’ => sub {
    template ‘index’;
};
 
dance;

Well, you could have put that in config.yml. But I agree with you, this is too much configuration for making Dancer behaving “the default TT way”. We should fix that I suppose.

It’s not a problem as such, but I’m sure it’s one of those things that’s going to niggle at me. If I wasn’t trying to emulate a newbie, I’d probably switch over to the Template::Tiny plugin in the short term. Unfortunately, it’s not particularly well known and so is probably out of bounds for this competition.

Given their strong preference for Template Toolkit, in their situation I’d probably have inlined the entire Template::Tiny package as the “house template” engine. Then you still have a direct upgrade path when people hit a feature T:Tiny didn’t support but you get to keep the default tag style. But the current predates Template::Tiny, and so be it.

I also had a momentary confusion over whether I should call my template “index” or “index.tt” or “index.html” or “index.html.tt”, but I put that mostly down to playing with Mojo’s double-dotted templates (which I’ll get to later). A quick look at the generated skeleton made it pretty clear what the naming is.

In the future, I plan to let template engines define their template extensions. So it will be less confusing for the user.

Adding the static files was very simple and easy to understand, following the convention of “if there’s a “public” directory, everything in it is a static file”.

However, I did hit a problem when I tried to add my logo image.

Weirdly, although my Dancer application was happily sending me css and my favicon.ico file, it didn’t appear to support PNG images. Bemused, I placed my first (legitimate) visit to the #dancer channel to ask a What The Hell.

Dancer uses MIME::Types under the covers, and the bug only happens on Windows, and they confirmed they can replicate it. Beyond that there’s no more information yet, but I’ve worked around the problem temporarily on my Dancer application by converting the PNG files to GIF.

And given the speed with which they chased down the previous Windows problems, I’m hopefully that by next week the problem will have gone away.

Indeed, I think we’re doomed with Windows environments ;) We have a lead though on this PNG-Win32-IE-only (!!) issue, and we coudl imagine it’s fixed by the next round, hopefully.

[...]
Overall, the process was relatively straight forward with the exception of the PNG problem and a general feel that the documentation/tools dump you in the deep end a bit too quickly and need polishing.

So as I understand it, no major issue there, except for the overkill configuration needs to get TT behaves as you expected. The documentation is being completely reorganized for the next stable release and we should fix that PNG issue pretty soon.

See you next round, and happy dancing!