NAME

CGI::Bus::tm - database Transaction page Manager to view and edit data

SYNOPSIS

 use CGI::Bus;
 $s =CGI::Bus->new();
 $s->tm->...see 'Transaction Sequence' below

DESCRIPTION

This module is database Transaction page Manager to view and edit data.

There are a common TRANSACTION SEQUENCE and simplest programming interface using cmd(-command) conditions and direct database calls along with cnd and qparam calls. Some common transaction commands for more usable programming interface are also implemented.

Some slots are only predefined for children and not used within this module. Some slots may be extended in subclasses.

See CGI::Bus::tmsql as an example of details and for more advanced SQL database applications development features.

See CGI::Bus::Base for inherited slots and methods.

TRANSACTION SEQUENCE

Transaction sequence is a series of hooks dependent on current command cmd and current generic (or general or global) command cmdg. cmd(-command) calls are used as conditions. In simplest programming interface this conditions should be programmed. In more usable programming interface (SQL generator) this conditions are hidden inside eval or cmd(-cmd) call evaluating cmdCCC methods, but may be hooked with -cmdCCC slots.

A transaction sequence looks like something as:

 my $s =CGI::Bus->new();
 my $t =$s->tmsql;
 my $d =$s->dbi;        #
 eval {                 # inside $t->eval(?connect, sub{
   if ($t->cmd(-chk)) { # check before insert, update, delete # $t->cmdchk
   }
   if ($t->cmd(-ins)) { # insert record
       $d->execute('insert ...', @{$t->qparam([names])});
   }
   if ($t->cmd(-upd)) { # update record where cnd
       $t->cnd(-upd, field=>flags,...);
       $d->execute('update ...' .$t->cnd, @{$p->qparam([names])});       
   }
   if ($t->cmd(-del)) { # delete record where cnd
       $t->cnd(-del, field=>flags,...);
       $d->execute('delete ...' .$t->cnd);
   }
   if ($t->cmd(-sel)) { # select record fields to edit
       $t->cnd(-sel, field=>flags,...);
       $p->qparam($d->selectrow_hashref('...' .$t->cnd));      
   }
   if ($t->cmd(-crt)) { # create new record values            # $t->cmdcrt
   }
   if ($t->cmd(-qry)) { # list query condition                # $t->cmdqry
   }                                                          
   if ($t->cmd(-htm)) { # html page begin                     # $t->cmdhtm
       print $t->htmlhid;
       print $t->htmlbar;
   }
   if ($t->cmd(-frm)) { # html record form                    # $t->cmdfrm
     # print html form
   }
   if ($t->cmd(-lst)) { # list records
       $t->cnd(-lst, field=>flags,...);
       $d->select...
   }
   if ($t->cmd(-end)) { # commit, inside $t->eval call
       $d->commit
   }
 };
 $t->print($t->htmlres);# result msg, inside $t->eval call
}

Transaction Sequence and Calls

-chk

Check or compute fields values before insert, update, delete operation - cmdchk call

-ins

Insert record into database

-upd

Update record in the database. Previous values parameters names have -pxpv prefix.

-del

Delete record in the database. Previous values parameters names have -pxpv prefix.

-sel

Select record fields into CGI params to view or edit. Previous values parameters will be reseted.

-crt

Create new record fields values into CGI params. Initiate to present new record form. cmdcrt call.

-qry

List query condition values initiate as CGI params - cmdqry call

-htm

HTML page begin output - print operations action bar and hidden HTML - cmdhtm call

-frm

Output HTML record form for query condition, view or edit - cmdfrm call

-lst

List records to user according to filter, view chosen, query condition given

-end

Commit database transaction, the last command, implemented inside eval call along with htmlres and rollback.

SLOTS

-acd

Access control description hash ref. RESERVED

-cmd

Current transaction command cached by cmd

-cmdc

Current transaction command cached inside cnd calls

-cmdCCC

Transacion command 'CCC' hook subroutine reference. Default operation is cmdCCC call. Commands are described in TRANSACTION SEQUENCE above.

-cmde

Current transaction command edit state flag cached by cmd calls

-cmdg

Generic (general, global) transaction command cached by cmd, available via cmdg. This is any -cmd command exept form exchanges - -frm, -ins, -upd commands.

