NAME

WebApp::Documentation::TemplateApp - A tour of the WebApp template app

VERSION

  Time-stamp: <2006-06-15 17:39:21 mailto:attila@stalphonsos.com>
  $Id: TemplateApp.pm,v 1.7 2006/06/15 23:12:55 attila Exp $

SYNOPSIS

  $ perldoc WebApp::Documentation::TemplateApp

DESCRIPTION

This is a walk-through through the template app that the webapp Create command installs. It is intended for web developers who are familiar with Perl. It also doesn't hurt to be familiar with the ExtUtils::MakeMaker Perl module, which comes standard with Perl.

OVERVIEW

In order to help people get started quickly with WebApp, it comes with a template application from which you can start. Using the Unix command-line tool webapp, you can initialize a source directory with a completely functioning web application, including automatically-generated (yet extensible) database-backed object classes, build-system based on ExtUtils::MakeMaker, several working CGI programs and HTML templates, and even simple support for cross-browser CSS fu, JavaScript-enabled apps, etc.

This POD documents this template application. If you read it before starting, you may be saved subtantial heartache. You don't have to use the template application to use WebApp of course, but it really does help if you've at least seen it once.

What the Template Application Does and Why

The template application is a real-world example. It is intended to show the interested developer how to do many common things, and to give them a useful starting point from which to begin their own apps.

If you follow the process outlined by this POD when starting a new application with WebApp you will probably have better luck, since starting from a working application is always easier than starting from scratch. Once you have your working tree in some sort of shape, you can diverge as much as you want from the template. There is no relationship between source trees initialized by the webapp Create command and the installation of WebApp itself.

The template application build system creates a user with your login name, and the password changem3 (see the init-db.pl program that comes with the template app for details). When you first load it up, it redirects you to a login screen. After logging in, it presents you with a piece of the main table of objects in the database, instances of MyWebApp::MyThing. You can scroll through them, add new ones, delete old ones, and change the size of the scroll window. These are all common things that you might want to do from a typical web application, so I thought it would be nice if the template actually did them.

There is an email-based opt-in registration system built in to WebApp, but as of 0.6.2 the template app does not yet use it properly. This will be fixed in 0.6.3, so that the template_app comes with a working example of such an app.

If Something Doesn't Work ...

If something described in this guide does not work for you, please report the problem to the mailto:webapp-dev@cluefactory.com mailing list. Include as much detail as you can. The author considers it vital that the template app work properly for everyone who tries to use it, so bug reports are greatly appreciated.

One hint: any serious problem will result in some error messages being spit out. You can almost always get at these by looking in the Apache error log that pertains to the e.g. vhost, server, etc. involved.

Alternatively, if you are using plain CGI (which the template app does by default), you can always try running the CGI programs from the command line. This is often a good way to make sure things are working.

Getting a Working Tree Started

WebApp comes with a command-line utility, the webapp command. It can do many things, but right now we'll focus on the Create subcommand. When you first run the Makefile.PL that comes with WebApp, it gives you a bit of advice at the end...

  $ perl Makefile.PL
  Welcome to WebApp version 0.6.2!

  To install completely:

      $ make
      $ sudo make install

  Don't forget to read the README and the WebApp::Documentation POD, and
  check http://cluefactory.com/oss/WebApp for news and updates.

  You can try creating a test application from the template with a
  command like:

      $ webapp Create app=something \
         dsn=dbi:Pg:dbname=something \
         src_dir=~/src/something \
         cgi_dir=~/public_html/something \
         code_dir=~/code/something \
         conf_dir=~/etc/WebApp

  This will clone the template application into ~/src/something, and
  give you further instructions.

  Writing Makefile for WebApp

Let's assume for the moment that...

• you have a working PostgreSQL installation on the local machine, in which you are allowed to create databases,
• you keep source code to your projects under <~/src>,
• your personal docroot is ~/public_html, which has ExecCGI turned on in the Apache config,
• you have no problems with ~/code being created to hold per-WebApp code and ~/etc for per-WebApp config files.

