lib/Catalyst/Helper/View/TTSite.pm

   1 package Catalyst::Helper::View::TTSite;
   2
   3 use strict;
   4 use File::Spec;
   5
   6 our $VERSION = '0.45';
   7 $VERSION = eval $VERSION;
   8
   9 sub mk_compclass {
  10     my ( $self, $helper, @args ) = @_;
  11     my $file = $helper->{file};
  12     $helper->render_file( 'compclass', $file );
  13     $self->mk_templates( $helper, @args );
  14 }
  15
  16 sub mk_templates {
  17     my ( $self, $helper ) = @_;
  18     my $base = $helper->{base},;
  19     my $ldir = File::Spec->catfile( $base, 'root', 'lib' );
  20     my $sdir = File::Spec->catfile( $base, 'root', 'src' );
  21
  22     $helper->mk_dir($ldir);
  23     $helper->mk_dir($sdir);
  24
  25     my $dir = File::Spec->catfile( $ldir, 'config' );
  26     $helper->mk_dir($dir);
  27
  28     foreach my $file (qw( main col url )) {
  29         $helper->render_file( "config_$file",
  30             File::Spec->catfile( $dir, $file ) );
  31     }
  32
  33     $dir = File::Spec->catfile( $ldir, 'site' );
  34     $helper->mk_dir($dir);
  35
  36     foreach my $file (qw( wrapper layout html header footer )) {
  37         $helper->render_file( "site_$file",
  38             File::Spec->catfile( $dir, $file ) );
  39     }
  40
  41     foreach my $file (qw( welcome.tt2 message.tt2 error.tt2 ttsite.css )) {
  42         $helper->render_file( $file, File::Spec->catfile( $sdir, $file ) );
  43     }
  44
  45 }
  46
  47 =head1 NAME
  48
  49 Catalyst::Helper::View::TTSite - Helper for TT view which builds a skeleton web site
  50
  51 =head1 SYNOPSIS
  52
  53 # use the helper to create the view module and templates
  54
  55     $ script/myapp_create.pl view HTML TTSite
  56
  57 # add something like the following to your main application module
  58
  59     sub message : Global {
  60         my ( $self, $c ) = @_;
  61         $c->stash->{template} = 'message.tt2';
  62         $c->stash->{message}  ||= $c->req->param('message') || 'No message';
  63     }
  64
  65     sub default : Private {
  66         my ( $self, $c ) = @_;
  67         $c->stash->{template} = 'welcome.tt2';
  68     }
  69
  70     sub end : Private { # Or use Catalyst::Action::RenderView
  71         my ( $self, $c ) = @_;
  72         $c->forward( $c->view('HTML') );
  73     }
  74
  75 =head1 DESCRIPTION
  76
  77 This helper module creates a TT View module.  It goes further than
  78 Catalyst::Helper::View::TT in that it additionally creates a simple
  79 set of templates to get you started with your web site presentation.
  80
  81 It creates the templates in F<root/> directory underneath your
  82 main project directory.  In here two further subdirectories are
  83 created: F<root/src> which contains the main page templates, and F<root/lib>
  84 containing a library of other template components (header, footer,
  85 etc.) that the page templates use.
  86
  87 The view module that the helper creates is automatically configured
  88 to locate these templates.
  89
  90 =head2 Default Rendering
  91
  92 To render a template the following process is applied:
  93
  94 The configuration template F<root/lib/config/main> is rendered. This is
  95 controlled by the C<PRE_PROCESS> configuration variable set in the controller
  96 generated by Catalyst::Helper::View::TTsite. Additionally, templates referenced by
  97 the C<PROCESS> directive will then be rendered. By default the following additional
  98 templates are set: F<root/lib/config/col>,
  99 which defines color names and RGB their RGB values and F</root/lib/config/url>,
 100 which defines site wide variables available to templates.
 101
 102 Next, the template defined by the C<WRAPPER> config variable is called. The default
 103 wrapper template is located in F<root/lib/site/wrapper>. The wrapper template
 104 passes files with C<.css/.js/.txt> extensions through as text OR processes
 105 the templates defined after the C<WRAPPER> directive: C<site/html> and C<site/layout>.
 106
 107 Based on the default value of the C<WRAPPER> directive in F<root/lib/site/wrapper>,
 108 the following templates are processed in order:
 109
 110 =over 4
 111
 112 =item * F<root/src/your_template.tt2>
 113
 114 =item * F<root/lib/site/footer>
 115
 116 =item * F<root/lib/site/header>
 117
 118 =item * F<root/lib/site/layout>
 119
 120 =item * F<root/lib/site/html>
 121
 122 =back
 123
 124 Finally, the rendered content is returned to the browser.
 125
 126 =head1 METHODS
 127
 128 =head2 mk_compclass
 129
 130 Generates the component class.
 131
 132 =head2 mk_templates
 133
 134 Generates the templates.
 135
 136 =cut
 137
 138 =head1 SEE ALSO
 139
 140 L<Catalyst>, L<Catalyst::View::TT>, L<Catalyst::Helper>,
 141 L<Catalyst::Helper::View::TT>
 142
 143 =head1 AUTHOR
 144
 145 Andy Wardley <abw@cpan.org>
 146
 147 =head1 LICENSE
 148
 149 This library is free software. You can redistribute it and/or modify
 150 it under the same terms as perl itself.
 151
 152 =cut
 153
 154 1;
 155
 156 __DATA__
 157
 158 __compclass__
 159 package [% class %];
 160
 161 use strict;
 162 use base 'Catalyst::View::TT';
 163
 164 __PACKAGE__->config({
 165     INCLUDE_PATH => [
 166         [% app %]->path_to( 'root', 'src' ),
 167         [% app %]->path_to( 'root', 'lib' )
 168     ],
 169     PRE_PROCESS  => 'config/main',
 170     WRAPPER      => 'site/wrapper',
 171     ERROR        => 'error.tt2',
 172     TIMER        => 0,
 173     render_die   => 1,
 174 });
 175
 176 =head1 NAME
 177
 178 [% class %] - Catalyst TTSite View
 179
 180 =head1 SYNOPSIS
 181
 182 See L<[% app %]>
 183
 184 =head1 DESCRIPTION
 185
 186 Catalyst TTSite View.
 187
 188 =head1 AUTHOR
 189
 190 [% author %]
 191
 192 =head1 LICENSE
 193
 194 This library is free software. You can redistribute it and/or modify
 195 it under the same terms as Perl itself.
 196
 197 =cut
 198
 199 1;
 200
 201 __config_main__
 202 [% USE Date;
 203    year = Date.format(Date.now, '%Y');
 204 -%]
 205 [% TAGS star -%]
 206 [% # config/main
 207    #
 208    # This is the main configuration template which is processed before
 209    # any other page, by virtue of it being defined as a PRE_PROCESS
 210    # template.  This is the place to define any extra template variables,
 211    # macros, load plugins, and perform any other template setup.
 212
 213    IF Catalyst.debug;
 214      # define a debug() macro directed to Catalyst's log
 215      MACRO debug(message) CALL Catalyst.log.debug(message);
 216    END;
 217
 218    # define a data structure to hold sitewide data
 219    site = {
 220      title     => 'Catalyst::View::TTSite Example Page',
 221      copyright => '[* year *] Your Name Here',
 222    };
 223
 224    # load up any other configuration items
 225    PROCESS config/col
 226          + config/url;
 227
 228    # set defaults for variables, etc.
 229    DEFAULT
 230      message = 'There is no message';
 231
 232 -%]
 233 __config_col__
 234 [% TAGS star -%]
 235 [% site.rgb = {
 236      black  = '#000000'
 237      white  = '#ffffff'
 238      grey1  = '#46494c'
 239      grey2  = '#c6c9cc'
 240      grey3  = '#e3e6ea'
 241      red    = '#CC4444'
 242      green  = '#66AA66'
 243      blue   = '#89b8df'
 244      orange = '#f08900'
 245    };
 246
 247    site.col = {
 248       page    = site.rgb.white
 249       text    = site.rgb.grey1
 250       head    = site.rgb.grey3
 251       line    = site.rgb.orange
 252       message = site.rgb.green
 253       error   = site.rgb.red
 254    };
 255 -%]
 256 __config_url__
 257 [% TAGS star -%]
 258 [% base = Catalyst.req.base;
 259
 260    site.url = {
 261      base    = base
 262      home    = "${base}welcome"
 263      message = "${base}message"
 264    }
 265 -%]
 266 __site_wrapper__
 267 [% TAGS star -%]
 268 [% IF template.name.match('\.(css|js|txt)');
 269      debug("Passing page through as text: $template.name");
 270      content;
 271    ELSE;
 272      debug("Applying HTML page layout wrappers to $template.name\n");
 273      content WRAPPER site/html + site/layout;
 274    END;
 275 -%]
 276 __site_html__
 277 [% TAGS star -%]
 278 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 279 <html>
 280  <head>
 281   <title>[% template.title or site.title %]</title>
 282   <style type="text/css">
 283 [% PROCESS ttsite.css %]
 284   </style>
 285  </head>
 286  <body>
 287 [% content %]
 288  </body>
 289 </html>
 290 __site_layout__
 291 [% TAGS star -%]
 292 <div id="header">[% PROCESS site/header %]</div>
 293
 294 <div id="content">
 295 [% content %]
 296 </div>
 297
 298 <div id="footer">[% PROCESS site/footer %]</div>
 299 __site_header__
 300 [% TAGS star -%]
 301 <!-- BEGIN site/header -->
 302 <h1 class="title">[% template.title or site.title %]</h1>
 303 <!-- END site/header -->
 304 __site_footer__
 305 [% TAGS star -%]
 306 <!-- BEGIN site/footer -->
 307 <div id="copyright">&copy; [% site.copyright %]</div>
 308 <!-- END site/footer -->
 309 __welcome.tt2__
 310 [% TAGS star -%]
 311 [% META title = 'Catalyst/TT View!' %]
 312 <p>
 313   Yay!  You're looking at a page generated by the Catalyst::View::TT
 314   plugin module.
 315 </p>
 316 <p>
 317   This is the welcome page.  Why not try the equally-exciting
 318   <a href="[% site.url.message %]">Message Page</a>?
 319 </p>
 320 __message.tt2__
 321 [% TAGS star -%]
 322 [% META title = 'Catalyst/TT View!' %]
 323 <p>
 324   Yay!  You're looking at a page generated by the Catalyst::View::TT
 325   plugin module.
 326 </p>
 327 <p>
 328   We have a message for you: <span class="message">[% message %]</span>.
 329 </p>
 330 <p>
 331   Why not try updating the message?  Go on, it's really exciting, honest!
 332 </p>
 333 <form action="[% site.url.message %]"
 334       method="POST" enctype="application/x-www-form-urlencoded">
 335  <input type="text" name="message" value="[% message %]" />
 336  <input type="submit" name="submit" value=" Update Message "/>
 337 </form>
 338 __error.tt2__
 339 [% TAGS star -%]
 340 [% META title = 'Catalyst/TT Error' %]
 341 <p>
 342   An error has occurred.  We're terribly sorry about that, but it's
 343   one of those things that happens from time to time.  Let's just
 344   hope the developers test everything properly before release...
 345 </p>
 346 <p>
 347   Here's the error message, on the off-chance that it means something
 348   to you: <span class="error">[% error %]</span>
 349 </p>
 350 __ttsite.css__
 351 [% TAGS star %]
 352 html {
 353     height: 100%;
 354 }
 355
 356 body {
 357     background-color: [% site.col.page %];
 358     color: [% site.col.text %];
 359     margin: 0px;
 360     padding: 0px;
 361     height: 100%;
 362 }
 363
 364 #header {
 365     background-color: [% site.col.head %];
 366     border-bottom: 1px solid [% site.col.line %];
 367 }
 368
 369 #footer {
 370     background-color: [% site.col.head %];
 371     text-align: center;
 372     border-top: 1px solid [% site.col.line %];
 373     position: absolute;
 374     bottom: 0;
 375     left: 0px;
 376     width: 100%;
 377     padding: 4px;
 378 }
 379
 380 #content {
 381     padding: 10px;
 382 }
 383
 384 h1.title {
 385     padding: 4px;
 386     margin: 0px;
 387 }
 388
 389 .message {
 390     color: [% site.col.message %];
 391 }
 392
 393 .error {
 394     color: [% site.col.error %];
 395 }