NAME

CGI::Bus - Web and DBI Application object

SYNOPSIS

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

DESCRIPTION

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.

Currently implemented and tested on Win32 Apache and IIS.

SUBOBJECTS

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.

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.

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.

SOLUTIONS

See AUTOLOAD, reset, print, CGI::Bus::Base

CLASSIFICATION

Creation and Setup

new, set, -import, -reimport

Internals

AUTOLOAD, launch, -classes, -cache, $CGI::Bus::SELF, reset, -reset, DESTROY, -debug, microtest

Subobjects and Features Embedded

cgi, -cgi, fcgicount, request, dbi, -dbi, oscmd

Error and Message processing

die, warn, problem, -problem, pushmsg, pushlog, -pushlog

Language

lngname, -lngname, lngload, lng

Locations

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

Utils

strtime, timestr, timeadd, cptran, ishtml, dumpout, dumpin, orarg

HTML Generation

httpheader, -httpheader, htmlstart, -htmlstart, htpgstart, -htpnstart, -htpgstart, -htpfstart, -htpgtop, htpgend, -htpgbot, htpfstart, htpfend, htmlescape, urlescape, htmlddlb, htmltextarea, htmltextfield, htmlfsdir

Parameters Handling

qparam, param, qparamh, qrun

User Name

userauth, userauthopt, user, useron, -user, -usercnv, usercn, usersn, unames, uguest, uadmin, -uadmins, usdomain, -usdomain, userver, -userver, ugroups, -ugroups, -ugrpcnv, ugnames, uglist, -uglist, unamesun, -login

SLOTS

Are available via set and several explicitly refered here methods.

$CGI::Bus::SELF

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

-bpath

-burl

Binary path, URL Default is path of script running. Cached and used by bpath, burl. See also Locations.

-cache

Data cache hash ref for stable methods results to speed up by skipping some code evaluations.

-cgi

CGI predefined object, created in initialize

-classes

Classes to autocreate Objects: {-key=>class,...}. See also -import, -reimport, -reset.

-dbi

DBI predefined object

-debug

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.

-dpath

Data path. Default is tpath. Cached and used by dpath. See also Locations.

-fcgicount

Counter of CGI::Fast loops. Used inside fcgicount.

-fcgimax

Margin of CGI::Fast loops. And FastCGI enable flag also. Used inside fcgicount.

-fpath

-furf

-furl

File store path, filesystem URL, URL. Default is ppath, fpath, purl. Cached and used by fpath, furf, furl See also Locations.

-hpath

-hurf

-hurl

Homes store path, filesystem URL, URL. Default is ppath, hpath, purl. Cached and used by hpath, hurf, hurl See also Locations.

-htmlstart

HTML start hash ref, for htmlstart

-htpfstart

Form pages HTML start hash ref, for htmlstart in CGI::Bus::tmsql and etc, see also -htpgstart, -htpnstart

-htpgbot

HTML page end HTML string, for htpgend

-htpgstart

Pages (views, lists) HTML start hash ref, for htmlstart in CGI::Bus::tmsql and etc, see also -htpfstart, -htpnstart

-htpgtop

HTML page begin HTML string, for htpgstart

-htpnstart

Navigator panes HTML start hash ref, for htmlstart in CGI::Bus::upws, see also -htpgstart, -htpfstart

-httpheader

HTTP header hash ref, for httpheader

-iurl

Apache images URL to use instead of text only behaviour. Default is undef, standard is '/icons'.

-import

-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.

-lngname

Name and charset of the language to use. See lngname

-login

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.

-ppath

-purl

Publish path, URL. Default is $ENV{DOCUMENT_ROOT} ||$ENV{PATH_TRANSLATED} ||'.'; surl. Cached and used by ppath, purl. See also Locations.

-pushlog

Log file name to push messages to

-qpath

-qurl

Query (script) Path, URL. Cached and used by qpath, qurl. See also Locations.

-reimport

-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

-reset => {-slot => 1,...}

slots to destroy when reusing application object. See also -import, -reimport, new.

-spath

-surl

Site path, URL Cached and used by spath, surl. See also Locations.

-tpath

Temporary files path. Default is based on CGI $TempFile::TMPDIRECTORY ||$ENV{TMP} ||$ENV{TEMP}. Cached and used by tpath. See also Locations.

-uadmins

List (array ref) of administrators or sub{} to check current user as administrator. Used by uadmin

-uglist

Users and groups list optional sub{}. uglist method evaluates this sub or uses it's own code.

-ugroups

User groups list optional sub{}. ugroups method evaluates this sub or uses it's own code.

-ugrpcnv

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})

-urfcnd

