Jifty::Manual::Tutorial - Zero to Jifty in a Jiffy
This tutorial should give you everything you need to build your first application with Jifty.
Here's what you need to have installed -- at least when we write it.
No bones about it. We believe pretty strongly in the DRY (Don't Repeat Yourself) principle. That's one of the big reasons we love Perl and CPAN. Jifty makes use of lots of amazing code from CPAN. At last count, it directly depended on 60 packages from CPAN. Most of these libraries are cross-platform pure-Perl packages and should run great out of the box on any platform you can get Perl onto.
We've gone to lengths to make sure you don't spend your day downloading library after library by bundling everything we can inside the Jifty package. With luck, all you'll need to install is a few tricky libraries that actually need to be compiled for your operating system. (Little things like Perl's database interface and the embedded SQLite that Jifty defaults to.)
You can either grab a complete Jifty package from http://download.jifty.org/pub/jifty/ or install from CPAN. If you get the slim version from CPAN, you'll have to install Jifty's dependencies yourself. (Though we help out with that where we can.) If you want to get up and running quickly, grab the latest version from:
http://download.jifty.org/pub/jifty/
Either way, the installation process is the same:
# tar xzvf jifty-<version>.tgz # cd jifty-<version> # perl Makefile.PL # make # make test # make install
If the tests don't pass, we want to hear about it. Please join us on jifty-devel@lists.jifty.org and report the failure. (See "GETTING HELP" below for info on how to join the list.)
jifty-devel@lists.jifty.org
Once you have Jifty happily installed, you're ready to create your first application.
Jifty is intentionally a bit minimalist. All you really need to make an application go is a copy of the jifty commandline tool (inside your new application's bin/ directory.
Of course, it's often helpful to have a bit more structure around to help guide your work. Jifty comes with tools to build that structure for you.
Change directory to some place it will be safe to create a new Jifty application. (Jifty will create a subdirectory for you).
# jifty app --name MyWeblog Can't guess application root from current path (/your/current/directory) or bin path (/usr/bin) Creating new application MyWebLog Creating directory lib Creating directory lib/MyWebLog Creating directory bin Creating directory etc Creating directory doc Creating directory log Creating directory web Creating directory web/templates Creating directory web/static Creating directory lib/MyWebLog/Model Creating directory lib/MyWebLog/Action Creating directory t Creating configuration file MyWeblog/etc/config.yml
Let's take those one by one.
Inside bin/ is jifty, the Jifty command dispatcher. Some of the most important commands are schema, which sets up or updates your database schema and server, which starts a standalone webserver. To find out what commands your jifty comes with, run:
schema
server
jifty help
Configuration files live in etc/, though if you don't have a config file, Jifty will supply some sane defaults.
Jifty won't magically write your documentation for you, but when you write your docs, put them in doc/.
Jifty uses Log::Log4perl to configure its logging. By default, it dumps logs named server.log and error.log into the log directory.
Jifty uses HTML::Mason as its primary templating system. Put your application's templates into web/templates/. Out of the box, Jifty comes with an application skeleton that it installs in share/web/templates/. This default application is a convenient way to get a basic application up and running quickly, but probably needs some customization as you build a more advanced application.
You can find where Perl stuck Jifty's default templates with:
perl -MJifty::Util -e 'print Jifty::Util->share_root'
Some nontrivial percentage of the stuff your web application serves out doesn't need to (or shouldn't) pass through your templating engine.
Just drop your static files into web/static/ and Jifty will serve them out if it can't find a template with the right name.
Out of the box, Jifty comes with a CSS style, Javascript libraries and a Pony. Look in /usr/local/share/jifty/web/static.
For a full treatment of the Jifty object model see Jifty::Manual::ObjectModel.
To build a basic Jifty application, you only need to worry about two sorts of classes, Models and Actions.
The real base of your application lives in lib/ApplicationName/Model. Classes here define your application's data structures and how they relate to each other. Jifty will use your model classes to set up and upgrade your database's schema when it needs to.
lib/ApplicationName/Model
When we said you only need to worry about Models and Actions, we weren't telling the whole truth. Jifty will take care of basic database-interaction (CREATE, READ, UPDATE, DELETE) Actions for your Models, but they're there if you want to change anything.
CREATE, READ, UPDATE, DELETE
Jifty starts off your application with a basic harness, but can't yet write all your tests for you. (It does, however, build simple tests for model classes you generate.)
As you might imagine by the fact that this tutorial application is named MyWebLog, the example here is a simple weblog application. Future tutorials, will add authentication, comments, and RSS and Atom feeds.
Weblogs tend to center around posts, so it's no surprise that the first model to create is the post:
post
# cd MyWeblog # jifty model --name Post Writing file /tmp/MyWeblog/t/00-model-Post.t Writing file /tmp/MyWeblog/lib/MyWeblog/Model/Post.pm
Great! Now you have a Post model (not that it models anything yet).
Open lib/MyWeblog/Model/Post.pm in your favorite text editor.
You should see something like this:
package MyWeblog::Model::Post::Schema; use Jifty::DBI::Schema; # Your column definitions go here. See Jifty::DBI::Schema for # documentation about how to write column definitions. package MyWeblog::Model::Post; use base qw/MyWeblog::Record/; # Your model-specific methods go here. 1;
Now it's time to tell the model class about posts. Start by giving our post a body and a title and a category. (In a future tutorial, the application will become fully folksonomy-compliant by upgrading that category to a tags table.)
body
title
category
tags
Position your cursor right after:
# Your column definitions go here. See L<Jifty::DBI::Schema> for # documentation about how to write column definitions.
Add the lines:
column title => type is 'text', label is 'Title', default is 'Untitled post'; column body => type is 'text', label is 'Content', render_as 'Textarea';
Save your model class.
Ok. It's time to initialize MyWeblog's database. By default, Jifty sets up your application with the SQLite database engine. If you'd rather use PostgreSQL or MySQL, you need to add some content to etc/jifty.yml. (See Jifty::Config for a bit more information).
Jifty::Config
# jifty schema --setup INFO - Generating SQL for application MyWeblog... INFO - Using MyWeblog::Model::Post INFO - Using Jifty::Model::Schema INFO - Set up version v0.0.1
Ok. You have a working, if simplistic, application. Start up a webserver and have a look around. Be sure to check out the AJAX-enabled administrative UI, the online documentation browser, and the Pony.
# ./bin/jifty server INFO - You can connect to your server at http://localhost:8888/
The administrative web does give you everything you need to work with your application's data, but it's not much of a weblog.
Create a page to post a new weblog entry:
# cd web/templates/
Open a new file called post in your text editor. Make it look like this:
<%init> my $action = Jifty->web->new_action(class =>'CreatePost'); </%init> <&|/_elements/wrapper, title => "Post to your weblog" &> <% Jifty->web->form->start() %> <% Jifty->web->form->next_page( url => '/') %> <% $action->form_field('title') %> <% $action->form_field('body') %> <% Jifty->web->form->submit( label => 'Post' ) %> <% Jifty->web->form->end() %> </&>
It's really easy to get a basic listing of entries and a little bit more complex to get a pretty AJAXified paged list. Here's how to do both; you can decide which one works best for you.
Open a new file called index.html in the web/templates directory in your text editor. (Your webserver will treat the URL /index.html as the default page for your site). Make it look like this:
/index.html
<%init> my $posts = MyWeblog::Model::PostCollection->new(); $posts->unlimit(); </%init> <&|/_elements/wrapper, title => Jifty->config->framework('ApplicationName') &> <dl> % while (my $post = $posts->next) { <dt><%$post->title%></dt> <dd><%$post->body%></dd> % } </dl> </&>
The complex way involves using one of Jifty's advanced features: Page regions. These regions let your application reload page sections independently, either using AJAX on modern high-end browsers or regular GET requests with downlevel browsers such as lynx, w3m, or the browser on your mobile phone.
lynx
w3m
The downside of this approach is that each separate region needs to live in its own fragment file.
The complex way starts off about the same as the easy way. Open a new file called web/templates/index.html in your text editor. Fill it with this:
<&|/_elements/wrapper, title => Jifty->config->framework('ApplicationName') &> <% Jifty->web->region(name => "myweblog-posts", path => "/fragments/page_of_posts") %> </&>
If you're on the ball, you've probably already guessed that you need to create a file called web/templates/fragments/page_of_posts containing:
<%args> $page => 1 </%args> <%init> my $posts = MyWeblog::Model::PostCollection->new(); $posts->unlimit(); $posts->set_page_info( current_page => $page, per_page => 25 ); $m->out("No items found.") if ($posts->pager->total_entries == 0); </%init> % if ($posts->pager->last_page > 1) { Page <% $page %> of <% $posts->pager->last_page %> % } <dl class="list"> % while (my $post = $posts->next) { <dt><%$post->title%></dt> <dd><%$post->body%></dd> % } </dl> % if ($posts->pager->previous_page) { <% Jifty->web->link( label => "Previous Page", onclick => { args => { page => $posts->pager->previous_page } } ) %> % } % if ($posts->pager->next_page) { <% Jifty->web->link( label => "Next Page", onclick => { args => { page => $posts->pager->next_page } } ) %> % }
Now fire up your Jifty webserver again. Go create a post by browsing /post on your webserver.
/post
Of course, having to remember the URL to get to the posting page is a bit annoying. To get a Post button in the menu, you need to override the default menus.
Jifty's default menus live in _elements/nav in the default application template (along with the Pony). For now, override _elements/nav. (We're working on ways to make this better.)
Inside your applications web/templates directory, create a directory called _elements.
mkdir web/templates/_elements
You may want to start with the stock jifty template, in which case you only need to add the $top->child( Post... part
$top->child( Post...
cat $(perl -MJifty::Util -e 'print Jifty::Util->share_root' \ )/web/templates/_elements/nav > web/templates/_elements/nav
Otherwise, inside _elements, open up a new file called nav in your text editor and insert:
nav
<%init> my $top = Jifty->web->navigation; $top->child( Home => url => "/"); $top->child( Post => url => "/post", label => "Post Article"); </%init>
For more information about the menu system, see the documentation in Jifty::Web::Menu.
That's just about everything you need to get started building Jifty applications. We're working hard to make Jifty even easier to use and to obsolete the hard bits of this tutorial as quickly as we can.
Please join us on the jifty-devel mailing list to talk about how you're using Jifty or what you find difficult or hard to use about it.
jifty-devel
The jifty command-line application comes with builtin help.
jifty
jifty help jifty help <command>
If your server is running with administration mode enabled (the configuration file AdminMode setting is missing or non-zero), you can click the "Online Docs" link in your browser for an extensive list of per-module Jifty documentation.
AdminMode
jifty-devel@lists.jifty.org is where we discuss how we're building Jifty, what we're having trouble with and so on.
To join the list, send mail to jifty-devel-subscribe@lists.jifty.org.
jifty-devel-subscribe@lists.jifty.org
We have a wiki! (Actually, the wiki is Jifty's primary website)
Please visit http://jifty.org/, browse and contribute.
The wiki is powered by Wifty, a Wiki built on Jifty. Its code is freely available from the jifty subversion repository.
At this incredibly early stage in its life, please report bugs in Jifty to jifty-devel@lists.jifty.org.
Future tutorials include:
Access Control and Security
Upgrading your application's data model
The dispatcher in depth
Deploying your application in production
Web Services
Continuations in depth
To install Jifty, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Jifty
CPAN shell
perl -MCPAN -e shell install Jifty
For more information on module installation, please visit the detailed CPAN module installation guide.