CGI::Application::Structured(3pm)

1CGI::Application::StrucUtsuerredC(o3n)tributed Perl DocuCmGeIn:t:aAtpipolnication::Structured(3)
2
3
4

NAME

6       CGI::Application::Structured - A medium-weight, MVC, DB web
7       micro-framework.
8
9   SYNOPSIS
10       A simple, medium-weight, MVC, DB web micro-framework built on
11       CGI::Application. The framework combines tested, well known plugins and
12       helper scripts to provide a rapid development environment.
13
14       The bundled plugins mix the following methods into your controller
15       runmodes:
16
17           $c->forward(runmode)
18
19           $c->redirect(url)
20
21           $c->tt_param(name=>value)
22
23           $c->tt_process()
24
25           $c->schema()->resultset("Things")->find($id)
26
27           $c->resultset("Things)->search({color=>"red"})
28
29           $c->log->info('This also works')
30
31           my $value = $c->session->param('key')
32
33           my $conf_val = $c->cfg('field');
34
35           my $select = $c->superform->select(
36                               name    => 'select',
37                               default => 2,
38                               values  => [ 0, 1, 2, 3 ],
39                               labels  => {
40                                       0 => 'Zero',
41                                       1 => 'One',
42                                       2 => 'Two',
43                                       3 => 'Three'
44                               }
45                       );
46
47
48           sub method: Runmode {my $c = shift; do_something();}
49
50           $c->fill_form( \$template )
51
52           my  $results = $ ->check_rm(
53                     'form_display','_form_profile')
54                     || return $c->check_rm_error_page;
55

DESCRIPTION

57       I have taken to heart a recent comment by Mark Stosberg on the CGIApp
58       mailing list:
59
60               "Titanium is just one vision of what can be built on top of
61               CGI::Application. Someone else could easily combine their own
62               combination of CGI::Application and different favorite plugins,
63               and publish that with a different name."
64
65       CGI::Application::Structured, like Titanium, is an opinionated
66       framework, based on CGI::Application.  Both frameworks includes a
67       number of vetted CGI-App plugins each of which are well documented and
68       tested.  C::A::Structured, however takes the view that developer time
69       and consistent projects structures can often be more cost-effective
70       than focusing on the highest performance on low cost hosting solutions.
71       That being said, C::A::Structured can be deployed on CGI, FastCGI or
72       mod_perl based on your needs.
73
74       C::A::Structured focuses on:
75
76       ·   adequate performance under CGI, but with more focus speed of
77           development.
78
79       ·   a well-defined project structure with directories for model
80           classes, controllers and view templates.
81
82       ·   a powerful templating DSL via Template Toolkit integration.
83
84       ·   a integrated Object Relational Mapper, DBIx::Class
85
86       ·   no runmode configuration required.
87
88       ·   integrated form building to simplify creation of complex HTML form
89           elements.
90
91       ·   clean url-to-controller mapping by default.
92
93       C::A::Structured comes in two packages:
94
95       ·   CGI::Application::Strutured - encapsulates the runtime environment.
96
97       ·   CGI::Application::Structured::Tools - includes project creation and
98           developemt scripts for developers.
99
100       CGI::Application::Structured::Tools are used to generate a micro-
101       architecture and helper scripts that work within that structure to
102       speed development and maintain project structure across development
103       teams and projects. The helper scripts eliminate the tedium of error-
104       prone manual creation of controllers, templates and database mappings
105       and provide a recognizeable structural conventions that reduced stress
106       on the developer when working across multiple apps, or working with
107       other developers code on the same project.
108
109       The first script that is used is 'cas-starter.pl'. This script is used
110       to generate the initial project skeleton. The skeleton app contains a
111       base controller class rather than runnable module as would be found in
112       Titanium.  Also generated is a default 'Home' controller subclass and a
113       URL dispatcher that is customized to default to the Home controllers
114       generated 'index' runmode.
115
116       cas-starter.pl also generates additional helper scripts in your
117       projects 'scripts' subdirectory:
118
119       ·   create_controller.pl
120
121       ·   create_dbic_schema.pl
122
123       'create_controller.pl' is used by the developer to generate additional
124       controller subclasses of your base module with a default 'index'
125       runmode and a default TT template for that runmode.
126
127       'create_dbic_schema.pl' generates a DBIx::Class::Schema subclass and a
128       set of resultset subclasses for your database.  These Object Relational
129       Maps (ORM) will greatly simplify and speed database assess and
130       manipulation in the development process.
131
132       Finally CGI::Application::Structured aims to be as compatible as
133       possible with Catalyst.  Many plugins used in
134       CGI::Application::Structured are also available for Catalyst, or are
135       even defaults in Catalyst. If your projects needs grow in scope or
136       scale to require Catalyst, porting much of your code will be very easy.
137

CGI::Application::Structured Tutorial

139       In this tutorial we will build a simplistic database driven web
140       application using CGI::Application::Structured to demonstrate using the
141       starter and helper scripts as well as the minimal required
142       configuration.
143
144       CGI::Application::Structured assumes that you have a database that you
145       want to use with the web.  If you have a database you can use for this
146       tutorial.  Otherwise, jump to the "Create The Example Database" section
147       at the bottom of this page before starting the tutorial.
148
149   Installation
150       You will need to install CGI::Application::Structured which provides
151       the runtime requirements.  You will also need to install
152       CGI::Application::Structured::Tools which supplies the development
153       environment.
154
155           ~/dev$ sudo cpan
156           cpan> install CGI::Application::Structured
157                 ... ok
158           cpan> install CGI::Application::Structured::Tools
159                 ... ok
160           cpan> exit
161
162   Creating A Project
163           ~/dev$ cas-starter.pl --module=MyApp1 \
164                                      --author=gordon \
165                                      --email="vanamburg@cpan.org" \
166                                      --verbose
167           Created MyApp1
168           Created MyApp1/lib
169           Created MyApp1/lib/MyApp1.pm                      # YOUR *CONTROLLER BASE CLASS* !
170           Created MyApp1/t
171           Created MyApp1/t/pod-coverage.t
172           Created MyApp1/t/pod.t
173           Created MyApp1/t/01-load.t
174           Created MyApp1/t/test-app.t
175           Created MyApp1/t/perl-critic.t
176           Created MyApp1/t/boilerplate.t
177           Created MyApp1/t/00-signature.t
178           Created MyApp1/t/www
179           Created MyApp1/t/www/PUT.STATIC.CONTENT.HERE
180           Created MyApp1/templates/MyApp1/C/Home
181           Created MyApp1/templates/MyApp1/C/Home/index.tmpl # DEFAULT HOME PAGE TEMPLATE
182           Created MyApp1/Makefile.PL
183           Created MyApp1/Changes
184           Created MyApp1/README
185           Created MyApp1/MANIFEST.SKIP
186           Created MyApp1/t/perlcriticrc
187           Created MyApp1/lib/MyApp1/C                       # YOUR CONTROLLERS GO HERE
188           Created MyApp1/lib/MyApp1/C/Home.pm               # YOUR *DEFAULT CONTROLLER SUBCLASS*
189           Created MyApp1/lib/MyApp1/Dispatch.pm             # YOUR CUSTOM DISPATCHER
190           Created MyApp1/config
191           Created MyApp1/config/config-dev.pl               # YOU CONFIG -- MUST BE EDITED BY YOU!
192           Created MyApp1/script
193           Created MyApp1/script/create_dbic_schema.pl       # IMPORTANT HELPER SCRIPT
194           Created MyApp1/script/create_controller.pl        # ANOTHER IMPORTANT HELPER SCRIPT.
195           Created MyApp1/server.pl                          # SERVER USES YOUR CUSTOM DISPATCH.PM
196           Created MyApp1/MANIFEST
197           Created starter directories and files
198
199   Configure Your Database
200       CGI::Application::Structured is database centric in some sense and
201       expects that you have a database.  Before running your app via
202       server.pl you need to configure your database access.
203
204       The example config is generated at MyApp1/config/config-dev.pl.  The
205       contents are shown here.
206
207               use strict;
208               my %CFG;
209
210               $CFG{db_dsn} = "dbi:mysql:myapp1_dev";
211               $CFG{db_user} = "root";
212               $CFG{db_pw} = "root";
213               $CFG{tt2_dir} = "templates";
214               return \%CFG;
215
216       Using the root account is shown here as a worst-practice.  You should
217       customize the file supplying the correct database dsn, user and
218       passwords for your database.
219
220       If you do not have a database and want to use an example see "Create
221       Example Database" below before continuing.
222
223       For information on advanced configuration see:
224       CGI::Application::Plugin::ConfigAuto
225
226   Generate A DBIx::Class Schema For Your Database
227       From your project root directory run the helper script to generate
228       DBIx::Class::Schema and Resultset packages. This will use the
229       configuration you supplied in config_dev.pl to produce a DB.pm in your
230       apps lib/MAINMODULE directory
231
232               ~/dev/My-App1$ perl script/create_dbic_schema.pl
233               Dumping manual schema for DB to directory /home/gordon/dev/MyApp1/lib/MyApp1/DB ...
234               Schema dump completed.
235
236       Given the example database shown below your resulting DBIx::Class
237       related files and folders would look like this:
238
239           ~/dev/MyApp1$ find lib/MyApp1/ | grep DB
240           lib/MyApp1/DB
241           lib/MyApp1/DB/Result
242           lib/MyApp1/DB/Result/Orders.pm
243           lib/MyApp1/DB/Result/Customer.pm
244           lib/MyApp1/DB.pm
245
246       For more information see: CGI::Application::Plugin::DBIC::Schema,
247       DBIx::Class
248
249   Run Your App
250       Before running your app you will need to export the CONFIG_FILE
251       pointing to your dev config file.
252
253       On linux you could use something like:
254
255          ~/dev/MyApp1$ export CONFIG_FILE=/home/gordon/dev/MyApp1/config/config-dev.pl
256
257       On windows you could use something like:
258
259           C:\Users\gordon\dev\MyApp1: set CONFIG_FILE=C:\Users\gordon\dev\MyApp1\config\config-dev.pl
260
261       Run the server:
262
263           ~/dev/MyApp1$ perl server.pl
264           access your default runmode at /cgi-bin/index.cgi
265           CGI::Application::Server: You can connect to your server at http://localhost:8060/
266
267       Open your browser and test at
268
269           http://localhost:8060/cgi-bin/index.cgi
270
271       For more information on the nature of the development server see:
272       CGI::Application::Server
273
274   Create A New Controller
275       This is where the create_controller.pl helper script comes in very
276       handy.  As an example we can generate a new module to interact with the
277       Orders table of the example database.
278
279           ~/dev/MyApp1$ perl script/create_controller.pl --name=Orders
280           will try to create lib/MyApp1/C
281           Created lib/MyApp1/C/Orders.pm
282           will try to create template directory templates/MyApp1/C/Orders
283           Created templates/MyApp1/C/Orders
284           Created templates/MyApp1/C/Orders/index.tmpl
285
286       You can restart server.pl and view default output at:
287
288           http://localhost:8060/cgi-bin/orders
289
290       Add a new runmode to lib/MyApp1/C/Orders.pm  to show the orders that we
291       have from the example database.
292
293           sub list: Runmode{
294               my $c = shift;
295
296
297               my @orders = $c->resultset("MyApp1::DB::Result::Orders")->all;
298
299               $c->tt_params(orders =>\@orders);
300               return $c->tt_process();
301
302           }
303
304       Then add a template for this runmode at
305       templates/MyApp1/C/Orders/list.tmpl with the following content:
306
307           <h1>Order List</h1>
308           <table>
309             <tr><th>Cust No</th><th>Order No</th></tr>
310             [% FOREACH order = orders %]
311                <tr>
312                  <td>[% order.customer_id %]</td>
313                  <td>[% order.id %]</td>
314                </tr>
315             [% END %]
316           </table>
317
318       Restart server.pl and visit page to see list of orders at:
319
320         http://localhost:8060/cgi-bin/orders/list
321
322       For advanced information on creating controllers, runmodes and
323       templates see: CGI::Application::Plugin::AutoRunmode,
324       CGI::Application::Plugin::TT, CGI::Application and Template::Toolkit.
325
326   Creating The Example Database (if you don't already have one)
327       The CGI::Application::Structured distrubution contains an example sql
328       file that you can use for this example app.  Use the download link at
329       CGI::Application::Structured on CPAN, grab the archive and extract the
330       file from the 'examples' directory of the distribution.
331
332       The script will create the 'myapp1_dev' database, create 2 tables and
333       load a few Notice that the create table statements end with
334       'engine=InnoDB'.  This is important since our DBIC generator script
335       will create perl modules to represent database table relationships,
336       based on the metadata in the database.  While the InnoDB engine will
337       work, the default engine for mysql will not store the relationship
338       metadata and you would then need to hand-craft the relationships at the
339       botton of the generated DB::Result classes.
340
341       Example:
342
343               ~/dev/MyApp1$ mysql -u root -p < example_tables.mysql.ddl
344
345       The contents of the example sql file are as follows:
346
347               CREATE DATABASE myapp1_dev;
348               USE myapp1_dev;
349
350               CREATE TABLE customer(
351                  id integer not null auto_increment PRIMARY KEY,
352                  last_name varchar(25) null,
353                  first_name varchar(25) not null
354               )engine=InnoDB;
355
356               CREATE TABLE orders(
357                 id integer not null auto_increment PRIMARY KEY,
358                 customer_id integer not null,
359                 order_status varchar(10) default "OPEN" not null,
360                 order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP not null,
361                 CONSTRAINT orders_customer_id_fk FOREIGN KEY (customer_id) REFERENCES customer(id)
362               )engine=InnoDB;
363
364               INSERT INTO customer (last_name, first_name) VALUES("Doe","John");
365               INSERT INTO orders (customer_id) VALUES(  1 );
366               INSERT INTO orders (customer_id) VALUES(  1 );
367               INSERT INTO orders (customer_id) VALUES(  1 );
368
369       If you did not use 'engine=InnoDB' or your database does not support
370       relationships, you can paste the following in the bottom of your
371       "MyApp/DB/Result/Orders.pm" to tell DBIx::Class how the example tables
372       relate:
373
374          # Created by DBIx::Class::Schema::Loader v0.04006 @ 2009-09-15 16:05:33
375          # DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:znOKfDkdRzpL0KHWpfpJ+Q
376
377           __PACKAGE__->belongs_to(
378             "customer",
379             "MyApp1::DB::Result::Customer",
380             { id => "customer" },
381           );
382
383       See documentation for DBIx::Class::Manual for more information on
384       configuring and using relationships in your model.
385

BUGS

406       There are no known bugs for this distribution.
407
408       Please report any bugs or feature requests through the web interface at
409       <https://rt.cpan.org>.
410
411       I will be notified, and then you'll automatically be notified of
412       progress on your bug as I make changes.
413

SUPPORT

415       I recommend joining the cgi-application mailing list.
416

AUTHOR

418           Gordon Van Amburg
419           CPAN ID: VANAMBURG
420           vanamburg at cpan.org
421

COPYRIGHT

423       This program is free software; you can redistribute it and/or modify it
424       under the same terms as Perl itself.
425
426       The full text of the license can be found in the LICENSE file included
427       with this module.
428
429
430
431perl v5.12.0                      2009-10-15   CGI::Application::Structured(3)