If any of these things are not true, it's fairly obvious what to do to fix them (install postgresql, tweak the paths, ...). If all of these things are true, then the command that Makefile.PL spits out, above, is precisely what you want. You might change the "something" to whatever you prefer, or not - just make sure you change it everywhere.

For the rest of this document, we will assume that you ran that command verbatim. If this is not true, then modify the examples and commands below as apropriate.

Initial Tweaks

Here's the output from the webapp Create command that WebApp's Makefile.PL tells you to run:

  $ webapp Create app=something \
           dsn=dbi:Pg:dbname=something \
           src_dir=~/src/something \
           cgi_dir=~/public_html/something \
           code_dir=~/code/something \
           conf_dir=~/etc/WebApp \
           dir=~/code/something \
           conf_dir=~/etc/WebApp

  Now, try the following commands:

      $ cd /home/attila/src/something
      $ mv Makefile.PL.dist Makefile.PL
  # reading README.WebApp would not be a bad idea at this point
      $ perl Makefile.PL
      $ make
  # depending on your Makefile.PL invocation, you might not need sudos here
      $ sudo make install
      $ sudo make webapp-install

Once again we cannot resist the temptation to give the reader a little free advice, and as usual we give excellent advice when it comes to WebApp.

First you need a Makefile.PL for your project. I've given you one, in the form of Makefile.PL.dist, you just have to tweak it a little to get it working the first time. I'll assume you do the mv command above, and talk about ~/src/something/Makefile.PL as if it exists now.

Every place in Makefile.PL that has a comment that looks like

  ## EEE something extremely interesting you must edit

is a place you should look at carefully. Let's go over them one by one:

Invocation of ./MyWebApp.pm to pick up VERSION

The very first thing your new Makefile.PL does (after use ExtUtils::MakeMaker of course) is pull in the source file that sets the VERSION for your application. In the template, I assume you have a set of perl modules called MyWebApp::*, and provide you with a few starting points. You will almost certainly want to change the names of these files to be more descriptive, and thus also change the name of the file in which your app's version number is set.

Of course, you're also going to have to s/MyWebApp/Whatever/ everywhere else in Makefile.PL. I assume this is obvious and won't mention it again.

Opening Banner

You probably want your own cute message to be spit out when your Makefile.PL is invoked. Edit the text that starts

  print STDERR "Welcome to the template application...."

to be whatever you want it to be.

ABSTRACT, VERSION_FROM, EXE_FILES, PREREQ_PM, ...

MakeMaker wants you to tell it a bunch of stuff in the invocation of WriteMakefile. For instance, a one-line abstract about your program, etc. This is all nicely documented in the ExtUtils::MakeMaker POD, which I highly recommend you read. If you don't feel like reading it, then follow along in your Makefile.PL and change the values for all of the fields that have the EEE comment before them.

The only ones you will probably care much about to begin with are EXE_FILES, and PM. These are the list of executable command-line programs and Perl modules that your program contains and wishes to get installed into the appropriate places. You might not have any command-line programs (the template app currently does not). You will almost certainly have some perl modules. The defaults I fill in come with the template app, and are meant to be studied and used as prototypes for new things you need in your app. As you add new perl modules, you must add them to this place in the Makefile.PL.

First Install

Okay, we've hacked up an initial Makefile.PL that looks about right. We need to run it to get a Makefile generated.

In keeping with our great tradition of FREE ADVICE FOR EVERYONE the default Makefile.PL spits out a couple helpful hints:

  $ perl Makefile.PL
  Welcome to the template application template 0.1.0 !  Someone please edit me please!

  Checking if your kit is complete...
  Make variant: BSD (OpenBSD)

  To install completely:
      $ make
      $ sudo make install
      # Edit mk/config.bsd - IMPORTANT
      $ make webapp-install

  ** Don't forget to edit mk/config.bsd before doing make webapp-install! **

  -- This template application brought to you by your Department of Redundancy Department,
  -- which reminds you that a belt always looks snappier with suspenders and a belt!  Be safe!

  Writing Makefile for something

