CGI::Bus::tm - database Transaction page Manager to view and edit data
use CGI::Bus; $s =CGI::Bus->new(); $s->tm->...see 'Transaction Sequence' below
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.
TRANSACTION SEQUENCE
cmd
cnd
qparam
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 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.
cmdg
eval
-cmd
cmdCCC
-cmdCCC
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 }
Check or compute fields values before insert, update, delete operation - cmdchk call
cmdchk
Insert record into database
Update record in the database. Previous values parameters names have -pxpv prefix.
-pxpv
Delete record in the database. Previous values parameters names have -pxpv prefix.
Select record fields into CGI params to view or edit. Previous values parameters will be reseted.
Create new record fields values into CGI params. Initiate to present new record form. cmdcrt call.
cmdcrt
List query condition values initiate as CGI params - cmdqry call
cmdqry
HTML page begin output - print operations action bar and hidden HTML - cmdhtm call
cmdhtm
Output HTML record form for query condition, view or edit - cmdfrm call
cmdfrm
List records to user according to filter, view chosen, query condition given
Commit database transaction, the last command, implemented inside eval call along with htmlres and rollback.
htmlres
Access control description hash ref. RESERVED
Banner to place above the toolbar. May be sub{}(self) or HTML. See also <-logo>
Current transaction command cached by cmd
Current transaction command cached inside cnd calls
Transacion command 'CCC' hook subroutine reference. Default operation is cmdCCC call. Commands are described in TRANSACTION SEQUENCE above.
Current transaction command edit state flag cached by cmd calls
Generic (general, global) transaction command cached by cmd, available via cmdg. This is any -cmd command exept form exchanges - -frm, -ins, -upd commands.
-frm
-ins
-upd
Transaction condition string generated by cnd
Form fields hash ref, converted from -form by set
-form
set
Filter 'WHERE' clause for all SQL commands - string or sub{}. -fltsel, -fltlst, -fltedt takes precedence. RESERVED
-fltsel
-fltlst
-fltedt
Filter 'WHERE' clause SQL 'UPDATE' and 'DELETE' commands - string or sub{}. RESERVED
Filter 'WHERE' clause SQL 'SELECT' command to list records - string or sub{}. RESERVED
Filter 'WHERE' clause SQL 'SELECT' commands to view record - string or sub{}. RESERVED
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
-fld
-lbl
-cmt
-flg
-col
-crt
-sav
-del
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
File store description hash ref, RESERVED
Full-text search expression template for use in query condition for -lists, '$_' is placeholder. RESERVED
-lists
Generated database commands and clauses, RESERVED
Starting and ending data (form or view) table HTML. Commonly used by default are '<table>' and '/<table>'.
Single key field name, RESERVED
Listbox rows number margin, RESERVED
Views data description hash ref, extendable in subclasses. See CGI::Bus::tmsql for descriptions of view attributes used here: -lbl, -cmt, -fields, -key, -orderby
-fields
-key
-orderby
View rows number default margin. Margin of the number of the rows returned by -lst operation
-lst
Logotype to place at the left of the toolbar. May be image URL or HTML. See also -banner, -tbarl
-banner
-tbarl
Operations allowed letters: '<' leftmost left navigation action bar from htmlbar; 'a'll: 'c'reate/'i'nsert, 'e'dit/'u'pdate, 'd'elete, 's'elect (?), 'v'iew record, 'l'ist, 'q'uery records; !'c'reate/'i'nsert, !'e'dit/'u'pdate, !'d'elete record, !'s'elect record button, !'v'iew record mode, !'q'uery condition
htmlbar
-pxcb => '_tcb_' - Transaction command or button name prefix
-pxqc => '_tsw_' - Special widget name prefix
-pxpv => '_tpv_' - Previous value parameter name prefix for -upd and -del operation
-pxqc => '_tqc_' - Query condition parameter name prefix for save by -lst operation
Refresh frequency for all lists (views) of recods, used to generate <meta http-equiv="refresh" CONTENT=XX>
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.
-rowlst
cmdlst
-rowedt
-rowupd
-rowdel
-rowsav
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).
-rowsav1
-rowsav2
Like -rowsel, but immediatelly 'a'fter database (SQL SELECT) command generation and execution. Field values are available as CGI params, both previous (-pxpv) and pending. -rowsel1a is used while editing record only (when previous field values selected). -rowsel2a is used for each record selection (previous or current field values selected).
-rowsel
-rowsel1a
-rowsel2a
Left toolbar HTML or HTML strings array ref for -htm operation
-htm
Right toolbar HTML or HTML strings array ref for -htm operation
Version store description hash ref, RESERVED
Width of data (form or view) table, in ' ' chars
Common methods: qparampv, qparamsw, qparampx, htmlself, cmd, cmdg, htmlbar, htmlhid, htmlres, htmlself, eval, evaluate
qparampv
qparamsw
qparampx
htmlself
htmlhid
evaluate
Programming interface: evaluate, eval, cmd, cnd
Transaction commands implementations: cmdchk, cmdcrt, cmdqry, cmdhtm, cmdfrm, cmdhlp
cmdhlp
Current transaction command
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
-chk
Create CGI params with -crt default values for new record
Check if there is form editing operation.
Print HTML form fields for new, view or edit record
Current generic (general, global) transaction command is any -cmd command exept form exchanges like -frm, -ins, -upd.
Print Help page HTML, constructed with -form and -lists descriptions
Print HTML at the top of the list of records or form of record. By other words, print htmlbar and htmlhid.
Create CGI params with -qry default values for query parameters form
-qry
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.
param
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
Full CGI::Bus::tm execution. Like eval, but with starting HTTP, starting and ending HTML page. Uses '-htpgstart' and '-htpfstart' from parent CGI::Bus
Generate action bar HTML string dependent on options or -opflg, current transaction, -tbarl , -tbarr.
-opflg
-tbarr
Generate hidden HTML string. Hidden HTML contains saved parameters values like previous values of fields.
Generate transaction result HTML string - empty or success or error message.
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.
Prefix field or param name given to construct special name. Prefixes are -pxcb, -pxsw, -pxpv, -pxqc.
-pxcb
-pxsw
-pxqc
List (view) name queried or default
qparam call with -pxpv prefixed param names.
Get params names with prefix given or qparam call with prefixed param names. Empty prefix means non-prefixed names.
qparam call with -pxsw prefixed param names.
New -banner.
New !'c'reate/'i'nsert, !'d'elete, !'e'dit/'u'pdate, !'q'uery -opflg options. New cmdfe method. Changed htmlbar considering -vsd option.
cmdfe
-vsd
New experimantal _tsw_LSO / qloval / qlourl / qlowgh / qlowgl / qloparse interface to implement options embedded into views.
_tsw_LSO
qloval
qlourl
qlowgh
qlowgl
qloparse
evaluate executes now some CGI::Bus::upws '_run' commands as full-text 'SEARCH' or user 'SETUP'.
qlst may determine default view via '_' sign not only at the end of the view name, but at the end of the view label too.
qlst
htmlbar button set behaviour: 'Login' button moved after 'Back' and will be always shown for guests; 'Login' button small picture resized; 'List' button in the record form replaced with 'Query' button and excluded when record editing; 'Edit' button will not be shown for guests.
cmdfrm 'l'ist, 's'elect, '"'quoted only fields (-flg =~/^["'ls]*$/) are not considered in form layout now
cmdfrm text area formatting improved with ' ' signs and '<code>' tags as needed.
cmdfrm lost line breacks when displaying text areas with embedded URLs
-logo slot
-logo
htmlbar and cmdhlp behaviour for '<' -opflg.
-refresh view and common slots
-refresh
-htmlts, -htmlte, -width common slots
-htmlts
-htmlte
-width
-rowsav1 and -rowsav2 events inside cmdsql.
cmdsql
- textarea fields displays linebreaks when viewed - 'Select' and 'Edit' command buttons appearance - '!s'elect record button '-opflg' value
- imagebuttons toolbar using -iurl slot; uncomment at the beginning of the source to disable; see issue in the source code
Implemented and Documented.
- review & test & debug
- how to move 'qparampv' and 'qparamsw' methods up to the application object?
Andrew V Makarow <makarow at mail.com>
24 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
'=item' outside of any '=over'
To install CGI::Bus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Bus
CPAN shell
perl -MCPAN -e shell install CGI::Bus
For more information on module installation, please visit the detailed CPAN module installation guide.