The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

DBIx::XMLServer::Field - base class for field types in DBIx::XMLServer

SYNOPSIS

  package MyField;
  our @ISA = ('DBIx::XMLServer::Field');

  sub init { };
  sub where { };
  sub select { };
  sub value { };
  sub join { };

DESCRIPTION

This package is the base class for field type classes in DBIx::XMLServer. Both built-in and user-supplied field types are derived from this class. This documentation describes the methods of the class and how they should be overridden in derived classes. All methods have sensible base implementations; many classes will only need to override one or two methods.

All methods of this class are executed inside evals; any errors thrown will be reported back to the user.

For examples on how to derive your own field types, see the built-in type packages.

init method

  $field->init();

The init method is called at the end of the class constructor. Any initialisation needed by the class should be put here. The default is to do nothing.

where method

  $sql_expression = $field->where($condition);

The where method takes a condition such as "=Fred*" or ">21" and converts it to an SQL expression such as "NAME LIKE FRED%" or "AGE > 21". The argument is the remainder of a fragment of the HTTP query, after the initial XPath expression selecting the field has been removed. This method will often want to call the select method to get the SQL name of the field. The default method returns '1'.

select method

  $sql_expression = $field->select();

The select method returns the SQL expression(s) for the field. The default is to return the value of the expr attribute of the field's <sql:field> element. This method may return a list, if the value of the field depends on more than one SQL expression.

value method

  $xml_node = $field->value(\@results);

The value method takes the result of the SQL query and converts it to a fragment of XML. The resulting fragment of XML replaces the <sql:field> element in the output record. The return value of this method should be: an XML::LibXML::Element; a XML::LibXML::DocumentFragment; a scalar value, which will be put into a new XML text node; or undef, indicating a null value. Should the return value be undef, the outcome in the result record is determined by the field's null attribute as described in DBIx::XMLServer. If the field is an attribute field, only scalar or undef return values are allowed.

The argument is an array reference whose elements are the values of the columns in the result of the SQL SELECT statement. This method should shift its columns out of the array; normally only one column will be used, but if the select method returns more than one expression then this method should remove the same number of values from the array.

The default behaviour is to shift one element from the array and return it as a scalar.

join method

  $table = $field->join()

This method returns the names of any tables which should be joined to the main table in order for this field to exist. The default is to return the value of the join attribute of the <sql:field> element.

OBJECT DATA

There are two items of object data which may be useful to classes:

Node reference

The expression $self->{node} gives the XML::LibXML::Element object representing the <sql:field> element which defined this field.

Owner reference

The expression $self->{XMLServer} gives the DBIx::XMLServer element associated to the field. The main use of this is probably to access the database handle stored in $self->{XMLServer}->{dbh}, for purposes such as string escaping; and to get at the XML document object at $self->{XMLServer}->{doc} for creating new nodes. Those wishing to access other data should look at the source to see what's there.

SEE ALSO

DBIx::XMLServer, DBIx::XMLServer::TextField, DBIx::XMLServer::NumberField, DBIx::XMLServer::DateField, DBIx::XMLServer::DateTimeField

AUTHOR

Martin Bright <martin@boojum.org.uk>

COPYRIGHT AND LICENCE

Copyright (C) 2003-4 Martin Bright

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