HTML::ElementSuper(3pm)

1HTML::ElementSuper(3) User Contributed Perl DocumentationHTML::ElementSuper(3)
2
3
4

NAME

6       HTML::ElementSuper - Perl extension for HTML::Element(3)
7

SYNOPSIS

9         use HTML::ElementSuper;
10
11         ### Positional extension
12         $e = new HTML::ElementSuper 'font';
13         $sibling_number = $e->addr();
14         $e2 = new HTML::ElementSuper 'p';
15         $e2->push_content($e);
16         #
17         @coords = $e->position();
18         $depth_in_pos_tree = $e->depth();
19
20         ### Replacer extension
21         $er = new HTML::ElementSuper 'font';
22         # Tree beneath $er, if present, is dropped.
23         $er->replace_content(new HTML::Element 'p');
24
25         ### Wrapper extension
26         $ew = new HTML::ElementSuper;
27         $ew->push_content("Tickle me, baby");
28         $ew->wrap_content(new HTML::Element 'font', color => 'pink');
29         print $ew->as_HTML();
30
31         ### Maskable extension
32         $em = new HTML::ElementSuper 'td';
33         $em->mask(1);
34         print $em->as_HTML; # nada
35         $em->mask(0);
36         print $em->as_HTML; # $e and its children are visible
37
38         ### Cloning of own tree or another element's tree
39         ### (is this the correct clomenature?  :-)
40         $a = new HTML::ElementSuper 'font', size => 2;
41         $b = new HTML::ElementSuper 'font', color => 'red';
42         $a_clone  = $a->clone;
43         $b_clone = $a->clone($b);
44         # Multiple elements can be cloned
45         @clone_clones = $a_clone->clone($a_clone, $b_clone);
46

DESCRIPTION

48       HTML::ElementSuper is an extension for HTML::Element(3) that provides
49       several new methods to assist in element manipulation. An
50       HTML::ElementSuper has the following additional properties:
51
52          * report is coordinate position in a tree of its peers
53          * replace its contents
54          * wrap its contents in a new element
55          * mask itself so that it and its descendants are invisible to
56            traverse()
57          * clone itself and other HTML::Element based object trees
58          * handle multiple values for attributes
59
60       Note that these extensions were originally developed to assist in
61       implementing the HTML::ElementTable(3) class, but were thought to be of
62       general enough utility to warrant their own package.
63

METHODS

65       new('tag', attr => 'value', ...)
66           Return a new HTML::ElementSuper object. Exactly like the
67           constructor for HTML::Element(3), takes a tag type and optional
68           attributes.
69
70       push_attr(attr => @values)
71           Extend the value string for a particular attribute. An example of
72           this might be when you'd like to assign multiple CSS classes to a
73           single element. The attribute value is extended using white space
74           as a separator.
75
76       addr()
77           Returns the position of this element in relation to its siblings
78           based on the content of the parent, starting with 0. Returns undef
79           if this element has no parent. In other words, this returns the
80           index of this element in the content array of the parent.
81
82       position()
83           Returns the coordinates of this element in the tree it inhabits.
84           This is accomplished by succesively calling addr() on ancestor
85           elements until either a) an element that does not support these
86           methods is found, or b) there are no more parents. The resulting
87           list is the n-dimensional coordinates of the element in the tree.
88
89       replace_content(@new_content)
90           Simple shortcut method that deletes the current contents of the
91           element before adding the new.
92
93       wrap_content($wrapper_element)
94           Wraps the existing content in the provided element. If the provided
95           element happens to be a non-element, a push_content is performed
96           instead.
97
98       mask
99       mask(mode)
100           Toggles whether or not this element is visible to parental methods
101           that visit the element tree using traverse(), such as as_HTML().
102           Valid arguments for mask() are 0 and 1. Returns the current setting
103           without an argument.
104
105           This might seem like a strange method to have, but it helps in
106           managing dynamic tree structures. For example, in
107           HTML::ElementTable(3), when you expand a table cell you simply mask
108           what it covers rather than destroy it. Shrinking the table cell
109           reveals that content to as_HTML() once again.
110
111       clone
112       clone(@elements)
113           Returns a clone of elements and all of their descendants. Without
114           arguments, the element clones itself, otherwise it clones the
115           elements provided as arguments. Any element can be cloned as long
116           as it is HTML::Element(3) based. This method is very handy for
117           duplicating tree structures since an HTML::Element cannot have more
118           than one parent at any given time...hence "tree".
119

REQUIRES

121       HTML::Element(3), Data::Dumper(3)
122

AUTHOR

124       Matthew P. Sisk, <sisk@mojotoad.com>
125

COPYRIGHT

127       Copyright (c) 1998-2010 Matthew P. Sisk. All rights reserved. All
128       wrongs revenged. This program is free software; you can redistribute it
129       and/or modify it under the same terms as Perl itself.
130