-cnd

Transaction condition string generated by cnd

-fields

Form fields hash ref, converted from -form by set

-filter

Filter 'WHERE' clause for all SQL commands - string or sub{}. -fltsel, -fltlst, -fltedt takes precedence. RESERVED

-fltedt

Filter 'WHERE' clause SQL 'UPDATE' and 'DELETE' commands - string or sub{}. RESERVED

-fltlst

Filter 'WHERE' clause SQL 'SELECT' command to list records - string or sub{}. RESERVED

-fltsel

Filter 'WHERE' clause SQL 'SELECT' commands to view record - string or sub{}. RESERVED

-form

Form data description array ref, extendable in subclasses. See CGI::Bus::tmsql for descriptions of field attributes used here: -fld, -lbl, -cmt, -flg ('k'ey and 'm'andatory), -col -crt, -frm, -sav, -ins, -upd, -del

-formtgf

Form Target Frame. Target frame to open form for create new or edit existed record. Undefined value means the same browser window as for list of records, '_BLANK' opens new browser window

-fsd

File store description hash ref, RESERVED

-ftext

Full-text search expression template for use in query condition for -lists, '$_' is placeholder. RESERVED

-genXXX

Generated database commands and clauses, RESERVED

-htmlts

-htmlte

Starting and ending data (form or view) table HTML. Commonly used by default are '<table>' and '/<table>'.

-keyfld

Single key field name, RESERVED

-lboxrnm

Listbox rows number margin, RESERVED

-lists

Views data description hash ref, extendable in subclasses. See CGI::Bus::tmsql for descriptions of view attributes used here: -lbl, -cmt, -fields, -key, -orderby

-listrnm

View rows number default margin. Margin of the number of the rows returned by -lst operation

-opflg

Operations allowed letters: '<' leftmost left navigation action bar from htmlbar; 'a'll: 'c'reate/'i'nsert, 'e'dit/'u'pdate, 'd'elete record; 's'elect record (?), '!s'elect record button; 'v'iew record, '!v'iew record mode; 'l'ist records, 'q'uery condition

-pxcb

-pxcb => '_tcb_' - Transaction command or button name prefix

-pxqc

-pxqc => '_tsw_' - Special widget name prefix

-pxpv

-pxpv => '_tpv_' - Previous value parameter name prefix for -upd and -del operation

-pxqc

-pxqc => '_tqc_' - Query condition parameter name prefix for save by -lst operation

-refresh

Refresh frequency for all lists (views) of recods, used to generate <meta http-equiv="refresh" CONTENT=XX>

-rowlst

-rowsel

-rowedt

-rowsav

-rowins

-rowupd

-rowdel

Subs{} to allow or filter row operation given. Are used at a lower level, then -cmdCCC subs{}. May be used for access control. -rowlst is to be evaluated for each row in cmdlst to filter rows to display. -rowedt controls record edit appearance. -rowupd and -rowdel (and -rowsav in this cases) are to evaluate when previous values of fields are fetched to -pxpv parameters. Partially RESERVED.

-rowsav1

-rowsav2

-rowsav1a

-rowsav2a

Like -rowsav, but immediatelly before or 'a'fter database (SQL) command generation and execution. Actual field values to be used for or 'a'fter database command are available as CGI params. -rowsav1 is used for edited record only (new value fieldnames not prefixed). -rowsav2 is used for each database command (new value fieldnames may be prefixed).

-tbarl

Left toolbar HTML or HTML strings array ref for -htm operation

-tbarr

Right toolbar HTML or HTML strings array ref for -htm operation

-vsd

Version store description hash ref, RESERVED

-width

Width of data (form or view) table, in '&nbsp;' chars

METHODS

Common methods: qparampv, qparamsw, qparampx, htmlself, cmd, cmdg, htmlbar, htmlhid, htmlres, htmlself, eval, evaluate

Programming interface: evaluate, eval, cmd, cnd

Transaction commands implementations: cmdchk, cmdcrt, cmdqry, cmdhtm, cmdfrm, cmdhlp

cmd -> current command

cmd (-command) -> is command matched?

cmd (-cmd) -> execution of all commands required

Current transaction command

