Perl on Dancer: Modfile

Dancer is a RESTful framework like Sinatra but I want to use Dancer in a MVC application model because allow us to have more efficient code reusing components and separate the logic, the data management and the way the information is displayed.

What is MVC?

There are a lot of tutorials everywhere explaining what MVC is. As a quick explanation, MVC stand for Model View Controller. Model is the data, View is an interface to view the data that is changed or processed in the Controller. To know more about MVC you may read these:

The Model

This is all about this post will be: The Model. As mentioned above, the model does nothing else but data management. It does not depend of the controller or the view.

There are a lot of Perl modules to handle the data. I use Dancer::Plugin::Database which use DBI::db module, however there are others modules such as Rose::DB and Dancer::Plugin::DBIC which use DBIx::Class. I'll provide an example with Dancer::Plugin::Database and Dancer::Plugin::DBIC.

Dancer::Plugin::Database

I use Dancer::Plugin::Database for projects that do not require a complex database design. It handle the connection to the database and it support many database managers such as SQLite, MySQL, PostgresSQL, Oracle, etc... For development I use SQLite and it is the one I'll use in this post but you may consider MySQL or PostgresSQL.

First you have to do is to install the Dancer::Plugin::Database module executing this line and update the Modfile with same line. Also, make sure you have installed the module for the database manager you will use, in this case is SQLite
Configure the connection to the DB. Open environments/development.yml to add these lines to the end:
Remember to use space instead of tab in any YAML (.yml) file, Dancer will complain if you use tabs.

Create the directory db, where all the databases will be (just like Rails). Create the db/migrations directory to have the following SQL files to create the tables.

db/migration/001_up_teams.sql will be used to create the teams:
.. and db/migration/001_down_teams.sql to eliminate them:
Same for the Users, use db/migration/002_up_users.sql to create the users:
.. and db/migration/002_down_users.sql to eliminate them:
Now, lets apply those migrations:

sqlite3 db/development.sqlite < db/migrations/001_up_teams.sql 
sqlite3 db/development.sqlite < db/migrations/002_up_users.sql

If something goes wrong you can always rollback with:

sqlite3 db/development.sqlite < db/migrations/002_down_users.sql 
sqlite3 db/development.sqlite < db/migrations/001_down_teams.sql

IMPORTANT: For every statement you do in the UP sql file, you have to undo it in the DOWN sql file and in the opposite order.

In order to test your application you need to fill the database with some data. We can do that with a seeder sql file. Create the db/development.seed.sql file with this:
Confirm the database content with:

$ sqlite3 development.sqlite "SELECT * FROM Users;"
1|Johandry|Amador|johandry@company.com|1|2013-12-22 07:10:30
2|John|Smith|johnsmith@company.com|2|2013-12-22 07:10:30
3|Juan|Smith|juansmith@company.com|2|2013-12-22 07:10:30
$ sqlite3 development.sqlite "SELECT * FROM Teams;"
1|App Admin|app_admin@company.com|2013-12-22 07:09:47
2|Finance|finance@company.com|2013-12-22 07:09:47

In case you want to confirm the same from the application, create this temporal route in the lib/myapplication.pm file:
And the template views/testdb.tt with this:
IMPORTANT: You need to switch from Template::Simple to Template::Toolkit. I'll not explain this change here but basically you need to uncomment the template_toolkit lines and comment the template simple line in config.yml.

In a next post I'll write about Dancer::Plugin::DBIC but now you have at least one model to dance with.

I think the Dancer tutorial is very good explaining how to install Dancer and start your first application. However there are a few things that are not there - and should not be there either - but may be important to have in every Dancer project. Let's start up an application from scratch.

I have tested this in Linux (CentOS and Ubuntu), Mac OS (OS X Mavericks) and Cygwin on Windows but I have not tested it in Windows directly. If you have, please, share your comments about it.

Install cpanminus and update your Perl modules.

cpanminus (cpanm) is much user friendly than cpan, I really recommend to install it and also other cpanm helpers such as cpan-outdated and cpan-listchanges.

In Mac OS X you have to add to the PATH variable the directory where cpanm was installed. In my Mac OS X 10.9.1 was installed in /opt/local/libexec/perl5.12/sitebin but confirm the path before do this.

Now you have them installed it's time to update your Perl modules:

Install Dancer

With cpanm the Dancer installation is very easy:

You can use the same command to update Dancer, in case you already have it installed.

Create your application scaffold

