[Jifty-commit] r6876 - jifty/trunk/lib/Jifty/Manual
Jifty commits
jifty-commit at lists.jifty.org
Thu Apr 23 12:23:56 EDT 2009
Author: c9s
Date: Thu Apr 23 12:23:55 2009
New Revision: 6876
Modified:
jifty/trunk/lib/Jifty/Manual/Tutorial_zhtw.pod
Log:
- update the untranslated part of zhtw tutorial from tutorial.pod
Modified: jifty/trunk/lib/Jifty/Manual/Tutorial_zhtw.pod
==============================================================================
--- jifty/trunk/lib/Jifty/Manual/Tutorial_zhtw.pod (original)
+++ jifty/trunk/lib/Jifty/Manual/Tutorial_zhtw.pod Thu Apr 23 12:23:55 2009
@@ -104,22 +104,33 @@
Jifty uses L<Log::Log4perl> to configure its logging. By default, it
dumps logs named F<server.log> and F<error.log> into the F<log> directory.
+=item var
+
+Jifty stores cache files here while the server is running. You shouldn't ever
+have to touch this directory.
+
+=item share/web/po
+
+Jifty supports internationalization. F<share/web/po/> is where your
+translations ("portable object templates") will go.
+
=item share/web/templates
-Jifty uses L<HTML::Mason> as its primary templating system. Put
-your application's templates into F<share/web/templates/>. Out of
-the box, Jifty comes with an application I<skeleton> that it installs
-in F<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.
+Though modern Jifty applications are encouraged to use L<Template::Declare>
+for templating, we also support L<HTML::Mason> templates. Put your
+application's Mason templates into F<share/web/templates/>. Out of the
+box, Jifty comes with an application I<skeleton> that it installs in
+F<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'
+ perl -MJifty::Util -le 'print Jifty::Util->share_root'
=item share/web/static
-Some nontrivial percentage of the I<stuff> your web application serves
+Some nontrivial percentage of the content your web application serves
out doesn't need to (or I<shouldn't>) pass through your templating
engine.
@@ -130,27 +141,22 @@
Pony. Look in F<share/web/static> in the Jifty distribution, or in the same
place Jifty stuck its default templates.
-=item lib/MyWeblog
-
-For a full treatment of the Jifty object model see
-L<Jifty::Manual::ObjectModel>.
-
-To build a basic Jifty application, you only need to worry about two
-sorts of classes, B<Models> and B<Actions>.
-
=item lib/MyWeblog/Model
The real base of your application lives in
-C<lib/B<ApplicationName>/Model>. Classes here define your application's data
-structures and how they relate to each other. Jifty will use your model
+C<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
+L<Jifty::Manual::ObjectModel>.
+
=item lib/MyWeblog/Action
-When we said you only need to worry about B<Models> and B<Actions>,
-we weren't telling the whole truth. Jifty will take care of basic
-database-interaction (C<CREATE, READ, UPDATE, DELETE>) B<Actions> for
-your B<Models>, but they're there if you want to change anything.
+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 (C<CREATE>, C<READ>, C<UPDATE>, C<DELETE>) B<Actions> for
+your B<Models> on-the-fly.
=item t
@@ -158,11 +164,6 @@
all your tests for you. (It does, however, build simple tests for model
classes you generate.)
-=item var
-
-Jifty stores cache files here while the server is running. You shouldn't ever
-have to touch this directory.
-
=back
=head2 Building your data model
@@ -225,67 +226,64 @@
Save your model class.
-=head2 Setting up the database
-
-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 F<etc/config.yml>. (See L<Jifty::Config>
-for a bit more information).
-
- # jifty schema --setup
- 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.80913
- Jifty version 0.80913 up to date.
- ...
- MyWeblog version 0.0.1 up to date.
-
=head2 Starting the Jifty application server
-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/
+You now have a working, if simplistic, application. Start up the Jifty web
+server by typing C<jifty server>.
-Please always run this command at the root directory of your Jifty applications,
-or you'll be caught by a lot of errors.
+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 F<etc/config.yml>. (See L<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.
-For many platforms, a simple "jifty server" command works too. :)
+For some platforms, you may have to type "./bin/jifty server".
=head2 Building a user interface
The administrative web does give you everything you need to work with your
-application's data, but it's not much of a weblog.
+application's data. You can create, update, and delete posts. However, it's not
+much of a weblog.
=head3 Posting
-Create a page to post a new weblog entry:
+Let's start building our user interface with a page to create new posts.
- # cd share/web/templates/
-
-Open a new file called F<post> in your text editor. Make it look like this:
+Open a new file called F<lib/MyWeblog/View.pm> 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() %>
- </&>
-
-Yes, it's a template file in L<HTML::Mason> syntax. If you're not familiar with Mason,
-we recommend you to consult its online documentation for details. I<Mason templates
-should start in the first column of the file. Particularly importantly, the C<E<lt>%initE<gt>>
-and C<E<lt>/%initE<gt>> blocks must be flush left.>
+ 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;
=head3 Viewing
@@ -293,127 +291,145 @@
complex to get a pretty AJAXified paged list. Here's how to do both; you can
decide which one works best for you.
-(If you cut and paste the code in the examples below, make sure it's
-lined up in column 1, or it won't work.)
-
=head4 The quick and dirty way
-Open a new file called F<index.html> in the F<share/web/templates> directory
-in your text editor. (Your webserver will
-treat the URL C</index.html> as the I<default> page for your site). Make it
-look like this:
+Open your F<lib/MyWeblog/View.pm> file and add this between the C<post>
+template and the "1;" at the very end of the file:
- <%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>
- </&>
+ 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 }
+ }
+ }
+ };
-(Make sure to remove that leading whitespace!)
+Now when you go to C<http://localhost:8888>, you'll be greeted with all of
+your blog posts.
=head4 The complex way that gets you lots of cool toys
-The I<complex way> involves using one of Jifty's advanced features: I<Page
-regions>. These regions let your application reload page sections
+The I<complex way> involves using one of Jifty's advanced features:
+I<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 C<lynx>, C<w3m>, or the browser on
-your mobile phone.
+requests with downlevel browsers such as C<lynx> and C<w3m>.
The downside of this approach is that each separate region needs to live in
-its own I<fragment> file.
-
-The complex way starts off about the same as the easy way. Open a new file
-called F<share/web/templates/index.html> in your text editor. Fill it with this:
+its own template. Happily, this is a good design practice even without regions.
- <&| /_elements/wrapper, title => Jifty->config->framework('ApplicationName') &>
-
- <% Jifty->web->region(name => "myweblog-posts",
- path => "/fragments/page_of_posts") %>
- </&>
+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
+F<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 file called F<share/web/templates/fragments/page_of_posts> containing:
+a template called C</fragments/page_of_posts>. 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,
+ },
+ },
+ );
+ }
+ };
- <%args>
- $page => 1
- </%args>
- <%init>
- my $posts = MyWeblog::Model::PostCollection->new();
- $posts->unlimit();
- $posts->set_page_info( current_page => $page,
- per_page => 15
- );
- $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 C</post>
-on your webserver. Create more than 15 posts, and notice how Jifty gives you
-AJAX C<Next Page> and C<Previous Page> buttons for you. 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!
+Now fire up your Jifty webserver again. Browse to C</post> and create more than
+three posts. Return to the home page and check out the nifty AJAX C<Next Page>
+and C<Previous Page> links you now have. Turn off javascript or view the page
+in C<lynx>, and notice how the AJAX automatically falls-back to page loads for
+you. All for free, thanks to Jifty!
=head3 Hey, where'd that class come from?
-If you're paying attention, you may have wondered about C<MyWeblog::Model::PostCollection>,
-since there's no file called F<PostCollection.pm>. By default, Jifty uses
-C<Jifty::ClassLoader> to auto-generate a bunch of classes for you. Of course,
-you can override these definitions if you like. See L<Jifty::ClassLoader> for more details.
+You may have wondered about C<MyWeblog::Model::PostCollection>, since there's
+no file called F<PostCollection.pm>. Jifty uses C<Jifty::ClassLoader> to
+auto-generate a bunch of classes for you. Of course, you can override these
+definitions if you like. See L<Jifty::ClassLoader> for more details.
=head2 Navigation
Of course, having to remember the URL to get to the posting page is a bit
-annoying. To get a B<Post> button in the menu, you need to override the default
+annoying. To get a B<Post> button in the menu, you need to override the default
menus.
-Jifty's I<default> menus live in F<_elements/nav> in the default application
-template (along with the Pony). For now, override F<_elements/nav>. (We're
-working on ways to make this better.)
-
-Inside your applications F<share/web/templates> directory, create a directory called
-F<_elements>.
-
- mkdir share/web/templates/_elements
-
-You may want to start with the stock jifty template, in which case you
-only need to add the C<< $top->child( Post... >> part
-
- cat $(perl -MJifty::Util -e 'print Jifty::Util->share_root' \
- )/web/templates/_elements/nav > share/web/templates/_elements/nav
-
-Otherwise, inside F<_elements>, open up a new file called C<nav> in your
-text editor and insert:
-
- <%init>
- my $top = Jifty->web->navigation;
- $top->child( Home => url => "/");
- $top->child( Post => url => "/post",
- label => "Post Article");
- </%init>
+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 F<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;
For more information about the menu system, see the documentation in
L<Jifty::Web::Menu>.
@@ -424,7 +440,7 @@
applications. We're working hard to make Jifty even easier to use and
to obsolete the I<hard bits> of this tutorial as quickly as we can.
-Please join us on the C<jifty-devel> mailing list to talk about how you're
+Please join us on the C<jifty-devel> mailing list to talk about how you're
using Jifty or what you find difficult or hard to use about it.
=head1 MORE TUTORIALS
@@ -443,11 +459,6 @@
L<Jifty::Manual::PageRegions>
-=item * Customized view
-
-For L<Template::Declare> views you can read L<Jifty::Plugin::ViewDeclarePage>,
-which has pretty good documentation on customizing page layouts.
-
=item * CSS and JS
L<Jifty::Manual::UsingCSSandJS>,
@@ -507,12 +518,11 @@
Please visit L<http://jifty.org/>, browse and contribute.
-The wiki is powered by I<Wifty>, a Wiki built on Jifty. Its code is freely
-available from the jifty subversion repository.
+The wiki is powered by I<Wifty>, a Wiki built on Jifty. Its code is freely
+available from the Jifty subversion repository.
=head1 REPORTING BUGS
-At this incredibly early stage in its life, please report bugs in Jifty
-to C<jifty-devel at lists.jifty.org>.
+Please report bugs in Jifty to C<jifty-devel at lists.jifty.org>.
=cut
More information about the Jifty-commit
mailing list