Merge pull request #9384 from ckeditor/i/9085-table-caption-docs

Docs (table): Added caption documentation and demo. Closes #9085.
ckeditor · Apr 26, 2021 · fb8c775 · fb8c775
2 parents 3bf7aa7 + 522c293
commit fb8c775
Show file tree

Hide file tree

Showing 5 changed files with 157 additions and 14 deletions.
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
@@ -11,7 +11,7 @@ The {@link module:table/table~Table} feature offers table creation and editing t
 
 ### 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}
 
@@ -33,18 +33,13 @@ Put the caret anywhere inside the table and click the **"Table properties"** but
 
 ### Table caption
 
-The {@link module:table/tablecaption~TableCaption} plugin adds support for table captions:
+The {@link module:table/tablecaption~TableCaption} plugin adds support for table captions.
 
-```html
-<figure class="table">
-	<table>
-		<tr>
-			<td>...</td>
-		</tr>
-	</table>
-	<figcaption>A caption goes here...</figcaption>
-</figure>
-```
+{@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.
@@ -420,6 +415,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>
@@ -447,7 +446,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>
@@ -513,6 +512,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>