The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
HTML-Object-v0.4.0
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ HTML::Object::DOM::Element::Table

NAME

HTML::Object::DOM::Element::Table - HTML Object DOM Table Class

SYNOPSIS

    use HTML::Object::DOM::Element::Table;
    my $table = HTML::Object::DOM::Element::Table->new || 
        die( HTML::Object::DOM::Element::Table->error, "\n" );

VERSION

    v0.2.1

DESCRIPTION

This interface provides special properties and methods (beyond the regular HTML::Object::DOM::Element object interface it also has available to it by inheritance) for manipulating the layout and presentation of tables in an HTML document.

Tables can have, in this order:

1. an optional caption element,
2. zero or more colgroup elements,
3. an optional thead element,
4. either one of the following:

  • zero or more tbody elements

  • one or more tr elements

5. an optional tfoot element

The above is for reference only and is not enforced by this interface.

INHERITANCE

    +-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+
    | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Table |
    +-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+

PROPERTIES

Inherits properties from its parent HTML::Object::DOM::Element

caption

Is a table caption element representing the first caption that is a child of the element, or undef if none is found.

When set, if the object does not represent a caption, a HTML::Object::HierarchyRequestError error is returned. If a correct object is given, it is inserted in the tree as the first child of this element and the first caption that is a child of this element is removed from the tree, if any, and returned.

Example:

    my $table = $doc->getElementsByTagName( 'table' )->first;
    my $old_caption = $table->caption( $new_caption );
    # or
    $table->caption = $new_caption;

See also Mozilla documentation

rows

Read-only.

Returns a HTML Collection containing all the rows of the element, that is all tr that are a child of the element, or a child of one of its thead, tbody and tfoot children. The rows members of a thead appear first, in tree order, and those members of a tbody last, also in tree order.

Note that for performance improvement, the collection is cached until changes are made that would affect the results.

Example:

    <table id="myTable">
        <tr></tr>
        <tbody>
            <tr></tr>
        </tbody>
    </table>

    my $rows = $doc->getElementById( 'myTable' )->rows;
    say $rows->length; # 2

    <table id="myTable2">
        <tr>
            <td>
                <table>
                    <tr></tr>
                </table>
            </td>
        </tr>
        <tbody>
            <tr></tr>
        </tbody>
    </table>

    my $rows = $doc->getElementById( 'myTable2' )->rows;
    say $rows->length; # Still 2

See also Mozilla documentation

tBodies

Read-only.

Returns a HTML Collection containing all the tbody of the element.

Note that for performance improvement, the collection is cached until changes are made that would affect the results.

See also Mozilla documentation

tbodies

Alias for "tBodies"

tFoot

Is a HTML::Object::DOM::Element::TableSection representing the first tfoot that is a child of the element, or undef if none is found.

When set, if the object does not represent a tfoot, a HTML::Object::HierarchyRequestError error is returned.

If a correct object is given, it is inserted in the tree immediately before the first element that is neither a caption, a colgroup, nor a thead, or as the last child if there is no such element, and the first tfoot that is a child of this element is removed from the tree, if any.

See also Mozilla documentation

tHead

Is a HTML::Object::DOM::Element::TableSection representing the first thead that is a child of the element, or undef if none is found.

When set, if the object does not represent a thead, a HTML::Object::HierarchyRequestError error is returned.

If a correct object is given, it is inserted in the tree immediately before the first element that is neither a caption, nor a colgroup, or as the last child if there is no such element, and the first thead that is a child of this element is removed from the tree, if any.

See also Mozilla documentation

METHODS

Inherits methods from its parent HTML::Object::DOM::Element

createCaption

Returns an HTML::Object::DOM::Element representing the first caption that is a child of the element. If none is found, a new one is created and inserted in the tree as the first child of the table element.

Example:

    <table>
        <tr><td>Cell 1.1</td><td>Cell 1.2</td><td>Cell 1.3</td></tr>
        <tr><td>Cell 2.1</td><td>Cell 2.2</td><td>Cell 2.3</td></tr>
    </table>

    my $table = $doc->querySelector('table');
    my $caption = $table->createCaption();
    $caption->textContent = 'This caption was created by JavaScript!';

See also Mozilla documentation

createTBody

Returns a HTML::Object::DOM::Element::TableSection representing a new tbody that is a child of the element. It is inserted in the tree after the last element that is a tbody, or as the last child if there is no such element.

Example:

    my $mybody = $mytable->createTBody();
    # Now this should be true: $mybody == mytable->tBodies->item( $mytable->tBodies->length - 1 )

See also Mozilla documentation

createTFoot

Returns an HTML::Object::DOM::Element::TableSection representing the first tfoot that is a child of the element. If none is found, a new one is created and inserted in the tree as the last child.

Example:

    my $myfoot = $mytable->createTFoot();
    # Now this should be true: $myfoot == $mytable->tFoot

See also Mozilla documentation

createTHead

Returns an HTML::Object::DOM::Element::TableSection representing the first thead that is a child of the element. If none is found, a new one is created and inserted in the tree immediately before the first element that is neither a caption, nor a colgroup, or as the last child if there is no such element.

Example:

    my $myhead = mytable->createTHead();
    # Now this should be true: $myhead == mytable->tHead

See also Mozilla documentation

deleteCaption

