Table

Xeditor table plugin

What it does

This plugin adds support for tables and table actions to Xeditor for html and cals. If configured, you can easily insert new rows/columns and perform merges between table cells.

Installation

First you have to switch into your project location using the command line.

cd path/to/your/project

Now you should be in the same directory as the package.json file. Then you can install the plugin as follows:

npm install @xeditor/plugin-table --save --registry https://npm.xeditor.com:4873

Configuration

The structure of the plugin configuration looks like this

{
	pluginId: 'table',
	ptype: 'uxxeditortable',
	tables: object|object[],
	overlay: object,
	menu: object,
	percentBehaviour: 'free'|'clamp'|'force',
	widthBehaviour: 'auto'|'fill'|'overflow',
	supportedUnitsFn: function,
	editableAttributesFn: function,
	resizeTableOnPaste: boolean,
	fixTablesOnLoad: boolean,
	ignoreCaptionOnMove: boolean,
	pasteRowAsNewRow: boolean,
	allowedBackgroundColors: string[]|function,
	allowedBorderColors: string[]|function,
	allowedBorderStyles: string[]|function,
	allowedBorderWidths: string[]|function,
	allowAdvancedColorPicker: string[]|function,
	rangeExpandMode: 'expand'|'legacy'|'auto'|'autoInclude'
}

Config	Type	Default	Required	Description
pluginId	string	-	yes	Plugin id
ptype	string	-	yes	Plugin component type/alias
tables	object | object[]	-	yes	One or more table model configs (see Table models for more info)
overlay	object	-	no	Table overlay config (see Overlay for more info)
menu	object	-	no	Table menu config (see Context menu for more info)
percentBehaviour	'free' | 'clamp' | 'force'	"force"	no	Defines how the editor should handle percent values.free: No regulation, the editor allows all values in any combination.clamp: The editor allows different values, but all percent values must add up to 100. force: If at least one size is given in percent, the editor forces the user to provide all values in percent values which must add up to 100.
widthBehaviour	'auto' | 'fill' | 'overflow'	"auto"	no	Defines how the absolute width of the table is calculated.auto: The size of the table is equal to the combined size of all table columns (allows horizontal scroll).fill: The size of the table is always equal to 100% of its parent container. With this setting the width of the cells might not 100% reflect the set attributes since the combinded width always adds up to 100% (does not allow horizontal scroll).overflow: The same as fill but allows horizontal scroll.
supportedUnitsFn	Function	-	no	Callback function which must return a list of all supported units (e.g. ['%', 'px', 'in', 'auto'])
editableAttributesFn	Function	-	no	Callback function which must return a list of internal attribute names which should be editable via the table config dialog
resizeTableOnPaste	boolean	true	no	If set to true tables will be resized when the pasted content does not fit (additional rows/cols are added).
fixTablesOnLoad	boolean	false	no	A configuration flag that, when set to true, ensures that tables are fixed and properly formatted on page load. If false, tables will not be automatically adjusted on load.
ignoreCaptionOnMove	boolean	true	no	Flag to allow or disallow the editor to ignore a table caption when dragging or copying entire tables
pasteRowAsNewRow	boolean	true	no	Flag indicating whether a table row is to be pasted as a new row or whether the currently selected row is to be overwritten
allowedBackgroundColors	string[] | Function	Ext.ux.xeditor.plugin. table.Plugin.BACKGROUND_COLORS	no	Defines which background colors should be allowed.
allowedBorderColors	string[] | Function	Ext.ux.xeditor.plugin. table.Plugin.BORDER_COLORS	no	Defines which border colors should be allowed.
allowedBorderStyles	string[] | Function	Ext.ux.xeditor.plugin. table.Plugin.BORDER_STYLES	no	Defines which border styles should be allowed.
allowedBorderWidths	string[] | Function	Ext.ux.xeditor.plugin. table.Plugin.BORDER_WIDTHS	no	Defines which border widths should be allowed.
allowAdvancedColorPicker	string[] | Function	true	no	Defines if the advanced color picker should be usable for background or border colors or not. If no advanced color picker can be used, the color set is restricted to the configured colors.
rangeExpandMode	'expand' | 'legacy' | 'auto' | 'autoInclude'	"auto"	no	Indicates how the editor should handle table range selections across merged cells.expand: Expands the table selection range to a square around all cells contained in the range.legacy: Does not expand the selection range and therefore not always builds a square (same behaviour as the old table plugin).auto: Expands if the user selects a range from cell a to cell b. Ignores merged cells which are not fully enclosed, only if the selection was done by clicking on a row or column action button.autoInclude: The same as auto but includes all cells which overlap with the selection boundaries instead of excluding them.