Filesystem URLs (file://) condition sub{}. Condition to use '-urf's instead of '-url's. See also urfcnd

-usdomain

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

User name get optional sub{}. user method evaluates this sub or returns user name got from web server.

-userver

User names Server name optional evaluation sub{}. userver method evaluates this sub or returns value from CGI::Bus::uauth. See also -usdomain, usdomain

-userauth

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'.

-usercnv

User name conversion optional sub{} to convert or filter user names to be returned by user. Example:

$g->set(-usercnv=>sub{lc($_[0]->usercn)});

METHDOS

AUTOLOAD

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

bpath -> binary path

bpath (subpath) -> binary subdirectory path

Binary path cached in -bpath with given subpath added. See also Locations.

burl -> binary URL

burl (subpath) -> binary subdirectory URL

burl (subpath, param => value,...) -> binary subdirectory URL

Binary URL cached in -burl with given subpath and parameters added. See also Locations.

cgi () -> CGI object

CGI predefined object stored in -cgi

cptran (fromCP, toCP, strings) -> translated

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 (constructor args) -> new DBI object

dbi -> current DBI object

Create new or return current DBI object stored in -dbi

DESTROY

Destructor, uses reset for almost all application object. See also Creation and Setup, Internals

die (?message) -> died

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

dpath -> data path

dpath (subpath) -> data subdirectory path

Data path cached in -dpath with given subpath added. See also Locations.

dumpin ( data string ) -> data ref

dumpout ( data ref ) -> data string

Stringify and destringify data structure with Data::Dumper and Safe

evalsub (sub, arguments) -> result

Evals sub given with local $CGI::Bus::SELF set to application object.

CGI::Bus::fcgicount (-fcgimax=>number, constructor args) -> success self

fcgicount (self, -fcgimax=>number, constructor args) -> success self

fcgicount -> success self

Interface for CGI::Fast. Uses -fcgicount, -fcgimax. May be used in constructs like:

while ($s =CGI::Bus::fcgicount($s,-fcgimax=>...)) {};
while (1) {$s =CGI::Bus::new($s,-fcgimax=>...); ...; last until $s->fcgicount};

fpath ( ?subpath ) -> File store path

furf ( ?subpath, ?args ) -> File store file URL

furl ( ?subpath, ?args ) -> File store URL

Location of file store cached in -fpath, -furf, -furl with given subpath added. Default is ppath, fpath, purl. See also Locations.

hpath ( ?subpath ) -> Home store path

hurf ( ?subpath, ?args ) -> Home store file URL

hurl ( ?subpath, ?args ) -> Home store URL

Location of home store cached in -hpath, -hurf, -hurl with given subpath added. Default is ppath, hpath, purl. See also Locations.

htmlddlb (name, data, field name,...) -> HTML drop-down list box

htmlddlb (name, data, [field name => label],...)

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.

htmlescape (text) -> escaped

CGI::escapeHTML call. See also urlescape.

htmlfsdir ( name, edit?, allow edit?, files path, URL, ?filesystemURL, ?rows, ?cols )

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.

htmlstart (?parameters) -> start html string

Start HTML string using CGI::start_html(?parameters) call. Default parameters are given from -htmlstart slot.

htmltextarea (-name=>...,-arows=>min, -hrefs=>1,...) -> textarea 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.

htmltextfield (-name=>..., -asize=>min) -> text field HTML

Like CGI::textfield call, but with additional attributes: -asize=>min autosizes widget to it's content. Implemented in CGI::Bus::wg.

htpfend -> end form and page HTML

End HTML form and page string using htpgend.

htpfstart (?httpheader, ?htmlstart) -> start page and form HTML

Start HTML page and form string using htmlstart, -htpfstart.

htpgend () -> end page HTML

End HTML page string using -htpgbot and CGI->end_html call.

htpgstart (?httpheader, ?htmlstart) -> start page HTML

Start HTML page string using httpheader, htmlstart, -htpgstart, -htpgtop

httpheader (?parameters) -> HTTP header string

HTTP header string using CGI::header(?parameters). Default parameters are given from -httpheader slot.

ishtml ( text ) -> is text HTML formatted?

Detect HTML format of text: beginning with '<' and one of well-known HTML tags.

launch (class => constructor args) -> object

launch -> class(constructor args) -> object

Creates object unbinded to CGI::Bus object. Uses AUTOLOAD like principles, but does not attaches object created to CGI::Bus object.

lng (msg) -> language message variants array ref

lng (number, msg) -> language message

Message text in current language. 0 - short message, label. 1 - long message, comment or description.

lngload (class, ?language) -> language base hash ref

Loads and returns language base hash ref for class given.

lngname () -> language name with charset

lngname (language to set)

Returns current language name with charset. Default is $ENV{HTTP_ACCEPT_LANGUAGE} and $ENV{HTTP_ACCEPT_CHARSET}.

microtest

Prints some diagnostics, used in debug mode.

new ( -slot=>value...) -> new application object

new (?reuse,...)...

Create new or reuse existed application object. See also Creation and Setup, Internals

orarg (sub, arg,...) -> succeeded arg

orarg (function string, arg,...) -> succeeded arg

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.

oscmd (?'-hi', command, args) -> success

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.

param (args) -> CGI subobject param call

CGI subobject param call, optimising AUTOLOADing. See also qparam

ppath -> publish path

ppath (subpath) -> publish subdirectory path

Publish path cached in -ppath with given subpath added. See also Locations.

print -> print object

print (?args to print) -> print object

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

problem (?message) -> problem set

Set problem flag or message -problem. See also Error and Message processing

purl -> publish URL

purl (subpath) -> publish subdirectory URL

purl (subpath, param => value,...) -> publish subdirectory URL

Publish URL cached in -purl with given subpath and parameters added. See also Locations.

pushlog ( messages )

Push messages strings to -pushlog file

pushmsg -> messages []

pushmsg (messages) -> messages []

Retrieve and store messages strings. Accumulate messages to display.

qparam ([parameters names]) -> [parameters values]

qparam ([names]=>[values]) -> [values]

qparam ({name=>value,...}) -> {name=>value,...}

qparam (?CGI param args) -> CGI param call

qparamh ([names]) -> {name=>value,...}

CGI::param call extended

qpath -> query (script) path

qpath (subpath) -> query (script) subdirectory path

Query (script running) path including script name cached in -qpath with given subpath added. See also Locations.

qrun () -> run parameter value

Query to run: CGI::param('_run') ||CGI::param('') ||CGI::param('run')

qurl -> query (script) URL

qurl (subpath) -> query (script) subdirectory URL

qurl (subpath, param => value,...) -> query (script) subdirectory URL

Query (script running) URL including script name cached in -qurl with given subpath and parameters added. See also Locations.

request () -> web server request object

Predefined web server request object - something like cgi or Apache->request.

reset

reset ({-slot=>1,...})

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

set (-slot) -> value

set (-slot=>value,...) -> application object

Retrieve or set application object slots. See also Creation and Setup

spath -> site path

spath (subpath) -> site subdirectory path

Site path cached in -spath with given subpath added. See also Locations.

strtime ( ?mask, ?@time ) -> string

strtime ( ?mask, ?time seconds ) -> string

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).

