MiniMVC.pm

filter: Statementstmt 100% 8 / 8 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 100% 10 / 10 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« MiniMVC/Installer.pm ↑ Summary MiniMVC/Cookbook.pm »
1 package MasonX::MiniMVC;
2  
3 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 =head1 NAME
7  
8 MasonX::MiniMVC - Very simple MVC framework for HTML::Mason
9  
10 =head1 VERSION
11  
12 Version 0.03
13  
14 =cut
15  
16 2 our $VERSION = '0.03';
17  
18 =head1 SYNOPSIS
19  
20 # in your dhandler
21 use MasonX::MiniMVC::Dispatcher;
22 my $dispatcher = MasonX::MiniMVC::Dispatcher->new(\%controllers);
23 $dispatcher->dispatch($m);
24  
25 =head1 DESCRIPTION
26  
27 The problem with Mason is that it's just way too tempting to include
28 application logic in your components. It's hard, too, to figure out how
29 to lay out an application. What do you put where? How do you make
30 something that's not a horrible spaghetti tangle?
31  
32 MasonX::MiniMVC is meant to solve most of these problems for simple
33 applications. It's essentially the simplest thing I could come up with
34 that looks like MVC and stops your Mason components from becoming an
35 unmanageable pile of cruft.
36  
37 =head2 Features
38  
39 =over 4
40  
41 =item *
42  
43 A basic directory layout, showing you where to put stuff to keep it
44 under control.
45  
46 =item *
47  
48 Attractive, clean URLs in the form
49 http://example.com/foo/bar/baz. This hides implementation details (*.mhtml
50 filenames) and makes the URLs more search-engine (and human) friendly
51 than http://example.com/foo/bar.mhtml?id=baz.
52  
53 =item *
54  
55 Sample (albeit very slim) controller and model classes are provided.
56  
57 =item *
58  
59 Views are simple Mason components.
60  
61 =back
62  
63 =head1 Non-features
64  
65 MasonX::MiniMVC isn't a full-blown MVC framework. If you're looking for
66 something heavyweight, try Catalyst.
67  
68 MiniMVC also makes some Mason behaviours difficult or impossible. (Most
69 specifically, you just get one top-level autohandler.)
70  
71 =head1 USING MINIMVC
72  
73 =head2 Installation
74  
75 First, install MasonX::MiniMVC. I'll assume you've done that.
76  
77 Then C<cd> into the directory where you want your application to be --
78 probably your webserver's document root -- and run C<minimvc-install
79 MyApp>, replacing "MyApp" with the name of your own application. Since
80 it'll be used as part of Perl module names, it needs to match C<^\w+$>.
81  
82 This will create a basic layout for your app. You should see output
83 something like this:
84  
85 Creating directory structure...
86 lib/
87 lib/MyApp/
88 lib/MyApp/Controller/
89 lib/MyApp/Model/
90 t/
91 view/
92 view/sample/
93 Creating stub/sample files...
94 dhandler
95 autohandler
96 index.mhtml
97 lib/MyApp/Dispatcher.pm
98 lib/MyApp/Controller/Sample.pm
99 lib/MyApp/Model/Sample.pm
100 t/controller_sample.t
101 t/model_sample.t
102 view/default.mhtml
103 view/sample/default.mhtml
104 .htaccess
105 view/.htaccess
106 lib/.htaccess
107 t/.htaccess
108  
109 =head2 Further setup
110  
111 =over 4
112  
113 =item *
114  
115 Set up Apache to handle the directory using HTML::Mason. The provided
116 .htaccess file contains a "SetHandler" directive, but you might need to
117 provide an "AddHandler" in your httpd.conf.
118  
119 =item *
120  
121 Add library paths to the dhandler. Currently there's an empty C<use
122 lib>, but you probably need to add the path to your MiniMVC lib
123 directory, i.e. C</some/directory/your-website/lib>.
124  
125 =back
126  
127 If everything's set up right, you should now be able to point a browser
128 at your application and see a stub/welcome page, with a link to a sample
129 controller-generated page.
130  
131 =head1 APPLICATION DEVELOPMENT WITH MINIMVC
132  
133 To build your application, the steps will be:
134  
135 =over 4
136  
137 =item 1.
138  
139 Create model code in lib/MyApp/Model/, using Class::DBI, DBIx::Class, or
140 whatever other kind of ORM you like to use. This will connect to your
141 database and provide an OO representation of the data.
142  
143 =item 2.
144  
145 Create a structure for your website, mapping URLs to controllers. Edit
146 C<MyApp::Dispatcher> to create these mappings. Typically you will create a
147 controller for each "noun", eg. users, posts, comments, or whatever is
148 appropriate to your site.
149  
150 Here's an example taken from the example "library" application that
151 comes with the MiniMVC distribution:
152  
153 package Library::Dispatcher;
154  
155 use base MasonX::MiniMVC::Dispatcher;
156  
157 sub new {
158 my ($class) = @_;
159 my $self = $class->SUPER::new({
160 'author' => 'Library::Controller::Author',
161 'book' => 'Library::Controller::Book',
162 'book/recommendation' => 'Library::Controller::Book::Recommendation',
163 });
164 }
165  
166 1;
167  
168 =item 3.
169  
170 Create controller classes for each item you listed in C<dhandler>. Just
171 copy C<MyApp/Controller/Sample.pm> and edit appropriately. Each
172 controller must have at least a C<default()> method, used to show the
173 "top level" page for that part of the site.
174  
175 Here's an example C<default()> method:
176  
177 sub default {
178 my ($self, $m, @args) = @_;
179 $m->comp("view/book/default.mhtml");
180 }
181  
182  
183 =item 4.
184  
185 Add methods as you see fit. For instance, you might have a C<Post.pm>
186 and create methods such as C<new()>, C<edit()>, C<view()>, etc. A
187 HTTP request to http://example.com/post/new will call
188 C<MyApp::Post::new()>. A request to http://example.com/post/view/42
189 will call C<MyApp::Post::view()> with 42 passed in as an argument.
190  
191 Here's an example of a method that fetches data using the Model
192 classes, and displays the details:
193  
194 sub view {
195 my ($self, $m, $id) = @_;
196 my $book = Library::Model::Book->fetch($id);
197 $m->comp("view/book/view.mhtml", book => $book);
198 }
199  
200 =item 5.
201  
202 As you've seen in the previous steps, the webpage output is done through
203 a view file. These live in C<view/>, and are displayed by calling
204 C<<$m->comp($view)>> from within the controller code.
205 You can pass args through C<<$m->comp()>> and they'll be accessible via
206 the Mason <%args> section in the view.
207  
208 Using the above example, your book view might look like this:
209  
210 <%args>
211 $book
212 </%args>
213  
214 <h1><% $book->title %></h1>
215 <p>
216 Author: <% $book->author->name() %>
217 </p>
218  
219 =back
220  
221 A fairly detailed sample application can be found in
222 C<examples/library/>, in the MiniMVC CPAN distribution.
223  
224 For more examples, see L<MasonX::MiniMVC::Cookbook>.
225  
226 =head1 AUTHOR
227  
228 Kirrily "Skud" Robert, C<< <skud at cpan.org> >>
229  
230 =head1 BUGS
231  
232 The following are unimplemented or simply known not to work. It's early
233 days yet. Comments welcome, though.
234  
235 =head2 autohandlers below the top level
236  
237 You get one top-level autohandler for your app. You can't have any
238 below that.
239  
240 =head2 404s
241  
242 I've got it doing a C<<$m->clear_and_abort(404)>> if it can't find a
243 controller for a URL, but it doesn't work for me under
244 HTML::Mason::CGIHandler. Don't know whether or not it works under
245 full-blown mod_perl Mason, though. Help wanted!
246  
247 =head2 Other
248  
249 Please report any bugs or feature requests to
250 C<bug-masonx-minimvc at rt.cpan.org>, or through the web interface at
251 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MasonX-MiniMVC>.
252 I will be notified, and then you'll automatically be notified of progress on
253 your bug as I make changes.
254  
255 =head1 SUPPORT
256  
257 You can find documentation for this module with the perldoc command.
258  
259 perldoc MasonX::MiniMVC
260  
261 You can also look for information at:
262  
263 =over 4
264  
265 =item * AnnoCPAN: Annotated CPAN documentation
266  
267 L<http://annocpan.org/dist/MasonX-MiniMVC>
268  
269 =item * CPAN Ratings
270  
271 L<http://cpanratings.perl.org/d/MasonX-MiniMVC>
272  
273 =item * RT: CPAN's request tracker
274  
275 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MasonX-MiniMVC>
276  
277 =item * Search CPAN
278  
279 L<http://search.cpan.org/dist/MasonX-MiniMVC>
280  
281 =back
282  
283 =head1 ACKNOWLEDGEMENTS
284  
285 Thanks to:
286  
287 Paul Fenwick for the autohandler hack to support notes().
288  
289 =head1 COPYRIGHT & LICENSE
290  
291 Copyright 2007 Kirrily "Skud" Robert, all rights reserved.
292  
293 This program is free software; you can redistribute it and/or modify it
294 under the same terms as Perl itself.
295  
296 =cut
297  
298 2 1; # End of MasonX::MiniMVC
« MiniMVC/Installer.pm ↑ Summary MiniMVC/Cookbook.pm »