First thing you need to have is a working or hosting directory. If this is your development environment, you can use the directory Documents/workspace inside your home directory (Windows, Linux or Mac OS). If this is a Testing or Production environment, you can use /opt/ to host your application.

Now it is time to create the application with the command 'dancer -a application_name'. Notice that I used application_name, but you can use a module name like Dancer::application_name.

Once the application scaffold is created go to the application directory and execute it.

$ cd /home/$USER/Documents/workspace
# Or go to /opt if this is not a Development environment
# cd /opt
$ dancer -a myapplication
+ myapplication
+ myapplication/bin
+ myapplication/bin/app.pl
+ myapplication/config.yml
+ myapplication/environments
+ myapplication/environments/development.yml
+ myapplication/environments/production.yml
+ myapplication/views
+ myapplication/views/index.tt
+ myapplication/views/layouts
+ myapplication/views/layouts/main.tt
+ myapplication/MANIFEST.SKIP
+ myapplication/lib
  myapplication/lib/
+ myapplication/lib/myapplication.pm
+ myapplication/public
+ myapplication/public/css
+ myapplication/public/css/style.css
+ myapplication/public/css/error.css
+ myapplication/public/images
+ myapplication/public/500.html
+ myapplication/public/404.html
+ myapplication/public/dispatch.fcgi
+ myapplication/public/dispatch.cgi
+ myapplication/public/javascripts
+ myapplication/public/javascripts/jquery.js
+ myapplication/t
+ myapplication/t/002_index_route.t
+ myapplication/t/001_base.t
+ myapplication/Makefile.PL
 
$ cd myapplication/
$ ./bin/app.pl

Open a web browser and go to: http://localhost:3000 to see the new application with a page very similar to a new Ruby on Rails application.

I like to rename the bin/app.pl file to bin/server.pl.

mv bin/app.pl bin/server.pl

Here is where most of the tutorials finish with the installation or setup but what about git?

Git setup

This is an important step. Even if you are the only developer of the project, you always must have a version control and repository for the application. You can setup a git server in other server but I recommend to use GitHub if you can or your company permit it.

Create an account in http://github.com and create a new repository. Choose the same name of your application, enter a description, check on 'Initialize this repository with a README' and select .... What???, there is Perl, Ruby and Rails but no Dancer!!!!, well .... select Perl in the 'Add .gitignore'. Click on 'Create Repository' and that's it.

In the next page there is a box at the right bottom corner with the title 'SSH clone URL'. Click on the 'copy to clipboard' icon or just copy that line. It will be something like this: git@github.com:your_github_user/myapplication.git.

Assuming that you already have git installed - if not, go to http://git-scm.com/downloads or google how to install git in your OS - go to the application directory to setup git. Execute these commands:
If you get an error about the public key (if this is your first time you will), then generate and add your key to github as explained here: https://help.github.com/articles/generating-ssh-keys

Now every time you made a change to the application you have to add the new files (if any), commit the changes and push them to github. Like this:

If you are working with a team or doing changes in different machines, you have to pull the latest changes from github before start working.
Or, if you want the code in a new machine or you want a new fresh copy just clone the application with:

To know more about git there are a lot of excellent documentation. For example:

Does Dancer have a Gemfile like Rails?

Unfortunately no, there is no such file in Dancer. However, you can make your own file, I name it Modfile and it have one module per line using the cpanm format:

#!/bin/bash

cpanm Module::Name[version]
cpanm git_repository
cpanm module.tar

Read the cpanm manual (man cpanm) to know more about this format. This is an example:

#!/bin/bash

cpanm Dancer
cpanm Dancer::Plugin::Database
cpanm Dancer::Plugin::FlashMessage
cpanm Template
cpanm Test::More                      # install Test::More
cpanm Net::SCP~1.0000                 # 1.0000 or later
cpanm Net::FTP~"&gt;= 1.0000, &lt; 2.0000"  # latest of 1.xxxx
cpanm Net::SSH2@0.9990                # specific version. same as Net::SSH2~"== 0.9990"
cpanm git://github.com/plack/Plack.git

Save the file and give it execution permission with:

chmod +x Modfile

All the Perl modules required by the application will be updated, downgraded or installed to the latest or specified version executing the Modfile file:

./Modfile

You are almost ready to start coding, let's learn some steps first and you'll be ready to dance.

Perl on Dancer

Pages

Sunday, December 22, 2013

MVC: Dancing with a Model