Merge pull request #9242 from ckeditor/i/3204-table-caption

Feature (table): Added support for table captions. Closes #3204.
ckeditor · May 7, 2021 · b542721 · b542721
2 parents 5a9fe1b + 43f07af
commit b542721
Show file tree

Hide file tree

Showing 51 changed files with 3,077 additions and 203 deletions.
diff --git a/packages/ckeditor5-image/src/imagecaption/imagecaptionediting.js b/packages/ckeditor5-image/src/imagecaption/imagecaptionediting.js
@@ -47,11 +47,17 @@ export default class ImageCaptionEditing extends Plugin {
 		 */
 
 		// Schema configuration.
-		schema.register( 'caption', {
-			allowIn: 'image',
-			allowContentOf: '$block',
-			isLimit: true
-		} );
+		if ( !schema.isRegistered( 'caption' ) ) {
+			schema.register( 'caption', {
+				allowIn: 'image',
+				allowContentOf: '$block',
+				isLimit: true
+			} );
+		} else {
+			schema.extend( 'caption', {
+				allowIn: 'image'
+			} );
+		}
 
 		// Add caption element to each image inserted without it.
 		editor.model.document.registerPostFixer( writer => this._insertMissingModelCaptionElement( writer ) );

diff --git a/packages/ckeditor5-image/tests/imagecaption/imagecaptionediting.js b/packages/ckeditor5-image/tests/imagecaption/imagecaptionediting.js
@@ -9,6 +9,7 @@ import ImageCaptionEditing from '../../src/imagecaption/imagecaptionediting';
 import ImageEditing from '../../src/image/imageediting';
 import UndoEditing from '@ckeditor/ckeditor5-undo/src/undoediting';
 import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
+import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 
 import { getData as getModelData, setData as setModelData } from '@ckeditor/ckeditor5-engine/src/dev-utils/model';
 import { getData as getViewData } from '@ckeditor/ckeditor5-engine/src/dev-utils/view';
@@ -18,6 +19,34 @@ import testUtils from '@ckeditor/ckeditor5-core/tests/_utils/utils';
 describe( 'ImageCaptionEditing', () => {
 	let editor, model, doc, view;
 
+	// FakePlugin helps check if the plugin under test extends existing schema correctly.
+	class FakePlugin extends Plugin {
+		init() {
+			const schema = this.editor.model.schema;
+			const conversion = this.editor.conversion;
+
+			schema.register( 'foo', {
+				isObject: true,
+				isBlock: true,
+				allowWhere: '$block'
+			} );
+			schema.register( 'caption', {
+				allowIn: 'foo',
+				allowContentOf: '$block',
+				isLimit: true
+			} );
+
+			conversion.elementToElement( {
+				view: 'foo',
+				model: 'foo'
+			} );
+			conversion.elementToElement( {
+				view: 'caption',
+				model: 'caption'
+			} );
+		}
+	}
+
 	testUtils.createSinonSandbox();
 
 	beforeEach( () => {
@@ -61,6 +90,17 @@ describe( 'ImageCaptionEditing', () => {
 		expect( model.schema.checkAttribute( [ '$root', 'image', 'caption' ], 'alignment' ) ).to.be.false;
 	} );
 
+	it( 'should extend caption if schema for it is already registered', async () => {
+		const { model } = await VirtualTestEditor
+			.create( {
+				plugins: [ FakePlugin, ImageCaptionEditing, ImageEditing, UndoEditing, Paragraph ]
+			} );
+
+		expect( model.schema.isRegistered( 'caption' ) ).to.be.true;
+		expect( model.schema.isLimit( 'caption' ) ).to.be.true;
+		expect( model.schema.checkChild( [ 'image' ], 'caption' ) ).to.be.true;
+	} );
+
 	describe( 'data pipeline', () => {
 		describe( 'view to model', () => {
 			it( 'should convert figcaption inside image figure', () => {

diff --git a/packages/ckeditor5-table/docs/_snippets/features/build-table-source.js b/packages/ckeditor5-table/docs/_snippets/features/build-table-source.js
@@ -13,6 +13,8 @@ import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment';
 import IndentBlock from '@ckeditor/ckeditor5-indent/src/indentblock';
 import TableProperties from '@ckeditor/ckeditor5-table/src/tableproperties';
 import TableCellProperties from '@ckeditor/ckeditor5-table/src/tablecellproperties';
+import TableCaption from '@ckeditor/ckeditor5-table/src/tablecaption';
+import Superscript from '@ckeditor/ckeditor5-basic-styles/src/superscript';
 
 import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
 
@@ -45,5 +47,7 @@ ClassicEditor.defaultConfig = {
 window.ClassicEditor = ClassicEditor;
 window.CKEditorPlugins = {
 	TableProperties,
-	TableCellProperties
+	TableCellProperties,
+	TableCaption,
+	Superscript
 };
diff --git a/packages/ckeditor5-table/docs/_snippets/features/table-caption.html b/packages/ckeditor5-table/docs/_snippets/features/table-caption.html
@@ -0,0 +1,104 @@
+<div id="snippet-table-caption">
+	<figure class="table">
+		<table>
+			<thead>
+				<tr>
+					<th>Name</th>
+					<th>Mass (10<sup>24</sup>kg)</th>
+					<th>Diameter (km)</th>
+					<th>Gravity (m/s<sup>2</sup>)</th>
+					<th>Length of day (hours)</th>
+					<th>Distance from Sun (10<sup>6</sup>km)</th>
+					<th>Mean temperature (°C)</th>
+				</tr>
+			</thead>
+			<tbody>
+				<tr>
+					<th>Mercury</th>
+					<td>0.330</td>
+					<td>4,879</td>
+					<td>3.7</td>
+					<td>4222.6</td>
+					<td>57.9</td>
+					<td>167</td>
+				</tr>
+				<tr>
+					<th>Venus</th>
+					<td>4.87</td>
+					<td>12,104</td>
+					<td>8.9</td>
+					<td>2802.0</td>
+					<td>108.2</td>
+					<td>464</td>
+				</tr>
+				<tr>
+					<th>Earth</th>
+					<td>5.97</td>
+					<td>12,756</td>
+					<td>9.8</td>
+					<td>24.0</td>
+					<td>149.6</td>
+					<td>15</td>
+				</tr>
+				<tr>
+					<th>Mars</th>
+					<td>0.642</td>
+					<td>6,792</td>
+					<td>3.7</td>
+					<td>24.7</td>
+					<td>227.9</td>
+					<td>-65</td>
+				</tr>
+				<tr>
+					<th>Jupiter</th>
+					<td>1898</td>
+					<td>142,984</td>
+					<td>23.1</td>
+					<td>9.9</td>
+					<td>778.6</td>
+					<td>-110</td>
+				</tr>
+				<tr>
+					<th>Saturn</th>
+					<td>568</td>
+					<td>120,536</td>
+					<td>9.0</td>
+					<td>10.7</td>
+					<td>1433.5</td>
+					<td>-140</td>
+				</tr>
+				<tr>
+					<th>Uranus</th>
+					<td>86.8</td>
+					<td>51,118</td>
+					<td>8.7</td>
+					<td>17.2</td>
+					<td>2872.5</td>
+					<td>-195</td>
+				</tr>
+				<tr>
+					<th>Neptune</th>
+					<td>102</td>
+					<td>49,528</td>
+					<td>11.0</td>
+					<td>16.1</td>
+					<td>4495.1</td>
+					<td>-200</td>
+				</tr>
+				<tr>
+					<th>Pluto</th>
+					<td>0.0146</td>
+					<td>2,370</td>
+					<td>0.7</td>
+					<td>153.3</td>
+					<td>5906.4</td>
+					<td>-225</td>
+				</tr>
+			</tbody>
+		</table>
+		<figcaption>
+			Data about the planets of our solar system (Planetary facts taken from
+			<a href="http://nssdc.gsfc.nasa.gov/planetary/factsheet/">Nasa's Planetary Fact Sheet - Metric</a>).
+		</figcaption>
+	</figure>
+</div>
diff --git a/packages/ckeditor5-table/docs/_snippets/features/table-caption.js b/packages/ckeditor5-table/docs/_snippets/features/table-caption.js
@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, CKEditorPlugins, console, window, document */
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-table-caption' ), {
+		extraPlugins: [
+			CKEditorPlugins.TableCaption, CKEditorPlugins.Superscript
+		],
+		table: {
+			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'toggleTableCaption' ]
+		},
+		image: {
+			toolbar: [
+				'imageStyle:full',
+				'imageStyle:side',
+				'|',
+				'imageTextAlternative'
+			]
+		}
+	} )
+	.then( editor => {
+		window.editorCaption = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/packages/ckeditor5-table/docs/api/table.md b/packages/ckeditor5-table/docs/api/table.md
@@ -19,6 +19,7 @@ See the {@link features/table Table feature} guide and the documentation for the
 * {@link module:table/table~Table}
 * {@link module:table/tabletoolbar~TableToolbar}
 * {@link module:table/tableproperties~TableProperties}
+* {@link module:table/tablecaption~TableCaption}
 * {@link module:table/tablecellproperties~TableCellProperties}
 * {@link module:table/tableselection~TableSelection}
 * {@link module:table/tableclipboard~TableClipboard}

diff --git a/packages/ckeditor5-table/docs/features/table.md b/packages/ckeditor5-table/docs/features/table.md
@@ -15,7 +15,7 @@ CKEditor 5 offers all necessary functionality to produce advanced, visually appe
 
 ### Basic table features
 
-The editor bellow shows the basic set of table features focusing on the **structure and semantics**. These features allow users to insert new tables into the content, add or remove columns and rows, define headers, and merge multiple cells. It is also worth noting that you will find them out–of–the–box in all {@link builds/guides/overview ready–to–use editor builds}.
+The editor bellow shows the basic set of table features focusing on the **structure and semantics**. These features allow users to insert new tables into the content, add or remove columns and rows, define headers, add caption, and merge multiple cells. It is also worth noting that you will find them out–of–the–box in all {@link builds/guides/overview ready–to–use editor builds}.
 
 {@snippet features/table}
 
@@ -35,6 +35,20 @@ Put the caret anywhere inside the table and click the **"Table properties"** but
 	By default, table styling tools are not included in the {@link builds/guides/overview ready–to–use editor builds} and must be installed separately. See the [installation](#table-and-cell-styling-tools-2) section to learn how to enable them in your editor.
 </info-box>
 
+### Table caption
+
+The {@link module:table/tablecaption~TableCaption} plugin adds support for table captions.
+
+{@snippet features/table-caption}
+
+<info-box>
+	By default, table caption feature is not included in the {@link builds/guides/overview ready–to–use editor builds} and must be installed separately. See the [installation](#table-caption-2) section to learn how to enable it in your editor.
+</info-box>
+
+<info-box hint>
+	By default, the table caption is placed above the table. You can change the placement by setting [`caption-side`](https://developer.mozilla.org/en-US/docs/Web/CSS/caption-side) in your {@link builds/guides/integration/content-styles content styles} for the `.ck-content .table > figcaption` style. Changing it to `caption-side: bottom` will display the caption below the table.
+</info-box>
+
 ### Nesting tables
 
 Starting from version 27.1.0 CKEditor 5 allows nesting tables inside other table's cells. This may be used for creating advanced charts or layouts based on tables. The nested table can be formatted just like a regular one.
@@ -137,6 +151,39 @@ ClassicEditor
 	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 </info-box>
 
+### Table caption
+
+To enable table caption feature in your editor, install the [`@ckeditor/ckeditor5-table`](https://www.npmjs.com/package/@ckeditor/ckeditor5-table) package:
+
+```
+npm install --save @ckeditor/ckeditor5-table
+```
+
+Then add the `Table`, `TableToolbar`, and **`TableCaption`** plugins to your plugin list and configure the table toolbar:
+
+```js
+import Table from '@ckeditor/ckeditor5-table/src/table';
+import TableToolbar from '@ckeditor/ckeditor5-table/src/tabletoolbar';
+import TableCaption from '@ckeditor/ckeditor5-table/src/tablecaption';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Table, TableToolbar, TableCaption, Bold, ... ],
+		toolbar: [ 'insertTable', ... ],
+		table: {
+			contentToolbar: [
+				'toggleTableCaption'
+			]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
 ## Configuring styling tools
 
 <info-box>
@@ -460,6 +507,10 @@ The table plugins register the following UI components:
 			<td>The <code>'tableProperties'</code> button</td>
 			<td>{@link module:table/tableproperties~TableProperties}</td>
 		</tr>
+		<tr>
+			<td>The <code>'toggleTableCaption'</code> button</td>
+			<td>{@link module:table/tablecaption~TableCaption}</td>
+		</tr>
 		<tr>
 			<td>The <code>'tableCellProperties'</code> button</td>
 			<td>{@link module:table/tablecellproperties~TableCellProperties}</td>
@@ -487,7 +538,7 @@ The {@link module:table/tabletoolbar~TableToolbar} plugin introduces two balloon
 		<tr>
 			<td><code>'insertTable'</code></td>
 			<td>{@link module:table/commands/inserttablecommand~InsertTableCommand}</td>
-			<td rowspan="15">{@link module:table/table~Table}</td>
+			<td rowspan="17">{@link module:table/table~Table}</td>
 		</tr>
 		<tr>
 			<td><code>'insertTableColumnLeft'</code></td>
@@ -553,6 +604,11 @@ The {@link module:table/tabletoolbar~TableToolbar} plugin introduces two balloon
 			<td><code>'splitTableCellHorizontally'</code></td>
 			<td>{@link module:table/commands/splitcellcommand~SplitCellCommand}</td>
 		</tr>
+		<tr>
+			<td><code>'toggleTableCaption'</code></td>
+			<td>{@link module:table/tablecaption/toggletablecaptioncommand~ToggleTableCaptionCommand}</td>
+			<td>{@link module:table/tablecaption~TableCaption}</td>
+		</tr>
 		<tr>
 			<td><code>'tableBorderColor'</code></td>
 			<td>{@link module:table/tableproperties/commands/tablebordercolorcommand~TableBorderColorCommand}</td>

diff --git a/packages/ckeditor5-table/lang/contexts.json b/packages/ckeditor5-table/lang/contexts.json
@@ -56,5 +56,7 @@
 	"Align table to the right": "The label used by assistive technologies describing a button that aligns the table to the right.",
 	"The color is invalid. Try \"#FF0000\" or \"rgb(255,0,0)\" or \"red\".": "The localized error string that can be displayed next to color (background, border) fields that have an invalid value",
 	"The value is invalid. Try \"10px\" or \"2em\" or simply \"2\".": "The localized error string that can be displayed next to length (padding, border width) fields that have an invalid value.",
-	"Color picker": "The label used by assistive technologies describing a button that opens a color picker, where user can choose a configured color for a certain properties (eg.: background color, color, border-color etc.)."
+	"Color picker": "The label used by assistive technologies describing a button that opens a color picker, where user can choose a configured color for a certain properties (eg.: background color, color, border-color etc.).",
+	"Toggle caption off": "The button label for the table toolbar hiding caption attached to the table.",
+	"Toggle caption on": "The button label for the table toolbar showing caption attached to the table."
 }
diff --git a/packages/ckeditor5-table/src/commands/insertcolumncommand.js b/packages/ckeditor5-table/src/commands/insertcolumncommand.js
@@ -52,10 +52,9 @@ export default class InsertColumnCommand extends Command {
 	 */
 	refresh() {
 		const selection = this.editor.model.document.selection;
+		const isAnyCellSelected = !!getSelectionAffectedTableCells( selection ).length;
 
-		const tableParent = selection.getFirstPosition().findAncestor( 'table' );
-
-		this.isEnabled = !!tableParent;
+		this.isEnabled = isAnyCellSelected;
 	}
 
 	/**

diff --git a/packages/ckeditor5-table/src/commands/insertrowcommand.js b/packages/ckeditor5-table/src/commands/insertrowcommand.js
@@ -52,10 +52,9 @@ export default class InsertRowCommand extends Command {
 	 */
 	refresh() {
 		const selection = this.editor.model.document.selection;
+		const isAnyCellSelected = !!getSelectionAffectedTableCells( selection ).length;
 
-		const tableParent = selection.getFirstPosition().findAncestor( 'table' );
-
-		this.isEnabled = !!tableParent;
+		this.isEnabled = isAnyCellSelected;
 	}
 
 	/**