Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Jifty::Manual::TutoriaUser Contributed Perl DocumentJifty::Manual::Tutorial(3)

       Jifty::Manual::Tutorial - Zero to Jifty in a Jiffy

       This tutorial should give you everything	you need to build your first
       application with	Jifty.

   The requirements
       Here's what you need to have installed -- at least when we write	it.

   Installing Jifty
       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 100 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.	 The Jifty installer is	capable	of determining what modules
       your system needs, and downloading and installing them all in one go.
       Don't worry, it will ask	you first before it makes any changes.

       On most systems you can use Perl's bundled CPAN module to download and
       install Jifty:

	 # perl	-MCPAN -e'install Jifty'

       If you've downloaded a ".tar.gz"	of Jifty, you can do a manual install:

	 # 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
       "" and report	the failure. (See "GETTING
       HELP" below for info on how to join the list.)

   Setting up the Scaffolding
       Once you	have Jifty happily installed, you're ready to create your
       first application.

       All you really need to make an application go is	a copy of the jifty
       command-line 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
	 Creating new application MyWeblog
	 Creating directory MyWeblog/lib
	 Creating directory MyWeblog/lib/MyWeblog
	 Creating directory MyWeblog/bin
	 Creating directory MyWeblog/etc
	 Creating directory MyWeblog/doc
	 Creating directory MyWeblog/log
	 Creating directory MyWeblog/var
	 Creating directory MyWeblog/var/mason
	 Creating directory MyWeblog/share
	 Creating directory MyWeblog/share/po
	 Creating directory MyWeblog/share/web
	 Creating directory MyWeblog/share/web/templates
	 Creating directory MyWeblog/share/web/static
	 Creating directory MyWeblog/lib/MyWeblog/Model
	 Creating directory MyWeblog/lib/MyWeblog/Action
	 Creating directory MyWeblog/t
	 Creating configuration	file MyWeblog/etc/config.yml

       Let's take those	one by one.

       lib Inside lib/ is where	all of your application	Perl code goes.	Your
	   application generally consists of a set of classes.

       bin Inside bin/ is jifty, the Jifty command dispatcher. The most
	   important command is	"jifty server" which starts a standalone
	   webserver. To find out what commands	your jifty comes with, run:

	       jifty help

       etc Configuration files live in etc/. Jifty generates a basic config
	   file	for your application, etc/config.yml.

       doc Jifty can't magically write your documentation for you, but when
	   you write your docs,	put them in doc/.

       log Jifty uses Log::Log4perl to configure its logging. By default, it
	   dumps logs named server.log and error.log into the log/ directory.

       var Jifty stores	cache files here while the server is running. You
	   shouldn't ever have to touch	this directory.

	   Jifty supports internationalization.	share/web/po/ is where your
	   translations	("portable object templates") will go.

	   Though modern Jifty applications are	encouraged to use
	   Template::Declare for templating, we	also support HTML::Mason
	   templates. Put your application's Mason templates in
	   share/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	-le 'print Jifty::Util->share_root'

	   Some	nontrivial percentage of the content your web application
	   serves out doesn't need to (or shouldn't) pass through your
	   templating engine. This includes, for example, images.

	   Just	drop your static files into share/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 plenty of CSS stylesheets,
	   JavaScript libraries, and even a Pony. Look in share/web/static in
	   the Jifty distribution, or in the same place	Jifty stuck its
	   default templates.

	   The real base of your application lives in "lib/MyWeblog/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.

	   For a full treatment	of the Jifty object model see

	   Actions are an API for your model classes. One way you might	think
	   of them is that an action is	an HTML	form, but generalized. Jifty
	   will	generate basic database-interaction ("CREATE", "READ",
	   "UPDATE", "DELETE") Actions for your	Models on-the-fly.

	   You can also	create your own	actions	for any	kind of	application

       t   Jifty starts	off your application with a basic harness, but can't
	   yet write all your tests for	you. It	does, however, build some
	   simple tests	for model and action classes you generate.

   Building your data model
       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


       Weblogs tend to center around posts, so it's no surprise	that the first
       model to	create is the "post":

	 # cd MyWeblog
	 # jifty model --name Post
	 Writing file /tmp/MyWeblog/lib/MyWeblog/Model/
	 Writing file /tmp/MyWeblog/t/00-model-Post.t

       Great! Now you have a Post model	(not that it models anything yet).

       Open lib/MyWeblog/Model/ in your favorite	text editor.

       You should see something	like this:

	 use strict;
	 use warnings;

	 package MyWeblog::Model::Post;
	 use Jifty::DBI::Schema;

	 use MyWeblog::Record schema {


	 # Your	model-specific methods go here.


       Now it's	time to	tell the model class about what	comprises a post.
       We'll start out by giving our post a "body" and a "title". (In a	future
       tutorial, the application will become fully folksonomy-compliant	by
       adding a	"category" and upgrading that "category" to a "tags" table.)

       Position	your cursor right after:

	 use MyWeblog::Record schema {

       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.

       Don't be	mistaken, these	are lines of actual Perl code. Jifty provides
       you with	a human-readable language for declaring	your models' columns.

   Starting the	Jifty application server
       You now have a working, if simplistic, application. Start up the	Jifty
       web server by typing "jifty server". For	some platforms,	you may	have
       to type "./bin/jifty server".

       The first thing you'll see is that Jifty	notices	you have no database,
       so it creates one for you. 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/config.yml. See
       Jifty::Config for a bit more information.

	   # jifty server
	   WARN	- Application schema has no version in the database.
	   WARN	- Automatically	creating your database.
	   INFO	- Generating SQL for application MyWeblog...
	   INFO	- Using	MyWeblog::Model::Post, as it appears to	be new.
	   INFO	- Using	Jifty::Model::Session, as it appears to	be new.
	   INFO	- Using	Jifty::Model::Metadata,	as it appears to be new.
	   INFO	- Set up version 0.0.1,	jifty version 0.81208
	   INFO	- You can connect to your server at http://localhost:8888/

       Everything but the last line was	database setup information that	you'll
       only see	when Jifty changes your	database.

       The last	line tells you the URL you can go to with your web browser.
       Have a look around. Be sure to check out	the AJAX-enabled
       administrative UI, the online documentation browser, and	the Pony.

   Building a user interface
       The administrative web does give	you everything you need	to work	with
       your application's data.	You can	create,	update,	and delete posts.
       However,	it's not much of a weblog.


       Let's start building our	user interface with a page to create new

       Open a new file called lib/MyWeblog/ in your text	editor.	Make
       it look like this:

	 package MyWeblog::View;
	 use strict;
	 use warnings;
	 use Jifty::View::Declare -base;

	 template post => page { title => 'Post	Entry' } content {
	     my	$action	= new_action(class => 'CreatePost');

	     form {
		 render_action $action;
		 form_submit(label => 'Post');


       Jifty provides very concise syntax for generating HTML using
       Template::Declare. We'll	see plenty more	soon.


       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.

       The quick and dirty way

       Open your lib/MyWeblog/ file and add this	between	the "post"
       template	and the	"1;" at	the very end of	the file:

	 template '/' => page {
	     # Get all posts.
	     my	$posts = MyWeblog::Model::PostCollection->new;

	     # Display each post in a <dl>.
	     dl	{
		 while (my $post = $posts->next) {
		     dt	{ $post->title }
		     dd	{ $post->body  }

       Now when	you go to "http://localhost:8888", you'll be greeted with all
       of your blog posts.

       The complex way that gets you lots of cool toys

       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" and "w3m".

       The downside of this approach is	that each separate region needs	to
       live in its own template. Happily, this is a good design	practice even
       without regions.

       The complex way starts off about	the same as the	easy way. Replace (or
       add, if you shied away from simplicity) the "/" template	in your

	 template '/' => page {
		 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	template called	"/fragments/page_of_posts" in your
       lib/MyWeblog/  Make it contain the following:

	 template '/fragments/page_of_posts' =>	sub {
	     # Retrieve	the current page argument, defaulting to 1.
	     my	$page =	get('page') || 1;

	     # Get all posts.
	     my	$posts = MyWeblog::Model::PostCollection->new;

	     # Display up to three posts on the	current	page.
		 current_page => $page,
		 per_page     => 3,

	     # Notify the user what page they're on if there are multiple.
	     if	($posts->pager->last_page > 1) {
		 p { "Page $page of " .	$posts->pager->last_page }

	     # Display the current page	of posts.
	     dl	{
		 attr {	class => 'list'	};

		 while (my $post = $posts->next) {
		     dt	{ $post->title }
		     dd	{ $post->body  }

	     # Previous	page link, the 'page' argument here will set a new value when
	     # this region is invoked again.
	     if	($posts->pager->previous_page) {
		     label => 'Previous	Page',
		     onclick =>	{
			 args => {
			     page => $posts->pager->previous_page,

	     # Next page link.
	     if	($posts->pager->next_page) {
		     label => 'Next Page',
		     onclick =>	{
			 args => {
			     page => $posts->pager->next_page,

       Now fire	up your	Jifty webserver	again. Browse to "/post" and create
       more than three posts. Return to	the home page and check	out the	nifty
       AJAX "Next Page"	and "Previous Page" links you now have.	Turn off
       JavaScript or view the page in "lynx", and notice how the AJAX
       automatically falls-back	to page	loads for you. All for free, thanks to

       Hey, where did that class come from?

       You may have wondered about "MyWeblog::Model::PostCollection", since
       there's no file called Jifty uses Jifty::ClassLoader
       to auto-generate	a bunch	of classes for you. Of course, you can
       override	these definitions if you like. See Jifty::ClassLoader for more

       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.

       We're going to set up a dispatcher for your weblog. A dispatcher
       handles "doing things" based on the URL of each incoming	request. We
       can set up additional menu items	by adding them in a "before rendering
       any template" dispatcher	rule.

       Open up a new file called lib/MyWeblog/ and	stick this
       content into it:

	 package MyWeblog::Dispatcher;
	 use strict;
	 use warnings;
	 use Jifty::Dispatcher -base;

	 before	'*' => run {
	     my	$top = Jifty->web->navigation;
	     $top->child(Home => url =>	'/');
	     $top->child(Post => url =>	'/post', label => 'Post	Article');


       Jifty provides nice syntax (yet again!) for declaring dispatcher	rules.
       For more	information about dispatching, see Jifty::Dispatcher. For more
       information about the menu system, see the documentation	in

   That's it!
       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.

       o   Managing your datastore


       o   Doing Stuff With Jifty


       o   Using page regions


       o   CSS and JS

	   Jifty::Manual::UsingCSSandJS, Jifty::Manual::JavaScript

       o   Web Services

	   See Jifty::Manual::TutorialRest for a quick overview.

       o   Continuations - "There And Back Again"


       o   Access Control and Security


       o   Deploying your application in production


       o   Upgrading your application's	data model


       o   Recipes for common tasks in Jifty


   Online Help
       The "jifty" command-line	application comes with builtin help.

	 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.

   Joining the mailing list
       "" 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 "".

   Browsing the	wiki
       We have a wiki! (Actually, the wiki is Jifty's primary website)

       Please visit <>, browse	and contribute.

       The wiki	is powered by Wifty, a Wiki built on Jifty. Its	code is	freely
       available from the Jifty	subversion repository.

       Please report bugs in Jifty to "".

perl v5.32.1			  2013-01-29	    Jifty::Manual::Tutorial(3)


Want to link to this manual page? Use this URL:

home | help