CGI::Bus - Web and DBI Application object
use CGI::Bus; $s =CGI::Bus->new(); $s->print->htpfstart; # start http, page, form $s->cgi->... # -> CGI object $s->dbi->... # -> DBI object $s->tmsql->... # -> SQL database interface object ........ $s->print->htpfend # end form and page
A web database with record versioning, access control at the record level, and file attachments was needed for me, see examples and CGI::Bus::tmsql... Modular structure and some codes implemented due to infrastructural needs.
This module is to provide based on CGI module core application object to load, contain and manage any other used by application objects, methods and data. Several slots and methods may be useful predefined and added also. Several automatic subobject classes may be useful provided. Perhaps, this looks something like Jellybean or PAS, but is not so complex or so right.
Jellybean
PAS
Currently implemented and tested on Win32 Apache and IIS.
CGI::Bus::Base is base class for automatic subobjects.
CGI::Bus::file is a file object encapsulating IO::File object.
CGI::Bus::fut is a file and directory utils library.
CGI::Bus::psp is a very simple and little HTML/Perl script processor, like something as Apache::ASP, HTML::Embperl, HTML::HTPL, HTML::Mason.
CGI::Bus::smtp is a simple SMTP sender, based on Net::SMTP.
CGI::Bus::tm is a database Transaction page Manager to view and edit data, the base and simplest case of CGI::Bus::tmsql below.
CGI::Bus::tmsql is an SQL database user interface to view and edit data, page transaction manager, another than DBIx::HTMLView, eXtropia or MOT.
eXtropia
MOT
CGI::Bus::uauth is default or base user authentication class, provides user, ugroups, uglist methods. It translates web server authentication and uses platform specific methods.
user
ugroups
uglist
CGI::Bus::udata is a user data store.
CGI::Bus::upws is a user personal work space.
CGI::Bus::wg is a collection of HTML widgets.
See AUTOLOAD, reset, print, CGI::Bus::Base
AUTOLOAD
reset
print
new, set, -import, -reimport
new
set
-import
-reimport
AUTOLOAD, launch, -classes, -cache, $CGI::Bus::SELF, reset, -reset, DESTROY, -debug, microtest
launch
-classes
-cache
$CGI::Bus::SELF
-reset
DESTROY
-debug
microtest
cgi, -cgi, fcgicount, request, dbi, -dbi, oscmd
cgi
-cgi
fcgicount
request
dbi
-dbi
oscmd
die, warn, problem, -problem, pushmsg, pushlog, -pushlog
die
warn
problem
-problem
pushmsg
pushlog
-pushlog
lngname, -lngname, lngload, lng
lngname
-lngname
lngload
lng
qpath, -qpath, qurl, -qurl, spath, -spath, surl, -surl, bpath, -bpath, burl, -burl, dpath, -dpath, tpath, -tpath, ppath, -ppath, purl, -purl, fpath, -fpath, furf, -furf, furl, -furl, hpath, -hpath, hurf, -hurf, hurl, -hurl, urfcnd, -urfcnd, -iurl
qpath
-qpath
qurl
-qurl
spath
-spath
surl
-surl
bpath
-bpath
burl
-burl
dpath
-dpath
tpath
-tpath
ppath
-ppath
purl
-purl
fpath
-fpath
furf
-furf
furl
-furl
hpath
-hpath
hurf
-hurf
hurl
-hurl
urfcnd
-urfcnd
-iurl
strtime, timestr, timeadd, cptran, ishtml, dumpout, dumpin, orarg
strtime
timestr
timeadd
cptran
ishtml
dumpout
dumpin
orarg
httpheader, -httpheader, htmlstart, -htmlstart, htpgstart, -htpnstart, -htpgstart, -htpfstart, -htpgtop, htpgend, -htpgbot, htpfstart, htpfend, htmlescape, urlescape, htmlddlb, htmltextarea, htmltextfield, htmlfsdir
httpheader
-httpheader
htmlstart
-htmlstart
htpgstart
-htpnstart
-htpgstart
-htpfstart
-htpgtop
htpgend
-htpgbot
htpfstart
htpfend
htmlescape
urlescape
htmlddlb
htmltextarea
htmltextfield
htmlfsdir
qparam, param, qparamh, qrun
qparam
param
qparamh
qrun
userauth, userauthopt, user, useron, -user, -usercnv, usercn, usersn, unames, uguest, uadmin, -uadmins, usdomain, -usdomain, userver, -userver, ugroups, -ugroups, -ugrpcnv, ugnames, uglist, -uglist, unamesun, -login
userauth
userauthopt
useron
-user
-usercnv
usercn
usersn
unames
uguest
uadmin
-uadmins
usdomain
-usdomain
userver
-userver
-ugroups
-ugrpcnv
ugnames
-uglist
unamesun
-login
Are available via set and several explicitly refered here methods.
Package variable, pointer to current CGI::Bus object. local $SELF is set within some methods for use by external objects or methods. See also evalsub
CGI::Bus
evalsub
Binary path, URL Default is path of script running. Cached and used by bpath, burl. See also Locations.
Locations
Data cache hash ref for stable methods results to speed up by skipping some code evaluations.
CGI predefined object, created in initialize
initialize
Classes to autocreate Objects: {-key=>class,...}. See also -import, -reimport, -reset.
DBI predefined object
Debug Mode: add 1 - verbose operation messages at the bottom of HTML pages, 2 - some debug values as HTML comment, 3 - debug values at the bottom of HTML pages, 4 - results of some methods calls.
Data path. Default is tpath. Cached and used by dpath. See also Locations.
Counter of CGI::Fast loops. Used inside fcgicount.
Margin of CGI::Fast loops. And FastCGI enable flag also. Used inside fcgicount.
File store path, filesystem URL, URL. Default is ppath, fpath, purl. Cached and used by fpath, furf, furl See also Locations.
Homes store path, filesystem URL, URL. Default is ppath, hpath, purl. Cached and used by hpath, hurf, hurl See also Locations.
HTML start hash ref, for htmlstart
Form pages HTML start hash ref, for htmlstart in CGI::Bus::tmsql and etc, see also -htpgstart, -htpnstart
HTML page end HTML string, for htpgend
Pages (views, lists) HTML start hash ref, for htmlstart in CGI::Bus::tmsql and etc, see also -htpfstart, -htpnstart
HTML page begin HTML string, for htpgstart
Navigator panes HTML start hash ref, for htmlstart in CGI::Bus::upws, see also -htpgstart, -htpfstart
HTTP header hash ref, for httpheader
Apache images URL to use instead of text only behaviour. Default is undef, standard is '/icons'.
-import => {'use...'=>{-method=>call,...},...} -import => {'use...'=>[method,...],...} -import => {-key=>class}
Add Classes or Methods and Packages. This slot does not exists, it is used only as set parameter to fill other slots or -classes slot.
Name and charset of the language to use. See lngname
Login screen URL. Used by userauth and CGI::Bus::uauth. If login script URL ends with '/' sign, it is treated as authenticated location, and current script name will to be appended.
Publish path, URL. Default is $ENV{DOCUMENT_ROOT} ||$ENV{PATH_TRANSLATED} ||'.'; surl. Cached and used by ppath, purl. See also Locations.
Log file name to push messages to
Query (script) Path, URL. Cached and used by qpath, qurl. See also Locations.
-reimport => {-key=>class,...} -reimport => [-key,...] -reimport => -key
Add Classes or slots to reset when reusing application object. This slot does not exists, it is used only as set parameter to fill -reset or -classes slots. See also -import, -reset, new.
-reset => {-slot => 1,...}
slots to destroy when reusing application object. See also -import, -reimport, new.
Site path, URL Cached and used by spath, surl. See also Locations.
Temporary files path. Default is based on CGI $TempFile::TMPDIRECTORY ||$ENV{TMP} ||$ENV{TEMP}. Cached and used by tpath. See also Locations.
List (array ref) of administrators or sub{} to check current user as administrator. Used by uadmin
Users and groups list optional sub{}. uglist method evaluates this sub or uses it's own code.
User groups list optional sub{}. ugroups method evaluates this sub or uses it's own code.
User groups names conversion optional sub{} to convert or filter user and group names to be returned by ugroups, uglist. Example:
$g->set(-ugrpcnv=>sub{$_[0]->usersn})
Filesystem URLs (file://) condition sub{}. Condition to use '-urf's instead of '-url's. See also urfcnd
User names Server's Domain name optional evaluation sub{}. usdomain method evaluates this sub or returns value from CGI::Bus::uauth. See also -userver, userver
User name get optional sub{}. user method evaluates this sub or returns user name got from web server.
User names Server name optional evaluation sub{}. userver method evaluates this sub or returns value from CGI::Bus::uauth. See also -usdomain, usdomain
User authentication optional sub{} or reference to list of authentication options. userauth evaluates this sub or calls CGI::Bus::uauth->'auth' if there is no current user. Authentication options will be passed to CGI::Bus::uauth->'auth'.
User name conversion optional sub{} to convert or filter user names to be returned by user. Example:
$g->set(-usercnv=>sub{lc($_[0]->usercn)});
Loads subobject or method requested in order: subobject or method defined via set(-import), CGI module method, automatic CGI::Bus subobject. Sets new object slot 'CGI::Bus' to application object. See also Creation and Setup, Internals
Creation and Setup
Internals
Binary path cached in -bpath with given subpath added. See also Locations.
Binary URL cached in -burl with given subpath and parameters added. See also Locations.
CGI
CGI predefined object stored in -cgi
Translates strings from codepage fromCP to codepage toCP, returns translated string or list of strings. Codepages may be 'oem', '866','ansi', '1251','koi' prone of koi8, '8859-5' prone of ISO 8859-5.
DBI
Create new or return current DBI object stored in -dbi
Destructor, uses reset for almost all application object. See also Creation and Setup, Internals
Error Stop, like CORE::die. Message with "\n" signs is considered to be for user, without "\n" is treated as software error and implemented via 'confess' or 'croak'. See also Error and Message processing, CGI::Carp
Error and Message processing
Data path cached in -dpath with given subpath added. See also Locations.
Stringify and destringify data structure with Data::Dumper and Safe
Evals sub given with local $CGI::Bus::SELF set to application object.
Interface for CGI::Fast. Uses -fcgicount, -fcgimax. May be used in constructs like:
-fcgicount
-fcgimax
while ($s =CGI::Bus::fcgicount($s,-fcgimax=>...)) {}; while (1) {$s =CGI::Bus::new($s,-fcgimax=>...); ...; last until $s->fcgicount};
Location of file store cached in -fpath, -furf, -furl with given subpath added. Default is ppath, fpath, purl. See also Locations.
Location of home store cached in -hpath, -hurf, -hurl with given subpath added. Default is ppath, hpath, purl. See also Locations.
Generate input helper drop-down list box HTML. Name is used as the common part of names of the HTML widgets - submits, scrolling_list, buttons, which names are generated by appending '_' sign and suffix. Data may be array ref with list of values, hash ref with internal and external values, sub{} to produce above. Other arguments are field names to fill with values. Field names with leading \t corresponds to multivalue fields. Implemented in CGI::Bus::wg.
CGI::escapeHTML call. See also urlescape.
CGI::escapeHTML
Generate filesystem directory editor HTML. This may be IE HTML IFRAME tag pointed to filesystem, URLs, or filefield for upload files and checkboxes to delete. Name is used as the common part of names of the HTML widgets. Implemented in CGI::Bus::wg.
Start HTML string using CGI::start_html(?parameters) call. Default parameters are given from -htmlstart slot.
CGI::start_html
Like CGI::textarea call, but with additional attributes: -arows=>min autosizes widget to it's content. -hrefs=>1 searches HTML hyperlinks in content and displays them. Implemented in CGI::Bus::wg.
CGI::textarea
Like CGI::textfield call, but with additional attributes: -asize=>min autosizes widget to it's content. Implemented in CGI::Bus::wg.
CGI::textfield
End HTML form and page string using htpgend.
Start HTML page and form string using htmlstart, -htpfstart.
End HTML page string using -htpgbot and CGI->end_html call.
end_html
Start HTML page string using httpheader, htmlstart, -htpgstart, -htpgtop
HTTP header string using CGI::header(?parameters). Default parameters are given from -httpheader slot.
CGI::header
Detect HTML format of text: beginning with '<' and one of well-known HTML tags.
Creates object unbinded to CGI::Bus object. Uses AUTOLOAD like principles, but does not attaches object created to CGI::Bus object.
Message text in current language. 0 - short message, label. 1 - long message, comment or description.
Loads and returns language base hash ref for class given.
Returns current language name with charset. Default is $ENV{HTTP_ACCEPT_LANGUAGE} and $ENV{HTTP_ACCEPT_CHARSET}.
Prints some diagnostics, used in debug mode.
Create new or reuse existed application object. See also Creation and Setup, Internals
Evaluates sub or function given with local $_ set to each arg until success. Returns successful arg. Example: orarg('-d','c:/home','c:/users') returns first existed directory.
Execute given OS command with output interception. Command and output will be stored with pushmsg if 'h'ide option is not set. Non zero return code will produce die if 'i'gnore option is not set. The last argument may be sub{} to print to STDIN of the command.
CGI subobject param call, optimising AUTOLOADing. See also qparam
Publish path cached in -ppath with given subpath added. See also Locations.
Prints arguments, returns object, that autoloads self or CGI method, prints result of it, returns itself. This is useful to shorten notation and some output control. Example: $u->print->h1('some header')->h2('some header') will print 'h1' and 'h2' tags given. See also: AUTOLOAD, cgi
Set problem flag or message -problem. See also Error and Message processing
Publish URL cached in -purl with given subpath and parameters added. See also Locations.
Push messages strings to -pushlog file
Retrieve and store messages strings. Accumulate messages to display.
CGI::param call extended
CGI::param
Query (script running) path including script name cached in -qpath with given subpath added. See also Locations.
Query to run: CGI::param('_run') ||CGI::param('') ||CGI::param('run')
Query (script running) URL including script name cached in -qurl with given subpath and parameters added. See also Locations.
Predefined web server request object - something like cgi or Apache->request.
Reset application object, i.e. when reusing - release subobjects to be reinitiated. Calls destructors of objects to be released, deletes 'CGI::Bus' slots of this objects. See also Creation and Setup, Internals
Retrieve or set application object slots. See also Creation and Setup
Site path cached in -spath with given subpath added. See also Locations.
Convert given date-time array into string using mask or format given. Mask constructions are 'yyyy', 'yy', 'mm', 'dd', 'hh', 'mm' or 'MM', 'ss', or POSIX strftime format. Default mask is 'yyyy-mm-dd hh:mm:ss'. Default time is localtime(time).
strftime
localtime
time
Site URL cached in -purl with given subpath and parameters added. See also Locations.
Add values given to time given.
Convert time string by mask to compatible with time number of seconds. See strtime for mask constructions and default mask.
Temporary files path cached in -tpath with given subpath added. See also Locations.
Is current user an administrator (checked against -uadmins) or an administrator of user or group given (checked against CGI::Bus::udata)? What names are managed by current user?
List all users and groups. Options are 'u'sers, 'g'roups. See also -uglist
Names and groups of current user, including unames and ugroups
Groups current user belongs to. See also -ugroups.
Is current user or user name given a guest or authenticated?
Names of current user, including user, usercn, lowercase of this names. See also ugnames.
Convert user names list to contain only unique names. Remove redundant lowercases and common names as possible.
Condition to use filesystem URLs (file://) instead of HTTP URLs (http://). This depends on browser type (see source code) and -urfcnd.
CGI::escape call. See also htmlescape.
CGI::escape
User names Server's Domain name - Windows NT or DNS domain name that may be included in user result as a part. See also -usdomain, CGI::Bus::uauth.
User name of the current user. See also -user.
Authenticate current user if guest. See also -userauth, CGI::Bus::uauth
-userauth
Authenticate current user if guest and required by '_auth' or '_login' CGI param. Uses userauth.
Common name of user, without domain part
User name as directory structure
User name as filename
Original name of the current user, user value before -usercnv
User shorten name, with usdomain value removed if present.
User names Server name - Windows NT or DNS host name. See also -userver, CGI::Bus::uauth.
Warning message, like CORE::warn. Message with "\n" signs is considered to be for user, without "\n" is treated as software warn and implemented via 'cluck' or 'carp'. See also Error and Message processing, CGI::Carp
- gwo.cgi - fields 'subject_v' and 'alist_v' used in all views, perconal views filters changed - uauth.pm - 'ugroups' on Win32 returns global group names prefixed with domain name for users from foreign domains. '-ugrpcnv' should be commented out. 'gwo.cgi' and 'notes.cgi' default group detection condition changed - gwo.cgi - fields 'subject_v', 'plist_v', 'alist_v' added to use in views, timeline view changed using this fields - timeline view supplied with predefined date margin columns from '-gant1' and '-gant2', so 'gwo.cgi' changed
- IE6 with IIS problem detected - on 'post' requests browser brings IIS to authentication/impersonalisation of the script to be not impersonalisated, but placed in the same directory as requiring web server authentication 'uauth.cgi' - tm.pm, tmsql.pm: '-refresh' view and common slots - tm.pm, tmsql.pm: '-htmlts', '-htmlte', '-width' common slots; '-width' field slot - cache-control http header mentioned in 'config.pl' - form tag generation with '-acceptcharset' attribute given from '-httpheader' - notes.cgi - 'mailto' field added - install-db.pl script to install or upgrade applications database - tmsql.pm: '-width' view attribute - tmsql.pm: 'explain select...' 'pushmsg' when listing data
- tmsql.pm: '-htmlts', '-htmlte', '-gant1', '-gant2', '-htmlg1' view slots. - tmsql.pm: '-rowsav1' and '-rowsav2' events.
- gwo.cgi - timeline chart view using '-gant1' and '-gant2' view slots. - gwo.cgi - mailsend code improved using '-rowsav1' event. - uauth.pm - filtered rows with space chars only 'findgrp.exe' may return. - tm.pm - textarea fields displays linebreaks when viewed - tm.pm - 'Select' command turns to view mode from edit mode, 'Edit' command removed from edit mode; '!s'elect command button '-opflg' flag - Bus.pm - '-debug=>3' recurse loop corrected
'Select' command may to be removed, 'Edit' command may to be restricted to appear when record viewing only. 'Select' may be replaced with 'refresh' browser action when record viewing. 'Select' may be useful to reject changes, but it is not very required. 'Select' may be useful to select record when it's key is available, so some flag in '-opflg' should be used to turn it on or off. 'Edit' command when editing loses changes and may be useful only to preview HTML entered by user. 'Edit' may be also associated with 'Select' when record editing.
- tmsql.pm - MySQL 'LIMIT rows' clause generation - uauth.pm - attempting to use a Windows2000 ADSI, see issues in the source code - uauth.pm, wg.pm - case insensitive sorting - notes.cgi - update for indexes - gwo.cgi - update for indexes, may be not useful - Bus.pm -debug slot levels - Bus.pm -iurl slot added - upws.pm - using icons based on -iurl slot value - all printed HTML tags and attributes are lowercase as from CGI module - tm.pm - image toolbar using -iurl slot, uncomment at the beginning of the source to disable
Implemented and Documented.
- -dpath, -ppath, -purl default values review - username SSL value review - naming review - review & test & debug
Andrew V Makarow <makarow@mail.com>
8 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.