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