Example configuration

This is an example plugin configuration. It does not include all possible configurations.

{
	pluginId: 'table',
	ptype: 'uxxeditortable',
	// return an array of units which should be supported
	// all of these must be included in the supported units of the plugin itself
	supportedUnitsFn: (editor, tablePlugin, tableModel) => {
		return ['%', 'px', 'in', 'auto'];
	},
	// only configure a single table
	// this may also be an array
	tables: {
		type: 'html',
		table: 'tab_table',
		caption: 'tab_caption',
		head: 'tab_head',
		body: 'tab_body',
		foot: 'tab_foot',
		// row and cell can be given as single string or as an array of strings
		row: 'tab_row',
		cell: ['tab_cell', 'tab_headcell'],
		// map internal attribute names (keys) to the actual cell attribute names (values)
		attributes: {
			align: 'text_align',
			background: 'cell_bg',
			colspan: 'colspan',
			rowspan: 'rowspan',
		},
		// map internal attribute names to actual row attribute names
		rowAttributes: {
			height: 'rowheight'
		},
		// disable borders via the cell style tag
		enableStyleBorders: false
	},
	menu: {
		// don't add disabled buttons to the context menu
		addDisabledButtons: false,
		// change the menu nesting to 3, to minimize the context menu size
		// this will collapse the entire table menu into a single submenu
		contextMenuNesting: 3
	},
	overlay: {
		// allow the resize of rows and columns
		enableResize: 'all',
		// only show insert buttons in the overlay (no delete buttons)
		enableActions: 'insert',
		// don't display column names in the top action row
		displayColumnNames: false,
		sizeTooltipPattern: 'Example tooltip: Inch => ${in:2}'
	}
}

Table models

How to configure a table model

To configure a table model provide one or more table model configurations.
A single configuration can be one of the following:\

• No table config

  If no table configuration is provided, it will be automatically generated based on the behaviors.
  However, this requires a correctly established behavior configuration in your project.

• A single string

  This will use the default model configuration for the provided model type (cals or html).
  Automatically excludes attributes or type names which are not available from the used schema.
  Can't be extended.

  tables: 'cals'

• Extend default model

  This will use the default model as base for the final configuration.
  Thus, all specified configuration options will be applied, and any options not provided will default to those set in the base model.
  Can be combined with type to extend the configuration of model a but use model b.

  tables: {
  	extends: 'cals',
  	table: 'my_custom_table',
  	cell: 'my_nice_cell'
  }

• Full model configuration

  Providing a full model configuration requires you to provide all necessary types and attributes.

  tables: {
  	type: 'cals',
  	table: 'my_table',
  	cell: 'my_cell',
  	row: 'my_row',
  	col: 'my_col',
  	...
  }

Table model structure

The table models config consists out of one or more model configurations.
A single model configuration is structured as follows.

{
	type: string,
	table: string,
	caption: string,
	head: string,
	body: string,
	foot: string,
	row: string|string[],
	cell: string|string[],
	col: string,
	colgroup: string,
	wrapPath: string[],
	attributes: {
		align: string,
		valign: string,
		background: string,
		colspan: string,
		rowspan: string,
		namest: string,
		nameend: string,
		colsep: string,
		rowsep: string,
		style: string
	},
	columnAttributes: {
		align: string,
		valign: string,
		width: string,
		name: string,
		number: string,
		colsep: string,
		rowsep: string
	},
	rowAttributes: {
		align: string,
		valign: string,
		height: string,
		colsep: string,
		rowsep: string
	},
	tableAttributes: {
		align: string,
		valign: string,
		colsep: string,
		rowsep: string,
		frame: string,
		rules: string,
		border: string
	},
	enableStyleBorders: boolean,
	enableAutoColnums: boolean
}