(That's what it looks like when you run the default Makefile.PL with no editing on an OpenBSD machine).

The Makefile that the template Makefile.PL generates has a few additional targets that are WebApp-specific. They all start with the prefix webapp-, e.g. webapp-install, as noted by the above message. These targets are in addition to the standard ones that ExtUtils::MakeMaker generates. I talk about them more explicitly in the next section.

If you follow our advice, the next thing is to type make:

  $ make
  cp MyWebApp.pm blib/lib/MyWebApp.pm
  cp MyWebApp/MyThing.pm blib/lib/MyWebApp/MyThing.pm
  cp MyWebApp/MyThing/code.pm blib/lib/MyWebApp/MyThing/code.pm
  Manifying blib/man3/MyWebApp::MyThing::code.3p
  Manifying blib/man3/MyWebApp.3p

At this point, you might want to do

  $ sudo make install

but only if you need to install your app into some standard place as root. If you set PREFIX when you invoked Makefile.PL to some place that you have write-access, for instance, you can just get away with

  $ make install

and if you don't really need anything installed publically, you can avoid that step entirely. The template application does not need anything installed as root, so you can probably skip that step.

The next step, however, you can't skip. Here's what it looks like:

  $ make webapp-install

    >> MyWebApp 0.1.0 (WebApp 0.6.2)

        Creating CGI dir: /home/attila/tmp/htdocs/something
        Creating code dir: /home/attila/code/something
        CGI Directory: /home/attila/tmp/htdocs/something
        Code Directory: /home/attila/code/something
        Conf Directory: /home/attila/etc/WebApp
        Initializing WebApp data and code areas
         CREATE DATABASE
         NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "users_pkey" for table "users"
         NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "sessions_pkey" for table "sessions"
        Recording database state
        Setting up database
*** Error code 1 (ignored)
        Executing application DDL
         CREATE SEQUENCE
         NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "mything_pkey" for table "mything"
         CREATE TABLE
        Running database initialization program
        Initializing configuration file: /home/attila/etc/WebApp/something.config
        Installing application-specific code and data
        Reinitializing WebApp code areas
        Generating login.cgi ... changed - overwriting... done.
        Generating logout.cgi ... changed - overwriting... done.
        Generating about.cgi ... changed - overwriting... done.
        Generating register.cgi ... changed - overwriting... done.


    << MyWebApp 0.1.0 (WebApp 0.6.2)

A whole lot of things happen, obviously. The error message can be safely ignored.

At this point, you should be able to surf up the URL for the template app and see the login screen. Assuming your username is abulafia, you can probably go somewhere very similar to

  http://127.0.0.1/~abulafia/something

to good effect.

All of this is driven by Makefile.WebApp.Common, which we will now discuss a little bit.

Makefiles, Makefiles Everywhere

There are essentially two parallel sets of Makefiles that come with the template_app: Makefile.PL and its associated files, including the Makefile that is generated at top-level, and Makefile.WebApp.* with its associated config files in the mk subdirectory.

Makefile.PL Additions

I've already touched upon Makefile.PL a bit. We add the following targets to the standard ones provided by ExtUtils::MakeMaker:

release, md5, sha1, ripemd160, asc

These targets are about release management. They are intended to help you automate some parts of creating a new release tarball and associated crypto materials. This is really only important if you want to release your app in this way. They all depend on the normal dist target provided by ExtUtils::MakeMaker. If you simply say:

  $ make dist

You will end up with a file called something-0.1.0.tar.gz, which is just what you think it is: a tarball that, when unpacked, should be capable of installing your app.

The md5, sha1, ripemd160 and asc targets create various kinds of checksums and signatures based on this dist tarball, each with an extension of the obvious kind, e.g.

  $ make md5

Will create a file called something-0.1.0.tar.gz.md5 that contains the MD5 checksum of the tarball. Likewise for sha1 and ripemd160. The openssl command is used for all checksums, although you can override this when you generate Makefile.PL.

The asc target assumes you have a PGP/GPG keypair installed and set up and that the gpg command is installed and working. If you type

  $ make asc

you will be asked for your passphrase, to unlock your private key. A detached, ASCII armored signature is dropped in a file called something-0.1.0.tar.asc.

I keep all of my releases in a directory called ~/releases on my laptop, for safekeeping. This is the default directory to which the tarball and all of the crypto.goop is copied when you say

  $ make release

If this isn't right, try overriding RELEASEDIR when you invoke Makefile.PL

webapp-install

You have already seen this target in action. It is a touchpoint between Makefile.PL and Makefile.WebApp.Common, which contains all the real WebApp-related build infrastructure. This target figures out which variant of the make command is in effect (BSD or GNU) and then does something like e.g.

  $ make -f Makefile.WebApp.BSD install

on a BSD make system, and

  $ make -f Makefile.WebApp.GNU install

on a GNU make system.

Those two files (Makefile.WebApp.{BSD,GNU}) are just front ends to Makefile.WebApp.Common. Whereas the latter file is purposely agnostic towards the variety of make in use, the former two are not. This is because the two styles of make differ in only really one significant way from my point of view: the syntax for file inclusion is different. Therefore, I have one front-end Makefile for each make variant, whose only job in life is to pull in other Makefiles of the right kind, followed by Makefile.WebApp.Common, where all the real work is done. The target we invoke in Makefile.WebApp.Common is called install. Describing the guts of Makefile.WebApp.Common is beyond the scope of this document, but you should take a peek if you are interested.

webapp-force

This is the same kind target as webapp-install - it just front-ends to the right kind of make and invokes the force_install target (instead of just plain old install). This target does everything that install does, after first completely dropping any existing database and getting rid of other associated state. It is a large hammer, meant to be used to completely reset your app to a known state. Be careful if you use it.

Config files in mk

As the message notes, there are some config files in mk that you should look over. By default we create one that looks reasonable based on your environment, but it may not be quite right. Any variable in Makefile.WebApp.Common that you think needs to be overridden should probably be overridden using a config file in mk instead of by editing Makefile.WebApp.Common itself.

DETAILED TOUR

This section contains a file-by-file description of what comes in the template application, as per the MANIFEST.

Build Infrastructure

Makefile.PL.dist

Nascent Makefile.PL that you must rename and edit to get started.

Makefile.WebApp.BSD

BSD make front-end to Makefile.WebApp.Common

Makefile.WebApp.Common

The WebApp-style build system that comes with the template app.

Makefile.WebApp.GNU

GNU make front-end to Makefile.WebApp.Common

gen_stored.sh

A shell script invoked by Makefile.WebApp.Common to regenerate automatically generated files, like MyWebApp/MyThing.pm.

mk/config.gnu.in

The starting point for config.gnu on GNU make systems. Edited by the install target.

mk/eg_freebsd_cgi.bsd

A sample BSD make config for FreeBSD. It worked once somewhere...

mk/eg_macosx.gnu

A sample GNU make config for MacOS X. Yes, that's right. MacOS X is based on BSD Unix (whatever that means), but it ships with GNU make.

mk/eg_openbsd_cgi_chroot.bsd

A sample config for an OpenBSD system that installs into the Apache chroot under /var/www. I develop under OpenBSD most of the time, and frequently want to make sure my stuff works in the chroot.

mk/eg_openbsd_speedy.bsd

A sample config for OpenBSD using SpeedyCGI instead of plain old CGI.

mk/config.bsd.in

This is to BSD make systems what config.gnu.in is to GNU make systems.

mk/eg_openbsd_cgi.bsd

Another sample for OpenBSD, this time plain old CGI.

utils/speedy_fixup.pl

A perl script used to fix up the final CGI programs in the docroot. It morphs them into SpeedyCGI programs, possibly with specialized, per-page SpeedyCGI invocation arguments.

See the CGI::SpeedyCGI POD for more information.

utils/gen_cgi.pl

The Perl script that grinds out the actual CGI programs from the skeleton that WebApp installs.

utils/noop_fixup.pl

A fixup script that does nothing, to keep Makefile.WebApp.Common happy.

utils/announce_version.pl

A perl script that announces the version of your app when you run Makefile.WebApp.Common.

HTML Templates and Web Goop

js/global.js

Nothing but comments. Theoretically, you can put some globally-necessary JavaScript code in here to get it loaded into all of your pages.

images/logo.png

A useless image.

css/common.css

CSS file for the template app common to all browsers.

css/kde.css

KDE-specific CSS hacks. Falls back to common.css.

css/msie.css

MSIE-specific CSS hacks.

css/unknown.css

CSS hacks for unknown browsers.

css/opera.css

CSS hacks for Opera.

css/gecko.css

CSS hacks for Gecko (Firefox/Mozilla).

html/_component.html

We adopt a cascading style of HTML templates in this sample app. All pages use _component.html as their base template. It, in turn, pulls in page-specific HTML templates based on the value of the SUBCOMP variable, which is set by the code in X (specifically the init_session_vars method) to be the same as the name of the page.

The net effect of this is that each page has its own sub-template (e.g. _login.html, _index.html, ...), which is effectively stitched into the middle of what appears in _component.html. The latter file provides all the basic boilerplate for the app.

The About screen guts, pulled in via _component.html when about.cgi is invoked.

html/_body_end.html

html/_body_start.html

html/_footer.html

html/_header.html

html/_sidebar.html

html/_javascript.html

These files are all part of the boilerplate that _component.html stitches together for us. They are split out into separate files to make it easy to change for all pages at once.

html/_about.html

The guts of the About screen.

html/_login.html

The guts of the Login screen, including the form

html/_index.html

The guts of the index screen.

html/_page_link.html

A sub-file pulled in by the list in index to generate links to additional pages of results

Application Code

_app_config.pl

A file of Perl code pulled in very early in the lifetime of a page or SpeedyCGI process. You should put all of the use statements that any of your top-level CGI programs requires in this file.

Xaction.pm

A class that inherits from WebApp::Xaction to provide you with a app-specific notion of what a "transaction" means to you.

init-db.pl

A perl program invoked to initialize a blank database for this app. The template app comes with one that creates a few dozen objects for you to play with, along with your user identity.

about.pl

Could become a "help" component with search, for instance

index.pl

The code behind index.cgi. Produces the list of objects and responds to the buttons to delete, add, etc.

login.pl

Authentication screen logic.

logout.pl

Code to log out a session.

register.pl

NOT WORKING RIGHT NOW: email-based registration logic based on the built-in facilities in WebApp::User.

utils.pl

Common code, pulled in by _app_config.pl

template.pl

template.pm

templates.el

These three files are more for you to use if you feel like it than part of the app, strictly speaking. The later file is EMACS lisp code that I use in my development environment. It provides you with a convenient way to keep templates (starting points) for various kinds of text files organized in your working trees. The former two files are both such templates: a starting point for a new CGI program (template.pl) and a starting point for a new perl module (template.pm).

If this interests you, feel free to play with it and ask me questions if it breaks. I use this on a daily basis.

MyWebApp.pm

This is the main perl module for the app. At the very least, it should set $VERSION to something sensible. Rename and tweak as desired.

MyWebApp/MyThing.pm

This is generated automatically by mkstored, a utility that comes with WebApp. It is glue code that interfaces between the database and the in-core objects that represent data stored in the database.

MyWebApp/MyThing/code.pm

This is an example of how you endow the built-in database objects with new methods. It provides a List-style constructor for MyThing, which means that you get back a list of objects that match criteria instead of just one object, the way that new hands them back.

Random Stuff

app.config

This is copied to CONF_DIR/something.config, where you can tweak it to suit yourelf. It is a WebApp::Config style file. Refer to the WebApp::Documentation to see everything you can tweak.

ddl.sql

The DDL (Data Definition Language, aka CREATE {TABLE|SEQUENCE|...} statements) for your applications.

INSTALL

A file with installation instructions, as per normal F/OSS conventions.

README

The README for your app. This is really for you to write, not me, but I put one there anyway just to remind you.

README.WebApp

A note about WebApp and how it pertains to your app.

MANIFEST

The packing list for your app, as per Makefile.PL conventions.

AUTHOR

Sean Levy <mailto:snl@cluefactory.com>

COPYRIGHT AND LICENSE

(C) 2002-2006 by Sean Levy <mailto:snl@cluefactory.com>. all rights reserved.

This code is released under a BSD license. Please see the LICENSE file that came with the source distribution or visit http://cluefactory.com/oss/WebApp/license.html