Barry Walsh > Builder-0.06 > Builder::XML

Download:
Builder-0.06.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.06   Source  

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.

syntax highlighting: