Provided by: libjifty-perl_1.10518+dfsg-3ubuntu1_all bug

NAME

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

DESCRIPTION

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

HOW TO

   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
       "jifty-devel@lists.jifty.org" 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.

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

       share/web/templates
           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'

       share/web/static
           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.

       lib/MyWeblog/Model
           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 Jifty::Manual::ObjectModel.

       lib/MyWeblog/Action
           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 logic.

       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 feeds.

       Posts

       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/Post.pm
         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/Post.pm 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.

         1;

       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.

       Posting

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

       Open a new file called lib/MyWeblog/View.pm 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');
             }
         };

         1;

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

       Viewing

       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/View.pm 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;
             $posts->unlimit;

             # 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 lib/MyWeblog/View.pm:

         template '/' => page {
             render_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 template
       called "/fragments/page_of_posts" in your lib/MyWeblog/View.pm.  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;
             $posts->unlimit;

             # Display up to three posts on the current page.
             $posts->set_page_info(
                 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) {
                 hyperlink(
                     label => 'Previous Page',
                     onclick => {
                         args => {
                             page => $posts->pager->previous_page,
                         },
                     },
                 );
             }

             # Next page link.
             if ($posts->pager->next_page) {
                 hyperlink(
                     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 Jifty!

       Hey, where did that class come from?

       You may have wondered about "MyWeblog::Model::PostCollection", since there's no file
       called PostCollection.pm. 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 details.

   Navigation
       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/Dispatcher.pm 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');
         };

         1;

       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 Jifty::Web::Menu.

   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.

MORE TUTORIALS

       ·   Managing your datastore

           Jifty::Manual::Models

       ·   Doing Stuff With Jifty

           Jifty::Manual::Actions

       ·   Using page regions

           Jifty::Manual::PageRegions

       ·   CSS and JS

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

       ·   Web Services

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

       ·   Continuations - "There And Back Again"

           Jifty::Manual::Continuations

       ·   Access Control and Security

           Jifty::Manual::AccessControl

       ·   Deploying your application in production

           Jifty::Manual::Deploying

       ·   Upgrading your application's data model

           Jifty::Manual::Upgrading

       ·   Recipes for common tasks in Jifty

           Jifty::Manual::Cookbook

GETTING HELP

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

   Browsing the wiki
       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.

REPORTING BUGS

       Please report bugs in Jifty to "jifty-devel@lists.jifty.org".