internal package Foswiki::Tables::Table

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

Perl Module:

Child packagesChild packages

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.

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.