The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Builder-0.06
River stage zero No dependents
1 ++
/ Builder::XML

NAME

Builder::XML - Building block for XML

VERSION

Version 0.06

SYNOPSIS

Please look at Builder docs. This currently contains the necessary synopsis & description for Builder::XML. At some point in future it will be moved here and Builder docs will be replaced with something more generic.

DESCRIPTION

See above.

So how does it work? (in more detail!)

Here are Builder::XML parameter contexts....

no parameters => produces a closed tag

    $xm->br;
    
    # => <br />

first parameter is a hashref => attributes

    $xm->span( { id => 'mydiv', class => 'thisClass' }, 'some content' );
    
    # => <span class="thisClass" id="mydiv">some content</span>

parameter(s) are a anon sub or code ref --> callback

    $xm->ul( { class => 'list' }, sub {
       for my $numb qw/one two three/ {
           $xm->li( $numb );
       }
    });

    # => <ul class="list"><li>one</li><li>two</li><li>three</li></ul>

parameter(s) are content => element text

    $xm->p( 'one', 'two', 'and three' );
    
    # => <p>one two and three</p>

parameter(s) are Builder blocks or content => nesting

    $xm->p( 'one', $xm->span( 'two' ), 'and three' );
    
    # => <p>one <span>two</span> and three</p>
    
    # NB. THIS DOESN'T WORK YET... unless first param is an object
    # Workaround - use __say__ method around text like so...
    #
    #      $xm->p( $xm->__say__('one'), $xm->span( 'two' ), 'and three' );
    #
    # This needs "fixing" for HTML usage

parameter(s) are Builder blocks within builder blocks => nesting ad-infinitum

    $xm->div(
        $xm->div(
            xm->span( 'hi there'),
        ),
    );
    
    # => <div><div><span>hi there</span></div></div>

Gotchas?

TODO: XML entities not implemented

TODO: invalid method calls... $xm->flip-flop, $xm->DESTROY, $xm->AUTOLOAD

TODO: Fix / workaround for attribute ordering

EXPORT

None.

METHODS

All methods are prefix/postfixed with __ so that ambigious method calls wont clash and can be turned successfully into XML elements.

Below is a complete list of defined methods in Builder::XML. NB. Most of these are private methods and only listing here for reference.

__new__

Private.

This is the contructor called by the Builder object when creating a block...

    $xm = $builder->block( 'Builder::XML' );

All arguments are passed from Builder->block method straight to Builder::XML->__new__

__render__

Will immediately render the building block. Can be useful in some cases...

    # provide example here of it working
    
    # and then provide example of what can go wrong!

...but recommend $builder->render for best practise.

__element__

Private

__cdata__

Wraps content in <![CDATA[ ]]> element. Useful for quick ditties like....

    $xm->span( $xm->__cdata__( 'yada yada' ) );
    
    # => <span><!CDATA[yada yada]]></span>

But for best practise you probably still find building a block more useful in the long run...

    my $xm = $builder->block( 'Builder::XML', { cdata => 1 } );
    
    $xm->span( 'yada yada' );

__cdatax__

PRIVATE - used with __cdata__

__say__

Really a Private method but as mentioned in Gotchas it can be useful for working around some implementation issues.

__push__

Private

__inc__

Private

__dec__

Private

__level__

Private

__tab__

Private

__start_tab__

Private

__end_tab__

Private

__open_newline__

Private

__close_newline__

Private

AUTOLOAD

Used in method to XML element resolution.

Therefore at present AUTOLOAD cannot be used as a XML element.

DESTROY

Standard POOP!

Therefore at present DESTROY cannot be used as a XML element.

AUTHOR

Barry Walsh <draegtun at cpan.org>

BUGS

Please report any bugs or feature requests to bug-builder at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Builder. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Builder::XML

You can also look for information at: Builder

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008-2013 Barry Walsh (Draegtun Systems Ltd | http://www.draegtun.com), all rights reserved.

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