/ 
Bigtop-0.11
River stage zero No dependents
/ notes/workflows

Workflows for WADL

For purposes of the following discussions, suppose your app is called Apps::Name.

These are normal workflows which WADL is trying to support:

1. Initial application creation

To build your app, you should first make a wadl file (else why are you considering this product). Call it name.wadl (or anything you like). At a minimum the file should have:

config {
    base_dir    /absolute/path/to/app/working/dir
    Init        Std
}
app App::Name {
}

There are two sections to the file. config controls what could be generated and where. app controls the contents of the built files.

Make the base_dir an absolute path, the wadl file is likely to move (see below). Init Std means that the Init::Std module will be asked to gen_Init, see exactly what that builds below.

Every app must have a name which is a valid Perl module name. The empty braces are required (but you can put things inside them).

Once you build the above wadl file, you can type:

wadlgen --Init name.wadl

This step is similar to h2xs. It makes stubs of the following:

Apps-Name/
Apps-Name/Build.PL
Apps-Name/Changes
Apps-Name/MANIFEST
Apps-Name/MANIFEST.SKIP
Apps-Name/README
Apps-Name/lib/
Apps-Name/t/

It also copies your name.wadl file into the Apps-Name directory.

Change into the Apps-Name directory and expand the .wadl file to be more like this:

config {
    base_dir    /absolute/path/to/app/working/dir
    Init        Std
    SQL         Postgres
    HttpdConf   Gantry
    Model       CDBI
    Control     Gantry
}
app App::Name {
    sequence address_seq {}
    table address {
        sequence address_seq;
        field id { is int, primary_key, assign_by_sequence; }
        field first {
            is             varchar;
            label          `First Name`;
            html_form_type text;
        }
        field last {
            is             varchar;
            label          `Last Name`;
            html_form_type text;
        }
        field phone {
            is             varchar;
            label          `Phone Number`;
            html_form_type text;
        }
    }
    controller Address {
        uses           Your::Favorite::Module;
        controls_table address;
        method some_method is handler {
        }
    }
}

Now you can build your app's specifics with:

wadlgen --gen=all

Alternatively, you can build any subset of the config defined items. Suppose you wanted only the SQL and HttpdConf:

wadlgen --gen=SQL --gen=HttpdConf

This will build all sorts of files: schema.sql - ready for use with psql to create the database in Postgres httpd.conf - ready to be an Includ in the system httpd.conf (think inside a virtual host) lib/Apps/Name.pm - a base module lib/Apps/Name/Address.pm - a module meant as the controller for the address table. lib/Apps/Name/Model.pm - a single file with Class DBI packages for each table

If all goes well, all you have to do is create your database, Include the httpd.conf in a virtual host in your system httpd.conf, restart your server and point your browser.

2. Changes to code

Once wadlgen makes files, you are free to edit away and never use it again, but you can also use wadlgen in the future IF you follow its plan. The plan is simple, NEVER edit a file marked NEVER EDIT. These files are not stubs, but complete pieces. Don't change them. Instead, change the files which use them.

3. Changes to the model

If you data changes, you want to have wadlgen update your app. Simply change your .wadl file then type:

wadlgen --gen=all

This will rebuild all of the NEVER EDIT files without comment. It will warn you that there are existing files it could have made as it sees them.

If you don't want a NEVER EDIT file rebuilt (likely because you didn't follow the NEVER EDIT advice, but I'm a forgiving guy), append : no_build to its line in the config section:

config {
    ...
    HttpdConf   Gantry:no_gen
    ...
}

You could also remove the line from the config section altogether, but this has two negative side effects. First, it removes from your memory that the item was ever built. Second, it does not allow WADL::HttpdConf::Gantry to register keywords. That could cause the parse to fail.

4. Clean rebuild

If you ever decide to start from scratch, simply change the base_dir parameter to a new directory and start with step 1.