package WebGUI::Form::Control; =head1 LEGAL ------------------------------------------------------------------- WebGUI is Copyright 2001-2007 Plain Black Corporation. ------------------------------------------------------------------- Please read the legal notices (docs/legal.txt) and the license (docs/license.txt) that came with this distribution before using this software. ------------------------------------------------------------------- http://www.plainblack.com info@plainblack.com ------------------------------------------------------------------- =cut use strict; use WebGUI::Operation::Shared; use WebGUI::International; =head1 NAME Package WebGUI::Form::Control =head1 DESCRIPTION Base class for all form field objects. Never use this class directly. =head1 SYNOPSIS use base 'WebGUI::Form::Control'; ...your methods here... Subclasses will look like this: use WebGUI::Form::subclass; my $obj = WebGUI::Form::subclass->new($session,%params); my $html = $obj->toHtml; my $html = $obj->toHtmlAsHidden; my $tableRows = $obj->toHtmlWithWrapper; =head1 METHODS The following methods are available via this package. =cut #------------------------------------------------------------------- =head2 privateName ( ) Creates a safe, private name for additional use in multi-part forms like File and Image. =cut sub privateName { my ($self, $action) = @_; return join '_', '_', $self->get('name'), $action; } #------------------------------------------------------------------- =head2 definition ( session, [ additionalTerms ] ) Defines the schema or parameters for a form field. =head3 session The session object, usually for internationalization. =head3 additionalTerms An array reference containing a hash of hashes of parameter names and their definitions. Example: [{ myParam=>{ defaultValue=>undef } }] By default all form fields have the following parameters: =head4 name The field name. =head4 value The starting value for the field. =head4 defaultValue If no starting value is specified, this will be used instead. =head4 _defaulted This flag indicates that the defaultValue was used. It is used by Form types that support an initial blank field, instead of using a default, like WebGUI::Form::Date.pm =head4 extras Add extra attributes to the form tag like onmouseover='doSomething()' =head4 formName The key to look up for the form name. =head4 label A text label that will be displayed if toHtmlWithWrapper() is called. =head4 id A unique identifier that can be used to identify this field with javascripts and cascading style sheets. Is autogenerated if not specified. The autogenerated version is the value of the name parameter concatinated with the string "_formId". So for a field called "title" it would be "title_formId". =head4 idPrefix If specified, this will be prepended to the id (whether autogenerated or not) to prevent overlap of two similar forms on the same page. =head4 uiLevel The UI Level that the user must meet or exceed if this field should be displayed with toHtmlWithWrapper() is called. =head4 uiLevelOverride An identifier that will be grabbed from the config file to determine the uiLevel. If the uiLevelOverride is "Article" and the name is "title" then the entry in the config file would look like: Article_uiLevel = title => 5 =head4 subtext A text string that will be appended after the field when toHtmlWithWrapper() is called. =head4 labelClass A stylesheet class assigned to the label with toHtmlWithWrapper() is called. Defaults to "formDescription". =head4 fieldClass A stylesheet class assigned to wrapper the field when toHtmlWithWrapper() is called. Defaults to "tableData". =head4 rowClass A stylesheet class assigned to each label/field pair. =head4 hoverHelp A text string that will pop up when the user hovers over the label when toHtmlWithWrapper() is called. This string should indicate how to use the field and is usually tied into the help system. =head4 profileEnabled Flag that tells the User Profile system that this is a valid form element in a User Profile =head4 dbDataType The SQL data type for this form element. Fields created using this form control will create a column with this data type. If undef, will not create a database column. Defaults to "VARCHAR(255)". =cut sub definition { my $class = shift; my $session = shift; my $definition = shift || []; push(@{$definition}, { formName=>{ defaultValue=>'A name for this form was not supplied' }, name=>{ defaultValue=>undef }, value=>{ defaultValue=>undef }, extras=>{ defaultValue=>undef }, defaultValue=>{ defaultValue=>undef }, _defaulted=>{ defaultValue=>0 }, label=>{ defaultValue=>undef }, uiLevel=>{ defaultValue=>1 }, uiLevelOverride=>{ defaultValue=>undef }, labelClass=>{ defaultValue=>"formDescription" }, fieldClass=>{ defaultValue=>"tableData" }, rowClass=>{ defaultValue=>undef }, hoverHelp=>{ defaultValue=>undef }, subtext=>{ defaultValue=>undef }, id=>{ defaultValue=>undef }, idPrefix=>{ defaultValue=>undef }, profileEnabled=>{ defaultValue=>0 }, dbDataType => { defaultValue => "VARCHAR(255)", }, }); return $definition; } #------------------------------------------------------------------- =head2 displayForm ( ) This utility method is used to format values for the Profile system but can be used in other areas as well. Most form elements will just return toHtml. =cut sub displayForm { my ($self) = @_; $self->toHtml; } #------------------------------------------------------------------- =head2 displayFormWithWrapper ( ) This utility method is used to format values for the Profile system but can be used in other areas as well. Most form elements will just return displayForm. =cut sub displayFormWithWrapper { my $self = shift; if ($self->passUiLevelCheck) { my ($fieldClass, $rowClass, $labelClass, $hoverHelp, $subtext) = $self->prepareWrapper; $hoverHelp &&= '