Depending on the configured model type, not all of the above configs are required or supported.

---

Basic model config options

Config	Type	Default	Required	Description
type	'html' | 'cals'	"html"	no	The type of the model (e.g. 'html' or 'cals')
table	string	-	yes	The table element type
caption	string	-	no	The table caption element type
head	string	-	no	The table head element type
body	string	-	no	The table body element type. If only one row container type exists, it should be asigned to the body. If no row container type exists head, body and foot can be omitted altogether.
foot	string	-	no	The table foot element type
row	string | string[]	-	yes	One or more row element types
cell	string | string[]	-	yes	One or more cell element types
col	string	-	no	Column definition element type
colgroup	string	-	no	Colgroup element type
wrapPath	string[]	-	no	Optional wrap path which contains one or more table wrapper elements
attributes	object	null	no	Mapping object which maps internal attribute names to cell attribute names
columnAttributes	object	null	no	Mapping object which maps internal attribute names to column attribute names
rowAttributes	object	null	no	Mapping object which maps internal attribute names to row attribute names
tableAttributes	object	null	no	Mapping object which maps internal attribute names to table attribute names
enableStyleBorders	boolean	true	no	Enables or disables cell borders via the style attribute
enableAutoColnums	boolean	true	no	Enables or disables the automatic numbering of column numbers

---

Attributes config options (attributes)

Config	Type	Default	Required	Description
colspan	string	-	no	Column span
rowspan	string	-	no	Row span
align	string	-	no	Horizontal text align
valign	string	-	no	Vertical text align
background	string	-	no	Cell background color
namest	string	-	no	Start column name
nameend	string	-	no	End column name
colsep	string	-	no	Column border
rowsep	string	-	no	Row border
style	string	-	no	Cell style

---

Column attributes config options (columnAttributes)

Config	Type	Default	Required	Description
align	string	-	no	Horizontal text align
valign	string	-	no	Vertical text align
width	string	-	no	Column width
name	string	-	no	Column name
number	string	-	no	Column number
colsep	string	-	no	Column border
rowsep	string	-	no	Row border

---

Row attributes config options (rowAttributes)

Config	Type	Default	Required	Description
align	string	-	no	Horizontal text align
valign	string	-	no	Vertical text align
height	string	-	no	Row height
colsep	string	-	no	Column border
rowsep	string	-	no	Row border

---

Table attributes config options (tableAttributes)

Config	Type	Default	Required	Description
align	string	-	no	Horizontal text align
valign	string	-	no	Vertical text align
colsep	string	-	no	Column border
rowsep	string	-	no	Row border
frame	string	-	no	Table border
rules	string	-	no	Border lines between rows or columns
border	string	-	no	Width of the border which is set by frame or rules

Overlay

The table overlay supports the following configurations. The overlay is the UI element which helps editing tables directly within the docuemnt.

{
	enabled: boolean,
	enableSelect: boolean,
	enableMaximize: boolean,
	showNumbers: string,
	enableResize: string,
	enableActions: string,
	highlightSelection: boolean,
	highlightActions: boolean,
	displayColumnNames: boolean,
	sizeTooltipPattern: string|function,
	resizeUnit: string,
	padding: number
}

