123. A generic, parameterizable, table editor command

Parameter syntax:

'insertColumnBefore'|'insertColumnAfter'|
'cutColumn'|'copyColumn'|
'pasteColumnBefore'|'pasteColumnAfter'|
'deleteColumn'|
'insertRowBefore'|'insertRowAfter'|
'cutRow'|'copyRow'|
'pasteRowBefore'|'pasteRowAfter'|
'deleteRow'|
'incrColumnSpan'|'decrColumnSpan'|
'incrRowSpan'|'decrRowSpan'

This command may be used to edit any table conforming to a model vaguely resembling the HTML table model (table contains rows, themselves possibly contained in row groups, etc).

Prerequisite in terms of selectionParameterDescription

A cell or an element having a cell ancestor must be implicitly or explicitly selected.

insertColumnBeforeInsert a column before column containing specified cell.
insertColumnAfterInsert a column after column containing specified cell.
cutColumnCut to the clipboard the column containing specified cell.
copyColumnCopy to the clipboard the column containing specified cell.
pasteColumnBeforePaste copied or cut column before column containing specified cell.
pasteColumnAfterPaste copied or cut column after column containing specified cell.
deleteColumnDelete the column containing specified cell.
sortRows

Sort all the rows of the table according to the string values of the cells of the “selected column”. (The “selected column” is the column containing specified cell.)

A dialog box is displayed allowing to specify the following sort options:

Order

Dictionary is the language-specific alphabetical order. Example: (Charles, best, Albert) is sorted as (Albert, best, Charles).

Numeric. The string value of a cell is expected to start with a number. Example: (+15.0%, 1.50%, -20%) is sorted as (-20%, 1.50%, +15.0%).

Lexicographic is the order of Unicode characters. Example: (Charles, best, Albert) is sorted as (Albert, Charles, best).

Dictionary and Numeric orders will cause this command to fail, unless the language of the table can be determined (e.g. lookup for the xml:lang attribute).

Direction

Ascending means: A to Z, low to high. Descending means: Z to A, high to low.

Note that:

  • Header/footer rows (e.g. thead) are never sorted.

  • The contents of row groups (e.g. tbody) are sorted separately.

A row must be explicitly selected.

OR a cell or an element having a cell ancestor must be implicitly or explicitly selected.

insertRowBefore

Insert a row before row containing specified cell.

insertRowAfterInsert a row before row containing specified cell.
cutRowCut to the clipboard the row containing specified cell.
copyRowCopy to the clipboard the row containing specified cell.
pasteRowBeforePaste copied or cut row before row containing specified cell.
pasteRowAfterPaste copied or cut row after row containing specified cell.
deleteRowDelete the row containing specified cell.

A cell or an element having a cell ancestor must be implicitly or explicitly selected.

incrColumnSpanIncrement the number of columns spanned by specified cell.
decrColumnSpanDecrement the number of columns spanned by specified cell.
incrRowSpanIncrement the number of rows spanned by specified cell.
decrRowSpanDecrement the number of rows spanned by specified cell.

Unlike the other commands contained in this reference, this command has no fixed name. It must be instantiated and given a name using a command configuration element (see Section 4, “command” in XMLmind XML Editor - Configuration and Deployment). It must also be parametrized using a simple specification contained in a property configuration element. See example below:

DITA simpletable example:

  <command name="dita.simpleTableEdit">1
    <class>com.xmlmind.xmledit.cmd.table.GenericTableEdit</class>
  </command>

  <property name="dita.simpleTableEdit.tableSpecification">2
    table=simpletable
    row=sthead:header strow
    cell=stentry
  </property>

1

This creates an instance of generic, parameterizable, table editor command com.xmlmind.xmledit.cmd.table.GenericTableEdit called dita.simpleTableEdit.

2

Because the table editor command is called dita.simpleTableEdit, a property called dita.simpleTableEdit.tableSpecification should exist too. The value of this property maps element names and attribute names to roles understood by the generic table editor command.

Example 1: "cell=th td" specifies that an element with name th or td should be considered by the generic table editor as being a cell.

Example 2: "rowSpan=morerows+1" specifies that attribute morerows, if found in cell elements, contains the number of additional rows spanned by the cell.

In the above example, the fact that the rowGroup=, rowSpan= and columnSpan= lines are missing means that this table model does not have the concept of row groups and that there are no attributes which could be used to specify the number of rows and the number of columns spanned by a cell.

The syntax of a table specification is:

spec -> table_spec row_group_spec? row_spec cell_spec 
        row_span_spec? column_span_spec?

table_spec -> table= element_name_list \n

row_group_spec -> rowGroup= element_name_role_list \n

row_spec -> row= element_name_role_list \n

cell_spec -> cell= element_name_list \n

row_span_spec -> rowSpan= attribute_name_list \n

column_span_spec -> columnSpan= attribute_name_list \n

element_name_role_list -> name_role {S name_role}*

name_role -> name{role}?

role -> :header | :footer | :body

element_name_list -> name {S name}*

attribute_name_list -> name{+1}? {S name{+1}?}*

name = non_qualified_name | {namespace_URI}local_part
table=

Specifies the names of the elements which must be considered as being tables, that is, row group containers or, directly, row containers (like in HTML 3.2 tables).

rowGroup=

Specifies the names of the elements which must be considered as being row groups, that is, row containers. May be omitted if not relevant.

The name of an element may be optionally followed by :header if the corresponding row group is a table header, :footer if the corresponding row group is a table footer and :body if the corresponding row group is a table body. By default, a row group is considered to be a table body.

row=

Specifies the names of the elements which must be considered as being rows, that is, cell containers.

The name of an element may be optionally followed by :header if the corresponding row is a table header, :footer if the corresponding row is a table footer and :body if the corresponding row is a normal row. By default, a row is considered to be a normal row.

cell=

Specifies the names of the elements which must be considered as being cells.

rowSpan=

Specifies the names of the attributes which are used to specify the number of rows spanned by a cell. May be omitted if not relevant.

Use +1 to specify that the attribute contains an additional number of rows rather than the actual number of rows spanned by a cell.

columnSpan=

Specifies the names of the attributes which are used to specify the number of columns spanned by a cell. May be omitted if not relevant.

Use +1 to specify that the attribute contains an additional number of rows rather than the actual number of rows spanned by a cell.

Example 1: the specification of an XHTML table would be:

table={http://www.w3.org/1999/xhtml}table
rowGroup={http...ml}tbody {http...ml}thead:header {http...ml}tfoot:footer
row={http...ml}tr
cell={http...ml}td {http...ml}th
rowSpan=rowspan
columnSpan=colspan

Notice how the XHTML namespace is specified before the local name of each element.

Example 2: a partial specification for CALS (DocBook 4; no namespace) tables would be:

table=tgroup entrytbl
rowGroup=tbody thead:header tfoot:footer
row=row
cell=entry
rowSpan=morerows+1

The fact that the columnSpan= line is missing means that there is no attribute which could be used to specify the number of columns spanned by a cell.