Provided by: ledgersmb_1.3.25-1_all 
NAME
LedgerSMB::Form - Provides general legacy support functions and the central object.
SYNOPSIS
This module provides general legacy support functions and the central object
STATUS
Deprecated
COPYRIGHT
#====================================================================
# LedgerSMB
# Small Medium Business Accounting software
# http://www.ledgersmb.org/
#
# Copyright (C) 2006
# This work contains copyrighted information from a number of sources
# all used with permission.
#
# This file contains source code included with or based on SQL-Ledger
# which is Copyright Dieter Simader and DWS Systems Inc. 2000-2005
# and licensed under the GNU General Public License version 2 or, at
# your option, any later version. For a full list including contact
# information of contributors, maintainers, and copyright holders,
# see the CONTRIBUTORS file.
#
# Original Copyright Notice from SQL-Ledger 2.6.17 (before the fork):
# Copyright (C) 2000
#
# Author: DWS Systems Inc.
# Web: http://www.sql-ledger.org
#
# Contributors: Thomas Bayen <bayen@gmx.de>
# Antti Kaihola <akaihola@siba.fi>
# Moritz Bunkus (tex)
# Jim Rawlings <jim@your-dba.com> (DB2)
#====================================================================
#
# This file has undergone whitespace cleanup.
#
#====================================================================
#
# main package
#
#====================================================================
METHODS
new Form([$argstr])
Returns a reference to new Form object. The initial set of attributes is obtained
from $argstr, a CGI query string, or $ARGV[0]. All the values are run through
unescape to undo any URI encoding.
The version and dbversion attributes are set to hardcoded values; action, nextsub,
path, script, and login are filtered to remove some dangerous values. Both menubar
and lynx are set if path matches lynx.
$form->error may be called to deny access on some attribute values.
open_form()
This sets a $self->{form_id} to be used in later form validation (anti-XSRF measure).
check_form()
This returns true if the form_id was associated with the session, and false if not.
Use this if the form may be re-used (back-button actions are valid).
close_form()
Identical with check_form() above, but also removes the form_id from the session.
This should be used when back-button actions are not valid.
$form->debug([$file]);
Outputs the sorted contents of $form. If a filename is specified, log to it,
otherwise output to STDOUT.
$form->encode_all();
Does nothing and is unused. Contains merely the comment # TODO;
$form->decode_all();
Does nothing and is unused. Contains merely the comment # TODO
$form->escape($str[, $beenthere]);
Returns the URI-encoded $str. $beenthere is a boolean that when true forces a single
encoding run. When false, it escapes the string twice if it detects that it is
running on a version of Apache 2.0 earlier than 2.0.44.
Note that recurring transaction support depends on this function escaping ','.
$form->unescape($str);
Returns the unencoded form of the URI-encoded $str.
$form->quote($str);
Replaces all double quotes in $str with '"'. Does nothing if $str is a
reference.
$form->unquote($str);
Replaces all '"' in $str with double quotes. Does nothing if $str is a
reference.
$form->hide_form([...]);
Outputs hidden HTML form fields to STDOUT. If values are passed into this function,
only those $form values are output. If no values are passed in, all $form values are
output as well as deleting $form->{header}. Values from the $form object are run
through $form->quote, whereas keys/names are not.
Sample output:
<input type="hidden" name="login" value="testuser" />
$form->error($msg);
Output an error message, $msg. If a CGI environment is detected, this outputs an HTTP
and HTML header section if required, and displays the message after running it through
$form->format_string. If it is not a CGI environment and $ENV{error_function} is set,
call the specified function with $msg as the sole argument. Otherwise, this function
simply dies with $msg.
This function does not return. Execution is terminated at the end of the appropriate
path.
$form->finalize_request();
Stops further processing, allowing post-request cleanup on intermediate levels by
throwing an exception.
This function replaces explicit 'exit()' calls.
$form->info($msg);
Output an informational message, $msg. If a CGI environment is detected, this outputs
an HTTP and HTML header section if required, and displays the message in bold tags
without escaping. If it is not a CGI environment and $ENV{info_function} is set, call
the specified function with $msg as the sole argument. Otherwise, this function
simply prints $msg to STDOUT.
$form->numtextrows($str, $cols[, $maxrows]);
Returns the number of rows of $cols columns can be formed by $str. If $maxrows is set
and the number of rows is greater than $maxrows, this returns $maxrows. In the
determination of rowcount, newline characters, "\n", are taken into account while
spaces are not.
$form->dberror($msg);
Outputs a message as in $form->error but with $DBI::errstr automatically appended to
$msg.
$form->isblank($name, $msg);
Calls $form->error($msg) if the value of $form->{$name} matches /^\s*$/.
$form->header([$init, $headeradd]);
Outputs HTML and HTTP headers and sets $form->{header} to indicate that headers have
been output. If called with $form->{header} set or in a non-CGI environment, does not
output anything. $init is ignored. $headeradd is data to be added to the <head>
portion of the output headers. $form->{stylesheet}, $form->{title},
$form->{titlebar}, and $form->{pre} all affect the output of this function.
If the stylesheet indicated by $form->{stylesheet} exists, output a link tag to
reference it. If $form->{title} is false, the title text is the value of
$form->{titlebar}. If $form->{title} is true, the title text takes the form of
"$form->{title} - $form->{titlebar}". The value of $form->{pre} is output immediately
after the closing of <head>.
$form->open_status_div
Returns a div tag with an id of statusdiv.
If $form->{id} is set and $form->{approved} the class is set to "posted" and if id is
set but not approved, this is set to "saved." If neither applies, we set to "new."
$form->close_status_div
Simply returns a </div> tag. This is included for clarity of code.
$form->redirect([$msg]);
If $form->{callback} is set or $msg is not set, call the redirect function in
common.pl. If main::redirect returns, exit.
Otherwise, output $msg as an informational message with $form->info($msg).
$form->sort_columns(@columns);
Sorts the list @columns. If $form->{sort} is unset, do nothing. If the value of
$form->{sort} does not exist in @columns, returns the list formed by the value of
$form->{sort} followed by the values of @columns. If the value of $form->{sort} is in
@columns, return the list formed by @columns with the value of $form->{sort} moved to
the head of the list.
$form->sort_order($columns[, $ordinal]);
Returns a string that contains ordering details for the columns in SQL form. $columns
is a reference to a list of columns, $ordinal is a reference to a hash that maps
column names to ordinal positions. This function depends upon the values of
$form->{direction}, $form->{sort}, and $form->{oldsort}.
If $form->{direction} is false, it becomes 'ASC'. If $form->{direction} is true and
$form->{sort} and $form->{oldsort} are equal, reverse the order specified by
$form->{direction}. $form->{oldsort} is set to the same value as $form->{sort}
The actual sorting of $columns happens as in $form->sort_columns(@$columns).
If $ordinal is set, the positions given by it are substituted for the names of columns
returned.
$form->convert_date($date, $myconfig)
This takes a date in YYYY-MM-DD format and returns it in the format of the user.
$form->format_amount($myconfig, $amount, $places, $dash);
Returns $amount as formatted in the form specified by $form->{numberformat}. $places
is the number of decimal places to have in the output. $dash indicates how to
represent conditions surrounding values.
+-------+----------+---------+------+
| $dash | -1.00 | 1.00 | 0.00 |
+-------+----------+---------+------+
| - | (1.00) | 1.00 | - |
| DRCR | 1.00 DR | 1.00 CR | DRCR |
| 0 | -1.00 | 1.00 | 0.00 |
| x | -1.00 | 1.00 | x |
| undef | -1.00 | 1.00 | |
+-------+----------+---------+------+
Sample behaviour of the formatted output of various numbers for select $dash values.
$form->parse_amount($myconfig, $amount);
Return a Math::BigFloat containing the value of $amount where $amount is formatted as
$myconfig->{numberformat}. If $amount is '' or undefined, it is treated as zero.
DRCR and parenthesis notation is accepted in addition to negative sign notation.
Calls $form->error if the value is NaN.
$form->round_amount($amount, $places);
Rounds the provided $amount to $places decimal places.
$form->db_parse_numeric('sth' => $sth, ['arrayref' => $arrayref, 'hashref' => $hashref])
Converts numeric values in the result set $arrayref or $hashref to Math::BigFloat
using $sth to determine which fields are numeric.
$form->get_my_emp_num($myconfig);
Function to get the employee number of the user $form->{login}. $myconfig is only
used to create %myconfig. $form->{emp_num} is set to the retrieved value.
This function is currently (2007-08-02) only used by pos.conf.pl.
$form->format_string(@fields);
Escape the values of $form selected by @fields for the format specified by
$form->{format}.
$form->datetonum($myconfig, $date[, $picture]);
Converts $date from the format $myconfig->{dateformat} to the format 'yyyymmdd'. If
the year extracted is only two-digits, the year given is assumed to be in the range
2000-2099.
If $date does not contain any non-digits, datetonum does nothing.
$picture is ignored.
$form->add_date($myconfig, $date, $repeat, $unit);
Returns the date $repeat $units from $date in the input format. $date can either be
in $myconfig->{dateformat} or 'yyyymmdd' (four digit year required for this option).
The valid values for $unit are 'days', 'weeks', 'months', and 'years'.
This function is unreliable for $unit values other than 'days' or 'weeks' and can die
horribly.
$form->print_button($button, $name);
Outputs a submit button to STDOUT. $button is a hashref that contains data about
buttons, $name is the key for the element in $button to output. Each value in $button
is a reference to a hash of two elements, 'key' and 'value'.
$name is the value of the button that gets sent to the server when clicked,
$button->{$name}{key} is the accesskey, and $button->{$name}{value} is the label for
the button.
test_should_get_images
Returns true if images should get be retrieved for embedding in templates
$form->db_init($myconfig);
Connect to the database that $myconfig is set to use and initialise the base
parameters. The connection handle becomes $form->{dbh} and $form->{custom_db_fields}
is populated. The connection initiated has autocommit disabled.
$form->run_custom_queries($tablename, $query_type[, $linenum]);
Runs queries against custom fields for the specified $query_type against $tablename.
Valid values for $query_type are any casing of 'SELECT', 'INSERT', and 'UPDATE'.
$form->dbconnect($myconfig);
Returns an autocommit connection to the database specified in $myconfig.
$form->dbconnect_noauto($myconfig);
Returns a non-autocommit connection to the database specified in $myconfig.
$form->dbquote($var);
If $var is an empty string, return NULL, otherwise return $var as quoted by
$form->{dbh}->quote($var).
$form->update_balance($dbh, $table, $field, $where, $value);
WARNING: This is a dangerous private function. All apps calling it must be careful to
avoid SQL injection issues.
If $value is set, sets the value of $field in $table to the sum of the current stored
value and $value. In order to not annihilate the values in $table, $where must
contain a WHERE clause that limits the UPDATE to a single row.
$form->update_exchangerate($dbh, $curr, $transdate, $buy, $sell);
Updates the exchange rates $buy and $sell for the given $currency on $transdate. If
there is not yet an exchange rate for $currency on $transdate, an entry is inserted.
This returns without doing anything if $curr eq ''.
$dbh is not used, favouring $self->{dbh}.
$form->save_exchangerate($myconfig, $currency, $transdate, $rate, $fld);
Saves the exchange rate $rate for the given $currency on $transdate for the provided
purpose in $fld. $fld can be either 'buy' or 'sell'.
$myconfig is not used. $self->update_exchangerate is used for the majority of the
work.
$form->get_exchangerate($dbh, $curr, $transdate, $fld);
Returns the exchange rate in relation to the default currency for $currency on
$transdate for the purpose indicated by $fld. $fld can be either 'buy' or 'sell' to
get usable results.
$dbh is not used, favouring $self->{dbh}.
$form->check_exchangerate($myconfig, $currency, $transdate, $fld);
Returns some true value when an entry for $currency on $transdate is true for the
purpose indicated by $fld. $fld can be either 'buy' or 'sell' to get usable results.
Returns false if $transdate is not set.
$myconfig is not used.
$form->add_shipto($dbh, $id);
Inserts a new address into the table shipto if the value of any of the shipto address
components in $form differs to the regular attribute in $form. The inserted value of
trans_id is $id, the other fields correspond with the shipto address components of
$form.
$dbh is unused.
$form->get_employee($dbh);
Returns a list containing the name and id of the employee $form->{login}. Any portion
of $form->{login} including and past '@' are ignored.
$dbh is unused.
$form->get_name($myconfig, $table[, $transdate])
Sets $form->{name_list} to refer to a list of customers or vendors whose names or
numbers match the value found in $form->{$table} and returns the number of matches.
$table can be 'vendor', 'customer', or 'employee'; if the optional field $transdate is
provided, the result set is further limited to $table entries which were active on the
provided date as determined by the start and end dates. The elements of
$form->{name_list} are references returned rows in hashref form and are sorted by the
name field. The fields of the hash are those of the view $table and the table entity.
$myconfig is unused.
$form->all_vc($myconfig, $vc, $module, $dbh, $transdate, $job);
Populates the list referred to by $form->{all_${vc}} with hashes of either vendor or
customer id and name, ordered by the name. This will be vendor details unless $vc is
set to 'customer'. This list can be limited to only vendors or customers which are
usable on a given day by specifying $transdate. As a further restriction,
$form->{all_${vc}} will not be populated if the number of vendors or customers that
would be present in that list exceeds, or is equal to, $myconfig->{vclimit}.
In addition to the possible population of $form->{all_${vc}}, $form->{employee_id} is
looked up if not already set, the list $form->{all_language} is populated using the
language table and is sorted by the description, and $form->all_employees,
$form->all_departments, $form->all_projects, and $form->all_taxaccounts are all run.
$module and $dbh are unused.
$form->get_regular_metadata($myconfig, $vc, $module, $dbh, $transdate, $job)
This is API-compatible with all_vc. It is a handy wrapper function that calls the
following functions: all_employees all_departments all_projects all_taxaccounts
It is preferable to using all_vc where the latter does not work properly due to
variable collisions, etc.
$form->{employee_id} is looked up if not already set, the list $form->{all_language}
is populated using the language table and is sorted by the description, and
$form->all_employees, $form->all_departments, $form->all_projects, and
$form->all_taxaccounts are all run.
$module and $dbh are unused.
$form->all_accounts()
Sets $form->{accounts} to all accounts. Returns the list as well. Example: my
@account_list = $form->all_accounts();
$form->all_taxaccounts($myconfig, $dbh2[, $transdate]);
Get the tax rates and numbers for all the taxes in $form->{taxaccounts}. Does nothing
if $form->{taxaccounts} is false. Taxes are listed as a space separated list of
account numbers from the chart. The retrieved values are placed within
$form->{${accno}_rate} and $form->{${accno}_taxnumber}. If $transdate is set, then
only process taxes that were valid on $transdate.
$myconfig and $dbh2 are unused.
$form->all_employees($myconfig, $dbh2, $transdate, $sales);
Sets $form->{all_employee} to be a reference to an array referencing hashes of
employee information. The hashes are of the form {'id' => id, 'name' => name}. If
$transdate is set, the query is limited to employees who are active on that day. If
$sales is true, only employees with the sales flag set are added.
$dbh2 is unused.
$form->all_projects($myconfig, $dbh2[, $transdate, $job]);
Populates the list referred to as $form->{all_project} with hashes detailing all
projects. If $job is true, limit the projects to those whose ids are not also
present in parts with a project_id > 0. If $transdate is set, the projects are
limited to those valid on $transdate. If $form->{language_code} is set, include the
translation description in the project list and limit to translations with a matching
language_code. The result list, $form->{all_project}, is sorted by projectnumber.
$myconfig and $dbh2 are unused. $job appears to be part of attempted job- costing
support.
$form->all_departments($myconfig, $dbh2, $vc);
Set $form->{all_department} to be a reference to a list of hashrefs describing
departments of the form {'id' => id, 'description' => description}. If $vc is
'customer', further limit the results to those whose role is 'P' (Profit Center).
This procedure is internally followed by a call to $form->all_years($myconfig).
$dbh2 is not used.
$form->all_languages($myconfig);
Set $form->{all_language} to be a reference to a list of hashrefs describing languages
using the form {'code' => code, 'description' => description}.
$form->all_years($myconfig[, $dbh2]);
Populates the hash $form->{all_month} with a mapping between a two-digit month number
and the English month name. Populates the list $form->{all_years} with all years
which contain transactions.
$dbh2 is unused.
$form->create_links( { module => $module, myconfig => $myconfig, vc => $vc, billing =>
$billing [, job => $job ] });
Populates the hash referred to as $form->{${module}_links} details about accounts that
have $module in their link field. The hash is keyed upon link elements such as
'AP_amount' and 'AR_tax' and they refer to lists of hashes containing accno and
description for the appropriate accounts. If the key does not contain 'tax', the
account number is appended to the space separated list $form->{accounts}. $module is
typically 'AR' or 'AP' and is the base type of the accounts looked up.
If $form->{id} is not set, check $form->{"$form->{vc}_id"}. If neither is set, use
$form->lastname_used to populate the details. If $form->{id} is set, populate the
invnumber, transdate, ${vc}_id, datepaid, duedate, ordnumber, taxincluded, currency,
notes, intnotes, ${vc}, department_id, department, oldinvtotal, oldtotalpaid,
employee_id, employee, language_code, ponumber, reverse, printed, emailed, queued,
recurring, exchangerate, and acc_trans attributes of $form with details about the
transaction $form->{id}. All of these attributes, save for acc_trans, are scalar;
$form->{acc_trans} refers to a hash keyed by link elements whose values are lists of
references to hashes describing acc_trans table entries corresponding to the
transaction $form->{id}. The elements in the acc_trans entry hashes are accno,
description, source, amount, memo, transdate, cleared, project_id, projectnumber, and
exchangerate.
The closedto, separate_duties, revtrans, and currencies $form attributes are filled
with values from the defaults table, while $form->{current_date} is populated with the
current date. If $form->{id} is not set, then $form->{transdate} also takes on the
current date.
When $billing is provided and true, the email addresses are selected from the billing
contact classes, when available, falling back to the normal email classes when not.
After all this, it calls $form->all_vc to conclude.
$form->lastname_used($myconfig, $dbh2, $vc, $module);
Fills the name, currency, ${vc}_id, duedate, and possibly invoice_notes attributes of
$form with the last used values for the transaction type specified by both $vc and
$form->{type}. $vc can be either 'vendor' or 'customer' and if unspecified will take
on the value given in $form->{vc}, defaulting to 'vendor'. If $form->{type} matches
/_order/, the transaction type used is order, if it matches /_quotation/, quotations
are looked through. If $form->{type} does not match either of the above, then ar or
ap transactions are used.
$myconfig, $dbh2, and $module are unused.
$form->current_date($myconfig[, $thisdate, $days]);
If $thisdate is false, get the current date from the database.
If $thisdate is true, get the date $days days from $thisdate in the date format
specified by $myconfig->{dateformat} from the database.
$form->like($str);
Returns '%$str%'
$form->redo_rows($flds, $new, $count, $numrows);
$flds refers to a list of field names and $new refers to a list of row detail hashes
with the elements of $flds as keys as well as runningnumber for an order or another
multi-row item that normally expresses elements in the form
$form->{${fieldname}_${index}}.
For every $field in @{$flds} populates $form->{${field}_$i} with an appropriate value
from a $new detail hash where $i is an index between 1 and $count. The ordering of
the details is done in terms of the runningnumber element of the row detail hashes in
$new.
All $form attributes with names of the form ${field}_$i where the index $i is between
$count + 1 and $numrows is deleted.
$form->get_partsgroup($myconfig[, $p]);
Populates the list referred to as $form->{all_partsgroup}. $p refers to a hash that
describes which partsgroups to retrieve. $p->{searchitems} can be 'part', 'service',
'assembly', 'labor', or 'nolabor' and will limit the groups to those that contain the
item type described. $p->{searchitems} and $p->{all} conflict. If $p->{all} is set
and $p->{language_code} is not, all partsgroups are retrieved. If $p->{language_code}
is set, also include the translation description specified by $p->{language_code} for
the partsgroup.
The results in $form->{all_partsgroup} are normally sorted by partsgroup name. If a
language_code is specified, the results are then sorted by the translated description.
$myconfig is unused.
$form->update_status($myconfig);
DELETEs all status rows which have a formname of $form->{formname} and a trans_id of
$form->{id}. INSERTs a new row into status where trans_id is $form->{id}, formname is
$form->{formname}, printed and emailed are true if their respective $form attributes
match /$form->{formname}/, and spoolfile is the file extracted from the string
$form->{queued} or NULL if there is no entry for $form->{formname}.
$myconfig is unused.
$form->save_status();
Clears out any old status entries for $form->{id} and saves new status entries.
Queued form names are extracted from $form->{queued}. Printed and emailed form names
are extracted from $form->{printed} and $form->{emailed}. The queued, printed, and
emailed fields are space separated lists.
$form->get_recurring();
Sets $form->{recurring} to contain info about the recurrence schedule for the action
$form->{id}. $form->{recurring} is of the same form used by
$form->save_recurring($dbh2, $myconfig).
reference,startdate,repeat,unit,howmany,payment,print,email,message
text date int text int int text text text
$form->save_recurring($dbh2, $myconfig);
Saves or deletes recurring transaction scheduling. $form->{id} is used to determine
the id used in the various recurring tables. A recurring transaction schedule is
deleted by having $form->{recurring} be false. For adding or updating a schedule,
$form->{recurring} is a comma separated field with partial subfield quoting of the
form:
reference,startdate,repeat,unit,howmany,payment,print,email,message
text date int text int int text text text
reference
A URI-encoded reference string for the recurrence set.
startdate
The index date for the recurrence.
repeat
The unitless repetition frequency.
unit
The interval unit used. Can be 'days', 'weeks', 'months', or 'years',
capitalisation and pluralisation ignored.
howmany
The number of recurrences for the transaction.
payment
Flag to indicate if a payment is included in the transaction.
print
A colon separated list of formname:format:printer triplets.
email
A colon separated list of formname:format pairs.
message
A URI-encoded message for the emails to be sent.
Values for the nextdate and enddate columns of the recurring table are calculated
using startdate, repeat, unit, howmany, and the current database date. All other
fields of the recurring, recurringemail, and recurringprint are obtained directly from
$form->{recurring}.
WARNING: This function does not check the validity of most subfields of
$form->{recurring}.
$dbh2 is not used.
$form->save_intnotes($myconfig, $vc);
Sets the intnotes field of the entry in the table $vc that has the id $form->{id} to
the value of $form->{intnotes}.
Does nothing if $form->{id} is not set.
$form->update_defaults($myconfig, $fld[, $dbh [, $nocommit]);
Updates the defaults entry for the setting $fld following rules specified by the
existing value and returns the processed value that results. If $form is false, such
as the case when invoked as "Form::update_defaults('',...)", $dbh is used as the
handle. When $form is set, it uses $form->{dbh}, initialising the connection if it
does not yet exist. The entry $fld must exist prior to executing this function and
this update function does not handle the general case of updating the defaults table.
Note that nocommit prevents the db from committing in this function.
NOTE: rules handling is currently broken.
Rules followed by this function's processing:
• If digits are found in the field, increment the left-most set. This change,
unlike the others is reflected in the UPDATE.
• Replace <?lsmb date ?> with the date specified in $form->{transdate} formatted as
$myconfig->{dateformat}.
• Replace <?lsmb curr ?> with the value of $form->{currency}
$form->db_prepare_vars(var1, var2, ..., varn)
Undefines $form->{varm}, 1 <= m <= n, iff $form-<{varm is both false and not "0".
$form->split_date($dateformat[, $date]);
Returns ($rv, $yy, $mm, $dd) for the provided $date, or the current date if no date is
provided. $rv is a seperator-free merging of the fields $yy, $mm, and $dd in the
ordering supplied by $dateformat. If the supplied $date does not contain non-digit
characters, $rv is $date and the other return values are undefined.
$yy is two digits.
$form->format_date($date);
Returns $date converted from 'yyyy-mm-dd' format to the format specified by
$form->{db_dateformat}. If the supplied date does not match /^\d{4}\D/, return the
supplied date.
This function takes a four digit year and returns the date with a four digit year.
$form->from_to($yyyy, $mm[, $interval]);
Returns the date $yyyy-$mm-01 and the the last day of the month interval - 1 months
from then in the form ($form->format_date(fromdate), $form->format_date(later)). If
$interval is false but defined, the later date is the current date.
This function dies horribly when $mm + $interval > 24
$form->audittrail($dbh, $myconfig, $audittrail);
Audit trail has been replaced by triggers which work on a very similar manner.