NAME

Net::Jabber::X::Form::Field - Jabber X Form Field Module

SYNOPSIS

Net::Jabber::X::Form::Field is a companion to the 
Net::Jabber::X::Form module.  It provides the user a simple 
interface to set and retrieve all parts of a Jabber Form Field.

DESCRIPTION

  To initialize the Field with a Jabber <x/> and then access the </x>
  you must pass it the XML::Parser Tree array from the 
  Net::Jabber::Client module.  In the callback function for the object
  type foo:

    use Net::Jabber;

    sub foo {
      my $foo = new Net::Jabber::Foo(@_);

      my @xTags = $foo->GetX("jabber:x:form");

      my $xTag;
      foreach $xTag (@xTags) {
        my @fields = $xTag->GetFields();
	my $field;
	foreach $field (@fields) {
	  $field->GetXXXX();
	  .
	  .
	  .
	}
      }
      .
      .
      .
    }

  You now have access to all of the retrieval functions available below.

  To create a new X Form Field to send to another user:

    use Net::Jabber;

    $Client = new Net::Jabber::Client();
    ...

    $foo = new Net::Jabber::Foo();
    $form = $foo->NewX("jabber:x:form");
    $foo = $form->AddField();
    ...

    $client->Send($foo);

  Using $field you can call the creation functions below to populate the 
  tag before sending it.

  For more information about the array format being passed to the CallBack
  please read the Net::Jabber::Client documentation.

Retrieval functions

$type    = $field->GetType();
$var     = $field->GetVar();
$label   = $field->GetLabel();
$value   = $field->GetValue();
$order   = $field->GetOrder();

@options = $field->GetOptions();

@field   = $field->GetTree();
$str     = $field->GetXML();

Creation functions

    $field->SetField(type=>"entry",
		     var=>"icqnum",
		     label=>"ICQ #",
		     order=>1);
    $field->SetType('pulldown');
    $field->SetVar('sex');
    $field->SetLabel('Sex');
    $field->SetOrder('2');
    $field->AddOption(value=>"m",
		      label=>"Male");
    $field->AddOption(value=>"f",
		      label=>"Female");
    $field->AddOption(value=>"u",
		      label=>"Unknown");

Test functions

$test = $field->DefinedType();
$test = $field->DefinedVar();
$test = $field->DefinedLabel();
$test = $field->DefinedOrder();

METHODS

Retrieval functions

GetType() - returns a string with type of field this is.

GetVar() - returns a string with variable name that the field sets.
           This is meant to be used as an index to a hash, but mainly
           so that when returned to the server the thing parsing it
           can quickly see which value goes with what variable.

GetLabel() - returns a string with label that should be displayed in
             front of the widget for this field.

GetValue() - returns a string with the value that this is field is set
             to.  If set then this should be the default value for the
             field in the widget, otherwise it is the value that the
             program returned.

GetOrder() - returns an integer with the order that this field should
             be displayed in on the form.  So a field with order=1
             should be displayed, or prompted, before the field with
             order=2.

GetXML() - returns the XML string that represents the <field/>.

GetTree() - returns an array that contains the <field/> tag
            in XML::Parser Tree format.

Creation functions

SetField(type=>string,   - set multiple fields in the <field/>
         var=>string,      at one time.  This is a cumulative
         label=>string,    and overwriting action.  If you
         value=>string,    set the "var" twice, the second
         order=>integer)   setting is what is used.  If you set
                           the tpe, and then set the
                           label then both will be in the
                           <field/> tag.  For valid settings
                           read the specific Set functions below.

SetType(string) - sets the type of field that this <field/> is.

SetVar(string) - sets the var name for the <field/>.

SetLabel(string) - sets the label that should be shown next to the
                   widget in the form.

SetValue(string) - sets the value of the field.

SetOrder(integer) - sets the order to show the field in.

Test functions

DefinedType() - returns 1 if the type attribute is set in the <field/>,
                0 otherwise.

DefinedVar() - returns 1 if the var attribute is set in the <field/>,
               0 otherwise.

DefinedLabel() - returns 1 if the label attribute is set in the <field/>,
                 0 otherwise.

DefinedOrder() - returns 1 if the order attribute is set in the <field/>,
                 0 otherwise.

AUTHOR

By Ryan Eatmon in February of 2001 for http://jabber.org..

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.