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
Get the number of header rows on the table. Defaults to 0.
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.
ObjectMethod moveRow($from, $to [, $any_row]) → $boolean
Move a row
-
$from 0-based index of the row to move
-
$to 0-based index of the target position (before $from is removed!)
-
$any_row - true to request moving of header and footer rows
Rows must exist. The rows must be editable rows 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.
If $to is outside the editable part of the table, the row will be moved
to the first or last editable position respectively.
Returns true if the move succeeded.
ObjectMethod upRow($row [, $any_row]) → $boolean
Move a row up one position in the table
-
$row 0-based index of the row to move * $any_row - true to request moving of header and footer rows
Row must exist. The row must be 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 1 if the move succeeded.
ObjectMethod downRow($row [, $any_row]) → $boolean
Move a row down one position in the table
-
$row 0-based index of the row to move * $any_row - true to request moving of header and footer rows
Row must exist. The row must be 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 1 if the move succeeded.