Removes the first caption that is a child of the element and returns the object of the caption element.

Example:

    <table>
        <caption>This caption will be deleted!</caption>
        <tr><td>Cell 1.1</td><td>Cell 1.2</td></tr>
        <tr><td>Cell 2.1</td><td>Cell 2.2</td></tr>
    </table>

    my $table = $doc->querySelector('table');
    $table->deleteCaption();

See also Mozilla documentation

deleteRow

Removes the row corresponding to the index given in parameter. If the index value is -1 the last row is removed; if it smaller than -1 or greater than the amount of rows in the collection, an HTML::Object::IndexSizeError is returned.

Example:

    <table>
        <tr><td>Cell 1.1</td><td>Cell 1.2</td><td>Cell 1.3</td></tr>
        <tr><td>Cell 2.1</td><td>Cell 2.2</td><td>Cell 2.3</td></tr>
        <tr><td>Cell 3.1</td><td>Cell 3.2</td><td>Cell 3.3</td></tr>
    </table>

    my $table = $doc->querySelector('table');
    # Delete second row
    $table->deleteRow(1);

See also Mozilla documentation

deleteTFoot

Removes the first tfoot that is a child of the element and returns the object of the caption element.

Example:

    <table>
        <thead><th>Name</th><th>Score</th></thead>
        <tr><td>Bob</td><td>541</td></tr>
        <tr><td>Jim</td><td>225</td></tr>
        <tfoot><th>Average</th><td>383</td></tfoot>
    </table>

    my $table = $doc->querySelector('table');
    $table->deleteTFoot();

See also Mozilla documentation

deleteTHead

Removes the first thead that is a child of the element and returns the object of the caption element.

Example:

    <table>
        <thead><th>Name</th><th>Occupation</th></thead>
        <tr><td>Bob</td><td>Plumber</td></tr>
        <tr><td>Jim</td><td>Roofer</td></tr>
    </table>

    my $table = $doc->querySelector('table');
    $table->deleteTHead();

See also Mozilla documentation

insertRow

Returns an HTML::Object::DOM::Element::TableRow representing a new row of the table. It inserts it in the rows collection immediately before the tr element at the given index position, if any was provided. If there are no existing rows yet, a tbody is created and the new row inserted into it. If a table has multiple tbody elements, by default, the new row is inserted into the last tbody.

If the index is not given or is -1, the new row is appended to the collection. If the index is smaller than -1, it will start that far back from the end of the collection array. If index is greater than the number of rows in the collection, an HTML::Object::IndexSizeError error is returned.

Example:

    <table></table>

    $doc->getElementsByTagName('table')->[0]->insertRow();

Table is now:

    <table>
        <tbody>
            <tr></tr>
        </tbody>
    </table>

But if there are already existing rows and no tbody, the new row will merely be added as the las child of the table.

    <table>
        <tr></tr>
    </table>

    $doc->getElementsByTagName('table')->[0]->insertRow();

Table is now:

    <table>
        <tr></tr>
        <tr></tr>
    </table>

Even if there is a tfoot, the new row will be added after:

    <table>
        <tr></tr>
        <tfoot></tfoot>
    </table>

    $doc->getElementsByTagName('table')->[0]->insertRow();

Table is now:

    <table>
        <tr></tr>
        <tfoot></tfoot>
        <tr></tr>
    </table>

If an index is negative, the new row will be added that far back from the end:

    <table>
        <tr id="one"></tr>
        <tr id="two"></tr>
        <tr id="three"></tr>
    </table>

    $doc->getElementsByTagName('table')->[0]->insertRow(-2);

Table is now:

    <table>
        <tr id="one"></tr>
        <tr></tr>
        <tr id="two"></tr>
        <tr id="three"></tr>
    </table>

See also Mozilla documentation

DEPRECATED PROPERTIES

align

Is a string containing an enumerated value reflecting the align attribute. It indicates the alignment of the element's contents with respect to the surrounding context. The possible values are "left", "right", and "center".

See also Mozilla documentation

bgColor

A string containing the background color of the table. It reflects the obsolete bgcolor attribute.

See also Mozilla documentation

border

Is a string containing the width in pixels of the border of the table. It reflects the obsolete border attribute.

See also Mozilla documentation

cellPadding

Is a string containing the width in pixels of the horizontal and vertical sapce between cell content and cell borders. It reflects the obsolete cellpadding attribute.

See also Mozilla documentation

cellSpacing

Is a string containing the width in pixels of the horizontal and vertical separation between cells. It reflects the obsolete cellspacing attribute.

See also Mozilla documentation

frame

Is a string containing the type of the external borders of the table. It reflects the obsolete frame attribute and can take one of the following values: void, above, below, hsides, vsides, lhs, rhs, box, or border.

See also Mozilla documentation

rules

Is a string containing the type of the internal borders of the table. It reflects the obsolete rules attribute and can take one of the following values: none, groups, rows, cols, or all.

See also Mozilla documentation

summary

Is a string containing a description of the purpose or the structure of the table. It reflects the obsolete summary attribute.

See also Mozilla documentation

width

Is a string containing the length in pixels or in percentage of the desired width fo the entire table. It reflects the obsolete width attribute.

See also Mozilla documentation

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, Mozilla documentation on table element

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd.

All rights reserved

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