cmdchk () -> check before insert, update, delete

Check fields (CGI params) values before insert or update with -chk subs{}. Calculate fields values with -frm, -sav, -ins, -upd, -del subs{} before insert, update, delete

cmdcrt () -> params with default values

Create CGI params with -crt default values for new record

cmdfrm () -> HTML form fields printed

Print HTML form fields for new, view or edit record

cmdg -> current generic command

cmdg (-command,...) -> is one of commands matched?

Current generic (general, global) transaction command is any -cmd command exept form exchanges like -frm, -ins, -upd.

cmdhlp () -> Help screen HTML printed

Print Help page HTML, constructed with -form and -lists descriptions

cmdhtm () -> top form HTML printed

Print HTML at the top of the list of records or form of record. By other words, print htmlbar and htmlhid.

cmdqry () -> params with default values

Create CGI params with -qry default values for query parameters form

cnd -> current transaction command condition string

cnd (?-cmd, param => format,...) -> condition string

cnd (?-cmd, ?'+', ?'-and|or', ?'+and|or', ?'prefix.', param, ?'fieldname=', format,...) -> condition string

Makes dbi transaction command condition string or returns current condition string. '-+and|or' prepends or appends 'and' or 'or' to condition string generated if it is not empty. Field values may contain condition expression used for -lst transaction. Field values are given from CGI params. Field formats may be empty, quote ("'", '"'), sub, string template with '?' placeholder for value.

eval (?dbi connect parameters, ?sub{}) -> DBI transaction

Connect to the database, execute given sub{} in DBI transaction, print htmlres, commit or rollback on errors. Default procedure is cmd('-cmd'). See also evaluate

evaluate () -> operation requested by browser

Full CGI::Bus::tm execution. Like eval, but with starting HTTP, starting and ending HTML page. Uses '-htpgstart' and '-htpfstart' from parent CGI::Bus

htmlbar (?opt) -> action bar HTML

Generate action bar HTML string dependent on options or -opflg, current transaction, -tbarl , -tbarr.

htmlhid () -> hidden HTML

Generate hidden HTML string. Hidden HTML contains saved parameters values like previous values of fields.

htmlres () -> transaction result HTML

Generate transaction result HTML string - empty or success or error message.

htmlself (command, param=>val,...) -> self command hyperlink HTML

htmlself (command, param=>val,..., {attributes})

htmlself ({attributes}, command, param=>val,...)

Generate self script command hyperlink HTML. See cmd and TRANSACTION SEQUENCE for commands. Attributes for 'A' HTML tag may be given as an array or hash ref.

pxnme ( prefix => name ) -> prefixed name

pxcb ( name ) -> command button name

pxsw ( name ) -> special widget name

pxpv ( name ) -> previous value name

pxqc ( name ) -> query condition name

Prefix field or param name given to construct special name. Prefixes are -pxcb, -pxsw, -pxpv, -pxqc.

qlst () -> queried list name

List (view) name queried or default

qparampv (name,...) -> previous value of param

qparam call with -pxpv prefixed param names.

qparampx (prefix) -> [field names]

qparampx (prefix,...) -> qparam prefixed

Get params names with prefix given or qparam call with prefixed param names. Empty prefix means non-prefixed names.

qparamsw (name,...) -> special widget value

qparam call with -pxsw prefixed param names.

VERSION

05/06/2002

New:

-refresh view and common slots

02/06/2002

New:

-htmlts, -htmlte, -width common slots

16/05/2002

New:

-rowsav1 and -rowsav2 events inside cmdsql.

07/05/2002

Changed:

 - textarea fields displays linebreaks when viewed
 - 'Select' and 'Edit' command buttons appearance
 - '!s'elect record button '-opflg' value

05/04/2002 - 06/05/2002

New:

 - imagebuttons toolbar using -iurl slot;
   uncomment at the beginning of the source to disable;
   see issue in the source code

19/01/2002 - 23/03/2002

New:

Implemented and Documented.

ToDo:

 - review & test & debug

Questions:

 - how to move 'qparampv' and 'qparamsw' methods up to the application object?

AUTHOR

Andrew V Makarow <makarow@mail.com>

cpanm CGI::Bus

perl -MCPAN -e shell
install CGI::Bus