Archive for the ‘Dancer’ Category

I’m blogging from the scene of destruction and havoc that used to be my apartment, but it’s currently undergoing renovation and this is what it’s turned into. There is dust everywhere, the furniture is all over the place, and I’m having trouble finding my way around. In short, it’s like a major rewrite of a large code base, but in real life.

Anyway, some renovation-shmenovation won’t stop me from continuing the initiative of monthly donations — so here we go. It has become a tradition of its own that June is the month when I support Dancer, my favorite Perl web framework, which I use both for work and for my personal projects with great joy. This year is no exception, and with my donation to the project I’m sending the well-deserved big thanks to the developers and maintainers of the project.

The second donation that I’m making this month goes to the “Friends to the Animals” Foundation, based in Katowice (whom I also support regularly — the previous time was in November last year). Their mission is to help mistreated and abandoned animals and to raise awareness of animal welfare issues, and I know they are truly dedicated to their cause. Thank you for your great work, Friends to the Animals!

Last month, while working on the POD Web View site, I developed a small Dancer plugin that lets you easily convert Markdown files into HTML content in your web application — Dancer::Plugin::Preprocess::Markdown.

The generated HTML content can be saved in a file, so that the Markdown source is only processed when it gets changed. Thus, the plugin can be used to build a poor man’s substitute for a static site generator (like Jekyll).

You’ll find the code at the usual places: CPAN and GitHub. As always, I’m looking forward to feedback/patches/forks.

When developing a Perl module, I often want to get a quick preview of the documentation that I’m writing, just to see if everything is in order and how it turns out. I used to do this the old fashioned way, by generating an HTML file with pod2html or pod2cpanhtml and opening it in a browser, but I was hoping in this day and age there is an easier and better solution, preferably a web application.

Looking around, however, the only thing I could find was the pod2html page at the CPAN Search site, which allows you to upload a POD file, have it processed by pod2html, and displayed with CPAN style. I thought it might be a good idea to try building something more user-friendly, with features like editing POD in the browser, drag and drop file uploads, etc.

And what better time for a little project like this than a weekend when you’re ill and not supposed to leave your apartment? Well, that’s what my last weekend was like — two days of coughing and coding, and here’s the result: POD Web View.

The application allows you to upload a POD file, get it from a URL, or paste its contents and edit it on the fly. The generated HTML can be displayed in the style of your choice, mimicking how it would look on CPAN, MetaCPAN, or GitHub.

I hope this will be useful for at least a few fellow Perl developers, like it already is for me. Please note that at this point this is still work in progress — the backend code needs some more work (e.g. basic sanity checks), and there are a couple UI issues that I’m aware of (and likely a dozen more that I’m not). Anyway, be my guest and give it a try, and if you’d like to report an issue, or maybe help me with the development (more than welcome), I’ve put the project up on GitHub.

Today I’m once again supporting an open source project that I’ve already donated to last year. There are many projects that I use on a regular basis or even every day, so I feel they deserve more than just a one-time donation. One of these projects is Dancer, the Perl web framework that I admire and which has been powering this site for more than two years now. Sadly, these days I don’t have as much time to contribute to the project as I had in the past (when I wrote a few Dancer plugins), so at least I’m going to help the project with my little donation.

The second of this month’s donations is to help fund the treatment of Czajka, the horse that was rescued from being sold to a slaughterhouse — as you might recall, I wrote about her last month. Medical tests revealed that Czajka suffers from a serious injury to one of her back legs which must have happened sometime in the past. She needs to undergo an operation and have the leg put in a cast, then stay in a horse hospital for two months, until the cast is ready to be removed. As you might imagine, all this costs a lot, so the Gift of Heart Foundation (who is taking care of Czajka) is accepting donations to fund it.

I hope the full amount gets raised soon and Czajka won’t have to wait much longer for her treatment to begin. If any of you, my dear readers, would like to chip in but don’t know how to proceed (because of, for instance, not understanding the Polish website of the Foundation), feel free to contact me and I’ll assist you.

In this article, we’ll develop a basic search application using Dancer andÂ Sphinx. Sphinx is an open source search engine that’s fairly easy to use, but powerful enough to be deployed in high-traffic sites, such as Craigslist and Dailymotion.

In keeping with this year’s Dancer Advent Calendar trend, the example app will be built on Dancer 2, but it should work just as well with Dancer 1.

Alright, let’s get to work.

The Data

Our web application will be used to search through documents stored in a MySQL database. We’ll use a simple table with the following structure:

Each document has an unique ID, a title, and contents, stored as both plain text and as HTML. We need the two formats for different purposes — HTML will be used to display the document in the browser, while plain text will be fed to the indexing mechanism of the search engine (because we do not want to index the HTML tags, obviously).

We can populate the database with any kind of document data — for my test version, I used a simple script to fill the database with POD documentation extracted from Dancer distribution. The script is included at the end of this article, in case you’d like to use it yourself.

When Sphinx is installed, it needs to be configured before we can play with it. Its main configuration file is usually located atÂ /etc/sphinx/sphinx.conf. For our purposes, a very basic setup will do — we’ll put the following in theÂ sphinx.conf file:

This defines oneÂ source, which is what Sphinx uses to gather data, and oneÂ index, which will be created by processing the collected data and will then be queried when we perform the searches. In our case, the source is the documents database that we just created. Thesql_query directive defines theÂ SELECT query that Sphinx will use to pull the data, and it includes all the fields from theÂ documents table, exceptÂ contents_html — like we said, HTML is not supposed to be indexed.

That’s all that we need to start using Sphinx. After we make sure theÂ searchd daemon is running, we can proceed with indexing the data. We callÂ indexer with the name of the index:

