HTML::...tSuper(3pm)

💖 HTML::ElementSuper 💖

okay bestie, come sit with me — this is HTML::ElementSuper, a User Contributed Perl Documentation page, and it's genuinely one of the most fun little extension modules out there. No cap. Let me walk you through it like we're texting at 1am. 🦋

---

✨ NAME ✨

HTML::ElementSuper — a Perl extension for HTML::Element(3). It's giving main character energy, fr fr. 💅

---

🎀 SYNOPSIS 🎀

Here's the whole vibe, verbatim, because I refuse to paraphrase code:

use HTML::ElementSuper;

### Positional extension
$e = new HTML::ElementSuper 'font';
$sibling_number = $e->addr();
$e2 = new HTML::ElementSuper 'p';
$e2->push_content($e);
#
@coords = $e->position();
$depth_in_pos_tree = $e->depth();

### Replacer extension
$er = new HTML::ElementSuper 'font';
# Tree beneath $er, if present, is dropped.
$er->replace_content(new HTML::Element 'p');

### Wrapper extension
$ew = new HTML::ElementSuper;
$ew->push_content("Tickle me, baby");
$ew->wrap_content(new HTML::Element 'font', color => 'pink');
print $ew->as_HTML();

### Maskable extension
$em = new HTML::ElementSuper 'td';
$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's tree
### (is this the correct clomenature?  :-)
$a = new HTML::ElementSuper 'font', size => 2;
$b = new HTML::ElementSuper 'font', color => 'red';
$a_clone  = $a->clone;
$b_clone = $a->clone($b);
# Multiple elements can be cloned
@clone_clones = $a_clone->clone($a_clone, $b_clone);

Not me reading that and immediately wanting to wrap everything in a pink font. 😭

---

🌸 DESCRIPTION 🌸

So HTML::ElementSuper is an extension for HTML::Element(3) that hands you a bunch of new methods to help with element manipulation. And an HTML::ElementSuper comes with these extra little superpowers:

• 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 💅

Quick lore drop: these extensions were originally developed to help implement the HTML::ElementTable(3) class, but everyone agreed they were of general enough utility to warrant their own package. Iconic behaviour, honestly. 👑

---

⭐ METHODS ⭐

💖 new('tag', attr => 'value', ...)

Returns a new HTML::ElementSuper object. It's exactly like the constructor for HTML::Element(3) — you hand it a tag type and some optional attributes. That's it. That's the whole thing. ✨

💖 push_attr(attr => @values)

Extends the value string for a particular attribute. Picture this: you want to assign multiple CSS classes to a single element. Yeah. This is the one. The attribute value gets extended using white space as the separator. 🌈

💖 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? It returns the index of this element in the content array of the parent. Sibling vibes, ranked. 💅

💖 position()

Returns the coordinates of this element in the tree it inhabits. How does it do that, you ask? Bestie, it succesively calls addr() on ancestor elements until either:

1. an element that does not support these methods is found, or
2. there are no more parents.

The resulting list is the n-dimensional coordinates of the element in the tree. 🗺️✨

💖 replace_content(@new_content)

A simple shortcut method that deletes the current contents of the element before adding the new. Out with the old, in with the new. Periodt. 💀

💖 wrap_content($wrapper_element)

Wraps the existing content in the provided element. And if the provided element happens to be a non-element? A push_content is performed instead. Adaptable queen. 👑

💖 mask / mask(mode)

Toggles whether or not this element is visible to parental methods that visit the element tree using traverse(), such as as_HTML(). Valid arguments for mask() are 0 and 1. Returns the current setting without an argument. 🙈

Now, this might seem like a strange method to have, but it helps in managing dynamic tree structures. Example: in HTML::ElementTable(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 as_HTML() once again. Hide and seek, but make it data structures. 🦋

💖 clone / clone(@elements)

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 HTML::Element(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 "tree". 🌳

---

🌈 REQUIRES 🌈

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

Just the two. Low maintenance bestie. 🫶

---

👑 AUTHOR 👑

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

---

💜 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.

"All wrongs revenged" is genuinely the hardest line in any manpage and I think about it constantly. 😭🔥

---

🌟 SEE ALSO 🌟

HTML::Element(3), HTML::ElementGlob(3), HTML::ElementRaw(3), HTML::ElementTable(3), perl(1).

---

Okay and for the little footer moment, bestie: this page is from perl v5.40.1, dated 2025-03-27. So yeah, go forth and supercharge your elements. Slay. 💅✨🎀