ePages 6.11.0 - DE_EPAGES/XML/API/BaseExportDriver.pm

Package DE_EPAGES::XML::API::BaseExportDriver

This is the base class for XML export drivers. Derived packages must override at least the method "drive".

Example
my $Driver = MyExportDriver->new;
$Driver->exportXML( 'output.xml', { encoding => 'utf-8' } );
package MyExportDriver;
use base qw( DE_EPAGES::XML::API::BaseExportDriver );

use strict;

# adds all Example elements
sub AllExamples {
    my $self = shift;

    my @Examples = qw( Example1 Example2 Example3 );
    $self->addElement( 'Example', { 'ExampleID' => $_ } ) foreach @Examples;
}

# returns the attributes of an 'Example' element
sub Example {
    my $self = shift;

    # access a parameter of the addElement() call
    my $ExampleID = $self->topID('ExampleID');

    # return all attribute values
    return {
        ExampleID => $ExampleID,
        Attribute1 => 'Value 1'
    };
}

# returns the attributes for the 'epages' tag
sub epages {
    return {};
}

# this method is called to start the export
sub drive {
    my $self = shift;

    # call the method 'AllExamples' for each 'epages' element
    $self->addHook( 'epages' => 'AllExamples' );

    # start the export by adding the root element
    $self->addElement( 'epages' );
}

Functions

addElement
addHook
consumer
drive
encodeTo
exportXML
items
new
parse
popID
pushID
topID
writeChildElements
writeDocument
writeElement
writer

addElement

Adds an XML element to the SAX2 stream. If the $TagName contains a hyphen (e.g. price-list) then the hyphen is substituted by an underscore (e.g. price_list) and saved as new $attribMethod. Calls $self->$attribMethod to retrieve the attributes of the element. Executes registered hook functions to create sub elements. The function addHook is used to register such hook functions. If the parameter $Text is defined, such text is between start tag and end tag after all sub tags (if any).

Syntax
$self->addElement( $TagName );
$self->addElement( $TagName, $hParams );
$self->addElement( $TagName, $hParams, $Text );
Example
$self->addElement( 'Company', { CompanyID => $CompanyID } );
Input
$TagName (string)
element name
$hParams (hash ref)
(optional) parameters for this element and its sub elements.
These parameters are accessible by sub element handlers using
$self->topID.
$Text (hash ref)
(optional) character data between start and end tag

addHook

Adds a hook function to create sub elements within a given parent element.

Syntax
addHook( $TagName, $MethodName );
Example
$driver->addHook( 'Company' => 'CostCentersByCompanyID' );
Input
$TagName (string)
parent tag name
$MethodName (string)
method name

consumer

Returns the instance of XML::SAX::Writer from the filter chain. Throws an error if no instance of XML::SAX::Writer exists.

Syntax
$Consumer = $Driver->consumer;
Return
$Writer (object)
XML::SAX::Writer::ConsumerInterface object

drive

Starts export of items.

Syntax
$self->drive();

encodeTo

Returns the target encoding (was set in exportXML).

Syntax
$Encoding = $Driver->encodeTo;
Return
$Encoding (string)
target encoding (utf8,iso-8859-1,...)

exportXML

Writes an xml file with the given encoding.

Syntax
$Driver->exportXML($FileName);
$Driver->exportXML($FileName, $hFormat);
$Driver->exportXML($FileName, $hFormat, $ahData);
Example
$Driver->exportXML( 'data.xml', { encoding => 'utf8' } );
Input
$FileName (string or array ref)
output file/array
$hFormat (ref.hash)
(optional) format info
  • encoding - target encoding (utf8,iso-8859-1,...) - string
$ahData (ref.array)
(optional) data | list of items to be exported. This value is
retured by items.

items

Returns the items to export.

Syntax
$ahData = $self->items();
Return
$ahData (ref.array)
list of items to be exported, see exportXML

new

Creates a SAX2 driver object.

Syntax
$Driver = $Package->new( Handler => $Handler );
Example
my $Driver = DerivedExportDriver->new( Handler => $Handler );
Input
$Handler (object)
SAX handler or filter
Return
$Driver (object)
SAX driver

parse

Starts the document, writes the declaration, calls drive und closes the document.

Syntax
$self->parse();

popID

Removes a parameter from the parameter stack and returns its value.

Syntax
$Value = $self->popID( $Key );
Example
$CompanyID = $self->popID( 'CompanyID' );
Input
$Key (string)
parameter name
Return
(parameter value)
$Value

pushID

Adds a parameter to the parameter stack. Any previous parameter with the same name will be hidden until $self->popID( $Key ) is called. Use $self->topID( $Key ) to get the parameter value. Use $self->popID( $Key ) to remove the parameter from the stack.

Syntax
$self->pushID( $Key, $Value );
Example
$self->pushID( 'CompanyID', $CompanyID );
Input
$Key (string)
parameter name
$Value
parameter value

topID

Returns the current value of a parameter.

Syntax
$Value = $self->topID( $Key );
Example
$CompanyID = $self->topID( 'CompanyID' );
Input
$Key (string)
parameter name
Return
(parameter value)
$Value

writeChildElements

Executes registered hook functions to create sub elements. The function addHook is used to register such hook functions. Overrride this method if you want to create sub elements without hook functions.

Syntax
$self->writeChildElements( $TagName );
$self->writeChildElements( $TagName, $hParams );
Input
$TagName (string)
element name
$hParams (hash ref)
(optional) parameters that are passed through from
writeElement

writeDocument

Starts the document, writes the declaration, calls $Sub->() und closes the document.

Syntax
$self->writeDocument( $Sub );
Input
$Sub (code ref)
code that creates the document content

writeElement

Adds an XML element to the SAX2 stream. First writes the start tag with attributes and the end tag. Between start and end tag calls $Sub->() if the 3rd parameter is a code ref, otherwise calls writeChildElements to add the child elements.

Syntax
$self->writeElement( $TagName );
$self->writeElement( $TagName, $hAttributes );
$self->writeElement( $TagName, $hAttributes, $Text );
$self->writeElement( $TagName, $hAttributes, $Text, $hParams );
$self->writeElement( $TagName, $hAttributes, $Sub );
Example
$self->writeElement( 'Company', { Name => 'ePages' } );
$self->writeElement( 'Company', { Name => 'ePages' }, sub {
    $self->writeElement( 'Office', { Country => 'Germany', City => 'Jena' } );
    $self->writeElement( 'Office', { Country => 'Germany', City => 'Hambug' } );
} );
Input
$TagName (string)
element name
$hAttributes
(optional) parameters for this element and its sub elements.
$Text (hash ref)
(optional) character data between start and end tag
$hParams (hash ref)
(optional) parameters that are passed through to
writeChildElements
$Sub (code ref)
(optional) code that is executed between start and end tag

writer

Returns the instance of XML::SAX::Writer from the filter chain. Throws an error if no instance of XML::SAX::Writer exists.

Syntax
$Writer = $Driver->writer;
Return
$Writer (object)
XML::SAX::Writer object