NAME

SQLField - Misc fields for tables and forms


SYNOPSIS

  use Site::SQLField;


DESCRIPTION

When creating fields in forms or tables, you have several options and types of fields. Each field has some common options like name, and custom options. They also support defaults for forms and automatic resolution of foreign keys from other tables.


Common Options

All fields have these options:


name

The name of the field, to reference it within the templates or getnamedfield() function. If blank then boundto takes precedence.


boundto

The SQL field that this field is bound to. If blank, then it is a non bound field. (perhaps an href or something)


type

Field type. Needs to be set at creation time. See Field Types later.


enabled

If true then it can be edited browser side, if false then it will not be a field it will be just text in the browser.


locked

If locked, it looks like it can be edited but does not actually become part of the update query.


label

The field label. If not set, it tries name then boundto.


visible

If set to '0' then the field and label will not be displayed but still set.


value

If the field is not bound, this is how you can get a value in it.


default

Default value for add forms.


autoescape

If true then entities will be encoded. Set to false to allow HTML to be displayed in tables and stuff.


href

Special tag for tables, if set then it will be placed in an A HREF= tag and wrapped around the default value for the field. Names in {} will be converted to the values for this row. Useful for making edit links or more info links like this:

 $f -> default( 'edit' );
 $f -> href( 'edit_record.pl?recordid={recordid}' );

For each row this would become:

 <A HREF="edit_record.pl?recordid=1">edit</A>

Or whatever the value of recordid was for this row.


htmlname

Returns the name of the field in the HTML form. Can be used to intercept values and change them before handling updates.


remove

Remove from it's container.


disabled

Shorthand for enable=0 and locked=1.


Field Types and Special Attributes

There are different field types for different types of data, that have special behaviour and custom attributes.


text

This is the default field type, and is just a plain text box. It has a 'size' attribute that translates directly in to the size for the HTML.


checkbox

For boolean fields, just a simple checkbox.


area

A text area. Has width/height settings and a wrap setting which turns on or off the ``WRAP=VIRTUAL'' setting in the text area.


dropbox

This is used for foreign key values mostly, or even if you want just canned responses. The dropbox has a 'rowsourcetype' attribute, which if set to 'list' will use the array reference in 'rowsourcevalues', but if set to 'query' will grab it's data from another query, 'rowsourcequery'. In the query, the first row should be the ID or value that is put in the field, and the rest will simply be join()'ed together with a space.

For example, say you have a table customer with primary key customerid and you use it in an order table. You might have something like this:

 $f = Site::SQLForm -> new( dbh => $dbh );
 $f -> table( 'orders' );
 $f -> addfield( type => 'dropbox',
                boundto => 'customerid',
                rowsourcetype => 'query',
                rowsourcequery => 'select customerid, name from customers',
                label => 'Customer' );

This would make a dropbox that uses the customerid value, but presented a drop box with all the customer names in it. Any SQL query is valid. On the other hand, if you wanted to just use a canned list:

 $f -> addfield( type => 'dropbox',
                boundto => 'shipvia',
                rowsourcevalues => [ {
                                        key => 'ups',
                                        value => 'UPS Shipping'
                                }, {
                                        key => 'snailmail',
                                        value => 'Post Office'
                                }, {
                                        key => 'truck-o',
                                        value => 'Freight via Truck'
                                } ] );

This makes a drop box with the 'value' parts visible, but uses the key parts in the database. For defaults, it will automatically find the right value and set it to SELECTED.


optiongroup

Same as dropbox, but lists items in an option group instead.


AUTHOR

Copyright (c) 2001 Steve Slaven <bpk@hoopajoo.net> All rights reserved.

This program is free software and is provided ``as is'' without express or implied warranty. You can redistribute it and/or modify it under the same terms as Perl itself.


SEE ALSO

perl(1).