Config	Type	Default	Required	Description
enabled	boolean	true	no	Enables or disables the entire overlay
enableSelect	boolean	true	no	Enabels or disables the selection via the overlay action rows
enableMaximize	boolean	false	no	Enabels or disables the table maximize button
showNumbers	'all' | 'row' | 'col' | 'none'	"all"	no	Configures which row/column numbers should be shown
enableResize	'all' | 'row' | 'col' | 'none'	"col"	no	Enables or disables the resize of rows/columns via the overlay
enableActions	'all' | 'delete' | 'insert' | 'none'	"all"	no	Configures which table actions should be available via the overlay
highlightSelection	boolean	true	no	True to highlight the active table selection within the action rows
highlightActions	boolean	true	no	True to highlight/preview table actions when hovering over corresponding buttons
displayColumnNames	boolean	true	no	True to display the column names (the attribute which maps to name in columnAttributes) instead of a continuous alphanumeric number (A,B,C,...). This has no effect if showNumbers is set to row or none.
sizeTooltipPattern	string | function	"\${axis}: \${cm:2} (\${px})"	no	The pattern which builds the resize tooltip. If this is a function the return value will be used as tooltip text.${axis} replaces with the current axis (width or height).${unit:precision} replaces with the width of the colum/row converted to the given unit and precision.
resizeUnit	string	"px"	no	Default unit to set the size of rows/columns (defaults to px or the first supported absolute unit)
padding	number	0	no	The distance in px between the overlay action rows and the table.

Context menu

{
	enableContextMenu: boolean,
	addDisabledButtons: boolean,
	addSeparators: boolean,
	contextMenuInsertIndex: number,
	contextMenuNesting: number
}

Config	Type	Default	Required	Description
enableContextMenu	boolean	true	no	Enables or disables the table context menu
addDisabledButtons	boolean	true	no	True to also add disabled buttons to the context menu
addSeparators	boolean	true	no	True to add seperators to visually group table actions
contextMenuInsertIndex	number	1	no	Insert index of the table context menu items
contextMenuNesting	number	1	no	The nesting level of context menu items the possible values are 0,1,2,3

Supported units

The following size units are supported by the plugin.

Name	Key	Type	Description
Percent	%	relative	Percent value
Centimeter	cm	absolute	Centimeter value
Millimeter	mm	absolute	Millimeter value
Point	pt	absolute	Point value
Pixel	px	absolute	Pixel value
Picas	pc	absolute	Picas value
Inch	in	absolute	Inch value
Auto	auto	auto	Auto size (the editor automatically calculates the size of the cell). This is only allowed if the corresponding attribute is not required.

Default schema configurations

Table configurations for default schemas like CALS or HTML.

These must go in the tables config options of the plugin itself.

CALS

{
	table: 'tgroup',
	col: 'colspec',
	colgroup: 'colgroup',
	row: 'row',
	cell: 'entry',
	body: 'tbody',
	foot: 'tfoot',
	head: 'thead',
	wrapPath: ['table'],
	attributes: {
		align: 'align',
		valign: 'valign',
		namest: 'namest',
		nameend: 'nameend',
		morerows: 'morerows',
		colsep: 'colsep',
		rowsep: 'rowsep'
	},
	columnAttributes: {
		align: 'align',
		name: 'colname',
		number: 'colnum',
		width: 'colwidth',
		colsep: 'colsep',
		rowsep: 'rowsep'
	},
	rowAttributes: {
		valign: 'valign',
		rowsep: 'rowsep'
	},
	tableAttributes: {
		align: 'align',
		cols: 'cols',
		colsep: 'colsep',
		rowsep: 'rowsep',
		frame: 'frame',
		rules: 'rules'
	}
}

HTML

{
    table: 'table',
    col: 'col',
    colgroup: 'colgroup',
    row: 'tr',
    cell: ['td', 'th'],
    body: 'tbody',
    foot: 'tfoot',
    head: 'thead',
    attributes: {
        align: 'align',
        valign: 'valign',
        colspan: 'colspan',
        rowspan: 'rowspan',
        background: 'bgcolor'
    },
    columnAttributes: {
		align: 'align',
        valign: 'valign',
        width: 'width'
    },
    rowAttributes: {
        align: 'align',
        valign: 'valign'
    },
    tableAttributes: {
        align: 'align',
		valign: 'valign',
        border: 'border',
		frame: 'frame',
		rules: 'rules'
    }
}

API

The API for the plugin can be found here: table plugin API