if (defined $opts->{validate} and $opts->{validate}) {
                my $dtd = $self->get_dtd;
                my $ret;
                eval {
                        my $parsed_dtd = XML::LibXML::Dtd->parse_string($dtd);
                        ### print STDERR $cloned->toString;
                        my $parser = $self->rayapp->xml_parser;
                        $parser->keep_blanks(0);
                        my $parsed = $parser->parse_string($cloned->toString);
                        $parser->keep_blanks(1);
                        $ret = $parsed->validate($parsed_dtd);
                };
                if ($@) {
                        $self->{errstr} = $@;
                } elsif (not $ret) {
                        $self->{errstr} = "The result is not valid, but no reason given.\n";
                }

        }

NAME

RayApp::DSD

DESCRIPTION

Even if this module implements a couple of methods, it will probably not be used directly by the application programmer. Therefore, we will just focus on the Data Structure Description (DSD) syntax in this man page.

The data structure description file is a XML file. Its elements either form the skeleton of the output XML and are copied to the output, or specify placeholders for application data, or input parameters that the application accepts.

Parameters

Parameters are denoted by the _param elements. They take the following attributes:

name

Name of the parameter. For example,

        <_param name="id"/>

specifies parameter id.

prefix

Prefix of the parameter. All parameters with this prefix will be allowed. Element

        <_param prefix="search-"/>

allows both search-23 and search-xx parameters.

multiple

By default, only one parameter of each name is allowed. However, specifying multiple="yes" makes it possible to call the application with multiple parameters of the same name:

        <_param name="id" multiple="yes"/>
        application.cgi?id=34;id=45

type

A simple type checking is possible. Available types are int, integer for integer values, num and number for numerical values, struct for more complex data structures, and string for generic string values. The value string is the default if the <_param> element does not have any children, otherwise the struct is the default.

Note that the type (int, num) on parameters should only be used for input data that will never be directly entered by the user, either for machine-to-machine communication, or for values in HTML forms that come from menus or checkboxes. If you need to check that the user specified their age as a number in a textfield, use the type string and application code to retrieve the correct data or return with request for more correct input.

Typerefs

Any child element with an attribute typeref is replaced by document fragment specified by this attribute. Absolute or relative URL is allowed, with possibly fragment information after a # (hash) character. For example:

        <root>
                <invoice typeref="invoice.dsd#inv"/>
                <adress typeref="address.xml"/>
        </root>

Data placeholders

Any element with no children, element with attributes type, multiple or with name _data are data placeholders that will have the application data binded to them. The allowed attributes of placeholders are:

type

Type of the placeholder. Except the scalar types which are the same as for input parameters, hash or struct values can be used to denote nested structure.

mandatory

By default, no data needs to be returned by the application for the placeholder. When set to yes, the value will be required.

id

An element can be assigned a unique identification which can be then referenced by typeref from other parts of the same DSD or from remote DSD's.

multiple

When this attribute is specified, the value is expected to be an aggregate and either the currect DSD element or its child is repeated for each value.

list

An array is expected as the value. The placeholder element will be repeated.

listelement

An array is expected, the child of the placeholder will be repeated for each of the array's element.

hash

An associative array is expected and placeholder element will be repeated for all values of the array. The key of individual values will be in an attribute id or in an attribute named in DSD with attribute idattr.

hashelement

The same as hash, except that the child of the placeholder will be repeated.

idattr

Specifies the name of attribute which will hold keys of individual values for multiple values hash and hashelement, the default is id.

hashorder

Order of elements for values binded using multiple values hash or hashelement. Possible values are num, string, and (the default) natural.

cdata

When set to yes, the scalar content of this element will be output as a CDATA section.

Conditions

The non-placeholder elements can have one of the if, ifdef, ifnot or ifnotdef attributes that specify a top-level value (from the data hash) that will be checked for presence or its value. If the condition is not matched, this element with all its children will be removed from the output stream.

Attributes

By default, only the special DSD attributes are allowed. However, with an attribute attrs a list of space separated attribute names can be specified. These will be preserved on output.

With attribute xattrs, a rename of attributes is possible. The value is space separated list of space separated pairs of attribute names.

Application name

The root element of the DSD can hold an application attribute with a URL (file name) of the application which should provide the data for the DSD.

SEE ALSO

RayApp(3)

AUTHOR

Copyright (c) Jan Pazdziora 2001--2006

VERSION

This documentation is believed to describe accurately RayApp version 2.004.