.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::ElementSuper 3pm"
.TH HTML::ElementSuper 3pm "2022-12-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::ElementSuper \- Perl extension for HTML::Element(3)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use HTML::ElementSuper;
\&
\&  ### Positional extension
\&  $e = new HTML::ElementSuper \*(Aqfont\*(Aq;
\&  $sibling_number = $e\->addr();
\&  $e2 = new HTML::ElementSuper \*(Aqp\*(Aq;
\&  $e2\->push_content($e);
\&  # 
\&  @coords = $e\->position();
\&  $depth_in_pos_tree = $e\->depth();
\&
\&  ### Replacer extension
\&  $er = new HTML::ElementSuper \*(Aqfont\*(Aq;
\&  # Tree beneath $er, if present, is dropped.
\&  $er\->replace_content(new HTML::Element \*(Aqp\*(Aq);
\&
\&  ### Wrapper extension
\&  $ew = new HTML::ElementSuper;
\&  $ew\->push_content("Tickle me, baby");
\&  $ew\->wrap_content(new HTML::Element \*(Aqfont\*(Aq, color => \*(Aqpink\*(Aq);
\&  print $ew\->as_HTML();
\&
\&  ### Maskable extension
\&  $em = new HTML::ElementSuper \*(Aqtd\*(Aq;
\&  $em\->mask(1);
\&  print $em\->as_HTML; # nada
\&  $em\->mask(0);
\&  print $em\->as_HTML; # $e and its children are visible
\&
\&  ### Cloning of own tree or another element\*(Aqs tree
\&  ### (is this the correct clomenature?  :\-)
\&  $a = new HTML::ElementSuper \*(Aqfont\*(Aq, size => 2;
\&  $b = new HTML::ElementSuper \*(Aqfont\*(Aq, color => \*(Aqred\*(Aq;
\&  $a_clone  = $a\->clone;
\&  $b_clone = $a\->clone($b);
\&  # Multiple elements can be cloned
\&  @clone_clones = $a_clone\->clone($a_clone, $b_clone);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
HTML::ElementSuper is an extension for \fBHTML::Element\fR\|(3) that provides
several new methods to assist in element manipulation. An
HTML::ElementSuper has the following additional properties:
.PP
.Vb 7
\&   * report is coordinate position in a tree of its peers
\&   * replace its contents
\&   * wrap its contents in a new element
\&   * mask itself so that it and its descendants are invisible to
\&     traverse()
\&   * clone itself and other HTML::Element based object trees
\&   * handle multiple values for attributes
.Ve
.PP
Note that these extensions were originally developed to assist in
implementing the \fBHTML::ElementTable\fR\|(3) class, but were thought to be of
general enough utility to warrant their own package.
.SH "METHODS"
.IX Header "METHODS"
.IP "new('tag', attr => 'value', ...)" 4
.IX Item "new('tag', attr => 'value', ...)"
Return a new HTML::ElementSuper object. Exactly like the constructor for
\&\fBHTML::Element\fR\|(3), takes a tag type and optional attributes.
.ie n .IP "push_attr(attr => @values)" 4
.el .IP "push_attr(attr => \f(CW@values\fR)" 4
.IX Item "push_attr(attr => @values)"
Extend the value string for a particular attribute. An example of this
might be when you'd like to assign multiple \s-1CSS\s0 classes to a single
element. The attribute value is extended using white space as a
separator.
.IP "\fBaddr()\fR" 4
.IX Item "addr()"
Returns the position of this element in relation to its siblings based
on the content of the parent, starting with 0. Returns undef if this
element has no parent. In other words, this returns the index of this
element in the content array of the parent.
.IP "\fBposition()\fR" 4
.IX Item "position()"
Returns the coordinates of this element in the tree it inhabits. This is
accomplished by succesively calling \fBaddr()\fR on ancestor elements until
either a) an element that does not support these methods is found, or b)
there are no more parents. The resulting list is the n\-dimensional
coordinates of the element in the tree.
.IP "replace_content(@new_content)" 4
.IX Item "replace_content(@new_content)"
Simple shortcut method that deletes the current contents of the element
before adding the new.
.IP "wrap_content($wrapper_element)" 4
.IX Item "wrap_content($wrapper_element)"
Wraps the existing content in the provided element. If the
provided element happens to be a non-element, a push_content is
performed instead.
.IP "mask" 4
.IX Item "mask"
.PD 0
.IP "mask(mode)" 4
.IX Item "mask(mode)"
.PD
Toggles whether or not this element is visible to parental methods that
visit the element tree using \fBtraverse()\fR, such as \fBas_HTML()\fR. Valid
arguments for \fBmask()\fR are 0 and 1. Returns the current setting without
an argument.
.Sp
This might seem like a strange method to have, but it helps in managing
dynamic tree structures. For example, in \fBHTML::ElementTable\fR\|(3), when
you expand a table cell you simply mask what it covers rather than
destroy it. Shrinking the table cell reveals that content to \fBas_HTML()\fR
once again.
.IP "clone" 4
.IX Item "clone"
.PD 0
.IP "clone(@elements)" 4
.IX Item "clone(@elements)"
.PD
Returns a clone of elements and all of their descendants. Without
arguments, the element clones itself, otherwise it clones the elements
provided as arguments. Any element can be cloned as long as it is
\&\fBHTML::Element\fR\|(3) based. This method is very handy for duplicating tree
structures since an HTML::Element cannot have more than one parent at
any given time...hence \*(L"tree\*(R".
.SH "REQUIRES"
.IX Header "REQUIRES"
\&\fBHTML::Element\fR\|(3), \fBData::Dumper\fR\|(3)
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthew P. Sisk, <\fIsisk@mojotoad.com\fR>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1998\-2010 Matthew P. Sisk. All rights reserved. All wrongs
revenged. This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBHTML::Element\fR\|(3), \fBHTML::ElementGlob\fR\|(3), \fBHTML::ElementRaw\fR\|(3), \fBHTML::ElementTable\fR\|(3), \fBperl\fR\|(1).