surl -> site URL

surl (subpath) -> site subdirectory URL

surl (subpath, param => value,...) -> site subdirectory URL

Site URL cached in -purl with given subpath and parameters added. See also Locations.

timeadd (time seconds, years, ?months, ?days, ?hours, ?minutes ,?seconds) -> time seconds

Add values given to time given.

timestr ( ?mask, time string ) -> time seconds

Convert time string by mask to compatible with time number of seconds. See strtime for mask constructions and default mask.

tpath -> temporary files path

tpath (subpath) -> temporary subdirectory path

Temporary files path cached in -tpath with given subpath added. See also Locations.

uadmin () -> administrator?

uadmin ( user or group name ) -> administrator?

uadmin ( [] ) -> [ managed users ]

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?

uglist ( ?'-ug' ) -> [users and groups list]

uglist ( ?'-ug', {}, ?label width ) -> {name => label,...}

List all users and groups. Options are 'u'sers, 'g'roups. See also -uglist

ugnames () -> [user and group names]

Names and groups of current user, including unames and ugroups

ugroups () -> [user groups]

Groups current user belongs to. See also -ugroups.

uguest (?user name) -> guest?

Is current user or user name given a guest or authenticated?

unames () -> [user names]

Names of current user, including user, usercn, lowercase of this names. See also ugnames.

unamesun (user names list) -> [unique names]

Convert user names list to contain only unique names. Remove redundant lowercases and common names as possible.

urfcnd () -> use URFs?

Condition to use filesystem URLs (file://) instead of HTTP URLs (http://). This depends on browser type (see source code) and -urfcnd.

urlescape (text) -> escaped

CGI::escape call. See also htmlescape.

usdomain () -> User names Server's Domain name

usdomain (set name)

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 () -> user name

user (?user name) -> user name set

User name of the current user. See also -user.

userauth (?redirect) -> user name

Authenticate current user if guest. See also -userauth, CGI::Bus::uauth

userauthopt () -> user name

Authenticate current user if guest and required by '_auth' or '_login' CGI param. Uses userauth.

usercn (?username) -> user name common part

Common name of user, without domain part

userds (?username) -> user name as directory structure

User name as directory structure

userfn (?username) -> user name as filename

User name as filename

useron () -> user original name

Original name of the current user, user value before -usercnv

usersn (?username) -> user shorten name

User shorten name, with usdomain value removed if present.

userver () -> User names Server name

userver (set name)

User names Server name - Windows NT or DNS host name. See also -userver, CGI::Bus::uauth.

warn (?message) -> warning

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

VERSION

07/05/2002 - 18/05/2002

New

- tmsql.pm- '-htmlts', '-htmlte', '-gant1', '-gant2', '-htmlg1' view slots.
- tmsql.pm: '-rowsav1' and '-rowsav2' events.

Changed

- 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

Issue on tm.pm record 'Select' and 'Edit' command buttons

'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.

05/04/2002 - 06/05/2002

New & Changed

- tmsql.pm - MySQL 'LIMIT rows' clause generation
- uauth.pm - attempting to use a Windows2000 ADSI, see issues in 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

15/10/2001 - 23/03/2002

Implemented and Documented.

ToDo

-  -dpath, -ppath, -purl default values review
-  username SSL value review
-  naming review
-  review & test & debug

AUTHOR

Andrew V Makarow <makarow@mail.com>

cpanm CGI::Bus

perl -MCPAN -e shell
install CGI::Bus