SharkAPI::Form.pm -- Form Functions
use SharkAPI::Form;
$DBF_Sample::form = SharkAPI::Form->new(app_obj => $DBF_Sample::app,
db_obj => $DBF_Sample::db);
...
# save
$DBF_Sample::form->save('customer_form');
This module contains functions for form processing. Forms are simply
a collection of fields grouped together by the form name. These functions
help with clearing, setting values, etc. If a SharkAPI::DB object is
passed during object construction then the Data Descriptor group(s) defined
along with each Form Descriptor will be called during save, clear, etc.
This allows forms to be connected to a DBI datasource.
The form functions bind GUI objects to Database or custom objects.
This is used to save a collection of fields to a particular database table or
custom save functions. The ``snapide'' tool is used to configure the Form
objects.
Here is the object hierarchy:
Form Descriptor Object
|
|
+--> Data Descriptor Object [ --> Datasource Object ]
|
|
+--> Data Field Object
+--> Data Field Object
.
.
The Form descriptor object defines the form object as a whole. A Data
Descriptor Object defines the table or database object
that is to be used for saving/loading/etc data. Each Data Field Object
then has attributes that contain the widget name and Data Descriptor
name, along with other attributes that define the field, i.e. datatype,
key type, insert/update permissions, etc.
If a Data Descriptor does not have a Datasource Object specified in its
attribute list then the (default) current connection passed to the
SharkAPI::Form object during creation.
A Form object has a state of ``NEW'' or ``EXISTS''. In addition a data descriptor
can be ``CLEAN'' or ``DIRTY''. This attribute is managed by an internal structure
that holds the current value for each field. Thus if a screen value changes
then the internal value and the display value will be different and the
descriptor will be ``DIRTY''.
NOTE: If a radio or check button is part of a group then only one of
the widgets should have the Data Field Object added. The group is
treated as a group.
- new ( [ OPT => OPT_VALUE [,...]] )
-
New creates the Form object. Options are passed as keyword value pairs.
Recognized options are:
- app_obj
The SharkAPI::App object containing the forms.
- db_obj
The SharkAPI::DB object to be used for data descriptor forms. If defined
then each call to a form method will search and operate on data descriptors.
- log_obj
Should be passed a function reference for logging operations of this class.
The function will be called with one argument containing the string to log.
- log_fetch
If set to a positive value the log funtion will be called with fetched values.
This defaults to ``0''.
- errstr
Contains the current error string.
- clear ( $formname )
-
This function will clear the fields on the specified form. The form state
will be set to NEW.
- state ( $formname )
-
This function returns the state of the named form. Valid states
for a descriptor are ``NEW'' or ``EXISTS''. A state of ``EXISTS'' means that
the data was pulled from a datasource, i.e. needs to be updated vs.
inserted.
- validate ( $formname )
-
This function calls the Validate objects for the specified form.
Currently the Validate object contains three types of
validation, setup through ``snapide'': regexp - regular
expression validation, must enter - field needs to have some
data entered, and no update - after the descriptor enters the ``EXISTS''
state then the data in field cannot change. If any field fails
validation the return value will be zero. The class variable
'errstr' contains the message from the validation object.
-
$DBF_Sample::form->{'errstr'}
- load ( $formname )
-
This function will load the fields associated with a descriptor based on
the defined key fields. If an error occurs or more than one row is found
then the function will fail and set 'errstr'.
- load_count ( $formname )
-
This function returns the number of rows that would be returned if the
load function were called on the specified data descriptor. This
function is useful for displaying a pick list if needed.
- save ( $formname )
-
This function will insert or update the database record based on the
state of the form object. If the save operation was sucessful then
the state of the form is set to ``EXISTS'' and return 1. If the function
fails then a zero value is returned and 'errstr' is set.
- delete ( $formname )
-
This function will delete the database record defined in the descriptor.
The descriptor state must be ``EXISTS''.
- sync_to ( $formname )
-
This function will copy the values from the internal structure to the
screen for the specified form. This can be thought of as
an ``undo'' or ``cancel'' type operation. The descriptor will be ``CLEAN''.
- sync_from ( $formname )
-
This function will copy the screen value to the internal structure
for the specified data descriptor. The descriptor will be ``CLEAN''.
- clean ( $formname )
-
This function will return ``0'' if the form not ``CLEAN''.
It works by comparing the screen value against the internal array.
- keyset ( $formname )
-
This function sets the fields that are defined as keys by having a
``keytype'' attribute. The function called is based on the keytype
and the value returned is populated on the form. Currently only
the keytype of ``auto'' is supported, and the seqkey table is used.
- set ( $formname, [ FIELD => FIELD_VALUE [,...]] )
-
This method will set a group of fields on the specified form. The field
name/value pairs are passed as a hash.
-
Example:
-
$form->set('customer_form', { name => $name,
phone => $phone,
address => $address,
city => $city,
state => $state,
zip => $zip });
- get ( $formname, [field1 [,...]] )
-
This function returns an array of the values stored in the fields
specified by field names passed. The values in the array are ordered
by the order of the passed field name values. If no field names are passed
then all fields will be returned in the form a field name/value pair hash.
-
Example:
-
@customer_data = $form->get('customer_form', 'name, 'phone',
'address','city','state','zip');
Or:
-
($name, $phone, $address, $city, $state, $zip ) =
$form->get('customer_form','name','phone','address','city',
'state', 'zip');
-
Or:
-
my %field_hash = $form->get('customer_form');
-
print "Name = ", $field_hash{name}, "\n";
The db_form example in the samples directory contains a single working
form that reads a table called ``customers''. The OIX data is defined using
``snapide''. There are two scripts:
#----------------------------------------------------
# Startup Perl Script
#
# This file contains the Perl executed at startup
#
#----------------------------------------------------
package DBF_Sample;
use strict;
use DBI;
use SharkAPI;
require SharkAPI::App;
#
# Init SharkAPI
#
$DBF_Sample::app = new SharkAPI::App(
app_module => 'MAIN',
run_mode => 'Gtk',
oix_object => $SnapRun::xml->{oix});
#
# Boot Via SharkAPI
#
$DBF_Sample::app->boot(snap_obj=>$SnapRun::xml);
#
# Init Console
#
if ($Snapper::debug) {
print " building console GladeXML object for debugging...\n";
$DBF_Sample::console = new SharkAPI::Console($DBF_Sample::app);
$DBF_Sample::console->console_logging('SQL',1,1);
$DBF_Sample::console->console_logging('PERL',1,1);
$DBF_Sample::console->console_logging('MSG',1,1);
print " --> done.\n";
$DBF_Sample::console->console_pump(0);
$DBF_Sample::console->console_show();
}
#
# End Console Section
#
#
# Drop into main loop
#
$DBF_Sample::app->main();
#
# Callbacks...
#
sub DBF_Sample::log {
my ($type, $data, $prefix, $level) = @_;
$DBF_Sample::console->console_print($type, $data, $prefix, $level)
if defined $DBF_Sample::console;
}
sub DBF_Sample::quit {
my ($w, $d) = @_;
$DBF_Sample::app->quit();
}
1;
#
# New Script
#
package DBF_Sample;
use strict;
sub DBF_Sample::select {
my ($widget, $row, $column) = @_;
# get data
my $data = $DBF_Sample::grid->grid_data($row);
# clear
$DBF_Sample::form->clear('customer_form');
# set key
$DBF_Sample::form->set('customer_form', {'customer_number' => $data->[0]});
# load it
$DBF_Sample::form->load('customer_form');
}
sub DBF_Sample::customer_clear {
my ($widget, $data) = @_;
return if DBF_Sample::check_connect();
# clear
$DBF_Sample::form->clear('customer_form');
}
sub DBF_Sample::customer_delete {
my ($widget, $data) = @_;
return if DBF_Sample::check_connect();
# delete
$DBF_Sample::form->delete('customer_form');
DBF_Sample::execute();
}
sub DBF_Sample::customer_save {
my ($widget, $data) = @_;
return if DBF_Sample::check_connect();
# save
$DBF_Sample::form->save('customer_form');
DBF_Sample::execute();
}
sub DBF_Sample::connect {
my ($w, $d) = @_;
$DBF_Sample::app->setvals(connect_type => 'dbi:Pg',
connect_server => '',
connect_database => 'sharkapi',
connect_user => 'shark',
connect_password => '');
$DBF_Sample::app->show("connect");
}
sub DBF_Sample::connect_cancel {
my ($w, $d) = @_;
$DBF_Sample::app->hide("connect");
return $DBF_Sample::app->true();
}
sub DBF_Sample::connect_ok {
my ($w, $d) = @_;
# Grab Info
my ($dsn, $server, $database, $user, $pass) =
$DBF_Sample::app->getvals(['connect_type', 'connect_server',
'connect_database', 'connect_user',
'connect_password']);
if ($server eq "" && $database eq "") {
$DBF_Sample::app->setval("main_appbar","Must set Server or Database...");
undef $DBF_Sample::db;
return $DBF_Sample::app->false();
}
# Build DSN
my $sep = ':';
$server && do {
$dsn .= $sep . 'server=' . $server;
$sep = ';';
};
$database && do {
for ($dsn) {
/Sybase/ && do {
$dsn .= $sep . 'database=' . $database;
last;
};
/Pg/ && do {
$dsn .= $sep . 'dbname=' . $database;
last;
};
}
$sep = ';';
};
$DBF_Sample::app->setval("main_appbar", "Login: $user...");
undef $DBF_Sample::db if $DBF_Sample::db;
undef $DBF_Sample::grid if $DBF_Sample::grid;
$DBF_Sample::db = SharkAPI::DB->new($dsn, $user, $pass,
{ AutoCommit => 1,
PrintError => 0,
RaiseError => 0 });
if (!$DBF_Sample::db || !$DBF_Sample::db->{'dbh'}) {
$DBF_Sample::app->setval("main_appbar", "Login: failed...");
undef $DBF_Sample::db;
return $DBF_Sample::app->false();
} else {
$DBF_Sample::db->db_log(sub {my ($data) = @_;DBF_Sample::log('SQL',$data);});
$DBF_Sample::app->setval("main_appbar", "Login: OK");
$DBF_Sample::app->hide("connect");
# create form object or update DB object
if ($DBF_Sample::form) {
$DBF_Sample::form->db_obj($DBF_Sample::db);
} else {
$DBF_Sample::form = SharkAPI::Form->new(app_obj => $DBF_Sample::app,
db_obj => $DBF_Sample::db);
}
# setup grid object
$DBF_Sample::grid = SharkAPI::Grid->new($DBF_Sample::app,
'result_window',
$DBF_Sample::db);
$DBF_Sample::grid->grid_handler('select_row', \&DBF_Sample::select);
DBF_Sample::execute($w, $d); # populate grid
return $DBF_Sample::app->true();
}
}
sub DBF_Sample::execute {
my ($w, $d) = @_;
my $query = q{select custnum as "key1",
custnum as "Cust Num",
custname as "Name",
address as "Address",
phone as "Phone",
active as "Active"
from customers
order by custnum
};
return if DBF_Sample::check_connect();
$DBF_Sample::grid->grid_execute_sql($query,1);
}
sub DBF_Sample::check_connect {
!$DBF_Sample::db && do {
$DBF_Sample::app->setval("main_appbar", "Connect First!!!");
return 1;
};
return 0;
}
1;
perl(1).
Snapper(3).
SharkAPI(3).
Bill Walz, bill@landsharklinux.com
The SharkAPI::Form module is Copyright (c) 2002 Albacore Technology, LLC
The SharkAPI::Form module is commercial licensed software
|