$ indexer test

It should spit out some information about the indexing operation, and when it’s done, we can do our first search:

It’s the documentation forÂ Dancer::Plugin, and it makes total sense that this is the first result for the wordÂ plugin. Sphinx setup is thus ready and we can get to the web application part of our little project.

Last month I set in motion the plan to make regular donations to open source projects and other good causes, and it’s time to do it again.

The choice of project that I’m donating to this month comes rather naturally, as it’s the project that gained most of my attention in the past twelve months, and which had a significant impact on my career — the Perl Dancer framework. Today is exactly one year since I have finished porting my website to Dancer, which was my very first experience with the framework, and through the months that followed I have used it in a number of real-life projects, developed a few plugins, and got a great contract job thanks to being experienced with it. Thank you Dancer for a great year!

The second donation that I’m making this month goes to “Last Chance”, a foundation that runs an animal shelter near Rawa Mazowiecka, my home town. I’m virtually adopting one of the dogs in the shelter — well, the choice was pretty straightforward when I saw that there was one dog that shared the first name with me! Stay strong, my dog namesake, maybe I’ll visit you one day when I’m in the neighborhood.

My first reaction was “oh come on, this is basic HTTP authentication, it’s insecure anyway and nobody would use it for any serious purpose”. But then I thought that it is, in fact, valid criticism. While I can’t do anything about the security of the authentication protocol itself (maybe except for advising people to only use it with SSL), this doesn’t mean that I shouldn’t follow the best security practices in those areas that are under my control, and how passwords are stored is one of them.

I modified the plugin to add support for hashed passwords in configuration files — it was really easy thanks to the Authen::Passphrase module, which provides an unified interface to a number of different passphrase schemes. So now you can keep your basic HTTP password secured using SHA-1, salted MD5, Blowfish, or any other scheme supported by Authen::Passphrase. Cleartext passwords still work, so backwards compatibility is maintained.

Dancer uses a simple model of interfacing with templating engines (based on Dancer::Template::Abstract) and makes it very easy to add support for new engines. Thanks to this, if you’re not happy with the default simple engine or with Template Toolkit, there is now a dozen different alternatives to choose from. Let’s take a look at some of them.

Dancer::Template::Tiny

Template::Tiny is a lightweight engine which reimplements a subset of Template Toolkit features. As the name implies, it aims to accomplish this with as little code as possible. If you’re using just the basic functionality of Template Toolkit, you should be able to switch to Template::Tiny without any modifications to template files (and you can easily go back at any moment).

Dancer::Template::Tenjin

Tenjin is a very fast templating engine with implementations for many languages — including, of course, Perl. Its great performance comes from the fact that it uses the underlying language’s constructs to process templates, instead of defining its own templating language and having to parse it. Support for this engine in Dancer is provided by Dancer::Template::Tenjin.

Dancer::Template::Haml

Haml, which stands for “HTML Abstraction Markup Language”, brings a fresh, different approach to templating. It aims at making templates short, clean, and as easy to read as well-formatted source code. Dancer::Template::Haml is a wrapper around Text::Haml and lets you use Haml templates in Dancer applications.

More

There are many more interesting templating engines ready to be used with Dancer, such as Mason (provided by Dancer::Template::Mason) or Xslate (Dancer::Template::Xslate). Do a CPAN or MetaCPAN search for “dancer template” to get a list of all the available engines, and choose the one that suits you best. In the true spirit of Perl, there’s more than one way to write a template!

A while ago I was converting a simple PHP website to Dancer, and moving it from being deployed on Apache to Starman. There wasn’t a lot of code, so rewriting went quickly — but, the site used a few specific features of Apache, namely directory indexes (courtesy of mod_autoindex) to allow user access to directories/files on the server, and htpasswd files to password-protect some of those directories.

I could just deploy the new Dancer website on Apache and keep using those goodies, but I thought that it would be nice if Dancer itself provided similar features. So, I created two plugins that do just that: Dancer::Plugin::DirectoryView and Dancer::Plugin::Auth::Htpasswd. Let me now show you how to use them.

Directory Indexes

Let’s say we have a files directory under public, and we’d like to allow users to browse it and download files. Enabling directory access is as simple as including the plugin in our Dancer application:

package MyWebApp;
...
use Dancer::Plugin::DirectoryView;

And updating the configuration file (config.yml) to tell the plugin which directory should be made available, and at which URL:

plugins:
DirectoryView:
url: /pub
root_dir: files

That’s it — now, if we launch our app and point the browser at the /pub URL, we’ll see the contents of the directory:

Protecting Directories with Htpasswd Files

As you might have noticed on the screenshot, there’s a secret directory under files. It contains some super secret data that should only be available to authorized users, so now we’re going to protect it using a htpasswd file.

First, let’s create the htpasswd file and an user, named “alice”:

$ htpasswd -c htpasswd alice

Once it is created, we need to put the htpasswd file in a safe location outside of the public directory, so let’s create a new directory passwd and store the file in there.

(If you’re migrating from Apache and already have the htpasswd file, you just need to copy it to your Dancer application.)

In our Dancer application, we include the Auth::Htpasswd plugin:

package MyWebApp;
...
use Dancer::Plugin::Auth::Htpasswd;

Now, we need to update our configuration file and add settings for the plugin. We’ll tell it to protect the /pub/secret path, and to use the htpasswd file we just created:

The plugin might be useful if you’re migrating a web application from Apache to a different HTTP server and want to keep using the same htpasswd files, or if you don’t want to keep passwords written in plain text in configuration (as it is with Auth::Basic).