You are here: HamWiki>System Web>Category>DeveloperDocumentationCategory>PerlDoc (24 Jun 2022, ProjectContributor)Edit Attach

PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

`internal package` Foswiki::Tables::Table

Abstract model of a table in a topic, suitable for use with the tables parser.

A table consists of specification and a set of rows. The specification gives type information about the columns it the table, to allow suitable editors to be instantiated on cells.

The rows in the tables are divided into a block of (uneditable) header rows, a block of (ediatble) body rows, and a block of (uneditable) footer rows. Any of these blocks may be empty.

A Table object has the following public fields:

{specs} - if given, the $specs passed to the constructor (array)
{rows} - array of Foswiki::Tables::Row objects (or a subclass thereof)
{number} - an identifier for this table in the sequence of tables in the topic. undef until set by some external agency (e.g. the parser).
{colTypes} - each column format is stored in the {colTypes} array. Entries in this array have the following fields:
- type - the type e.g. text, radio
- size - the (unverified) size, e.g. 1, 10x8 (defaults to 20 for text, 40x5 for textarea and 1 for any other type)
- initial_value - everything after the second comma for text, label and date. The empty string otherwise.
- values - array generated by treating everything after the second comma as a csv list.
{headerrows} - number of header rows in the table. If no header rows are specified in the spec this will be undef.
{footerrows} - number of footer rows in the table. If no footer rows are specified in the spec this will be undef.

`ClassMethod` new($specs [, $supertag])

Constructor

$specs - array of tag specs that affect this table. Each spec is defined as follows:
- raw is the string representation of the macro that apply to this table. Only required so that the table can be accurately serialised to TML.
- tag - simple string name of the tag
- attrs - Foswiki::Attrs for the tag. Note that these may have been heavily modified due to expansion of include parameters.
$supertag - optional tag that overrides all other tags

The following entries in attrs are used:

format - The format of the cells in a row of the table. The format is defined like a table row, where the cell data specify the type for each cell. For example, format="| text,16 | label |". Cells can be any of the following types:
- text, <size>, <initial value> Simple text field. Initial value is optional.
- textarea, <rows>x<columns>, <initial value> Multirow text box. Initial value is optional.
- select, <size>, <option 1>, <option 2>, etc Select one from a list of choices.
- radio, <size>, <option 1>, <option 2>, etc. Radio buttons. size indicates the number of buttons per line in edit mode.
- checkbox, <size>, <option 1>, <option 2>, etc Checkboxes. size indicates the number of buttons per line in edit mode.
- label, 0, <label text> Fixed label.
- row The row number, automatically worked out.
- date, <size>, <initial value>, <DHTML date format> Date. Initial value and date format are both optional.
headerrows - integer number of rows in the thead
footerrows - integer number of rows in the tfoot
extras - optional Foswiki::Attrs hash of extra attributes
initsort, sort, disableallsort

`ClassMethod` row_class() → $classname

Perl class used for constructing table rows (default Foswiki::Tables::Row) Designed to be overridden in subclasses that want to use their own subclass of Foswiki::Tables::Row for their rows.

`ClassMethod` getMacros() → @macronames

Get a list of the macro names for additional attributes for tables e.g 'EDITTABLE'. These macros will be processed and combined onto the first recognisable table that follows the macro. Subclasses can choose to override this to ignore TABLE tags, or call SUPER and add their own tags.

`ObjectMethod` finish()

Clean up for disposal

`ObjectMethod` makeConsistent()

Check that the table is consistent with the spec, and fix it if not. If there are header and footer rows defined in the the spec, there have to be enough rows in the table for them. If fix is true, empty rows will be added to flesh out to the required number of rows.

Added rows will have the number of columns and initial data specified by the format spec (minimum 1 colun)

`ObjectMethod` totalRows() → $integer

Return the total number of rows in the table (including header and footer rows)

`ObjectMethod` number([$set]) → $number

Setter/getter for the table number. The table number uniquely identifies the table within the context of a topic. The table number is undef until it is set by some external agency.

`ObjectMethod` stringify()

Generate a TML representation of the table

`ObjectMethod` getHeaderRows() → $integer

Get the number of header rows on the table. Defaults to 0.

`ObjectMethod` getFooterRows() → $integer

Get the number of footer rows on the table.

`ObjectMethod` getID() → $id

Generate a unique string ID that uniquely identifies this table within a topic. Useful for identifying a table in the context of REST calls that modify the table.

`ObjectMethod` getFirstBodyRow() → $integer

Get the 0-based row index of the first editable row after the header. The row may not actually exist in the {rows}; this is just the index of the row if it does exist.

`ObjectMethod` getLastBodyRow() → $integer

Get the 0-based row index of the last row before the footer. The row may not actually exist in the {rows}; this is just the index of the row if it does exist, given the current size of the table.

`ObjectMethod` getCellData([$row [, $col]]) → $data

Get cell, row, column or entire table, depending on params.

If $row and $col are given, return the scalar stored in that cell.
If only $row is given, then return an array of the data in each column.
If $row is undef but $col is given, return an array of the data in that col.
If neither $row nor $col is given, return a 2D array of the cell data.

Only data which exists in the table is returned; columns missing from rows will be filled out with undef.

`ObjectMethod` getLabelRow() → $rowobj

Get the last header row before the first body row. undef if there is no label row.

`ObjectMethod` addRow($row [, $newRow [, $any_row]]) → $rowObject

Construct and add a row after the given row * $row - 0-based index of the row to add after * $newRow - the row to add. A new row will be created using the row_class if this is undefined.

$any_row - true to ignore header and footer constraints when adding rows.

If !$any_row, and $row is < 0, then adds to the start of the body rows. If !$any_row and $row is after the last body row, then adds the row to the end of the body rows. if $any_row, and $row < 0, then adds to the start of the table. If $any_row, and $row is after the last table row (including the footer) the adds the row to the end of the table.

New rows are created with the number of columns specified in the format spec for the table or, failing that, the width of row 0 of the table.

If $any_row is false, the table will be made consistent (missing header/footer rows added) before anything else is done.

Returns the new row.

`ObjectMethod` isEditableRow($row) → $boolean

Return true if the given row is editable i.e. is a body row, and exists.

deleteRow($row [, $any_row]) → $boolean

Delete the given row * $row - 0-based index of the row to delete * $any_row - true to request deletion of header and footer rows The row must exist. The row must be an editable row unless $any_row is true.

If $any_row is false, the table will be made consistent (missing header/footer rows added) before anything else is done.

Returns true if the row was deleted.