浏览代码

Docs: Add section about block vs inline content to the table feature documentation.

Maciej Gołaszewski 7 年之前
父节点
当前提交
5d23c0058d
共有 1 个文件被更改,包括 91 次插入0 次删除
  1. 91 0
      packages/ckeditor5-table/docs/features/table.md

+ 91 - 0
packages/ckeditor5-table/docs/features/table.md

@@ -70,6 +70,97 @@ And the following commands:
 
 The {@link module:table/tabletoolbar~TableToolbar} plugin introduces the balloon toolbar for tables. The toolbar shows up when a table cell is selected and is anchored to the table. It is possible to {@link module:table/table~TableConfig#toolbar configure} its content. Normally, it contains the table-related tools such as `'tableColumn'`, `'tableRow'`, and `'mergeTableCells'` dropdowns.
 
+## Block vs inline content in table cells
+
+The table feature supports block content - like paragraphs, lists, headings, etc - in table cells. The table cells in the model will always have at least one block. For empty table cell it will be empty `<paragraph>`. Such table cells (with single `<pargraph>`) are considered as cells with inline content only.
+
+<info-box info>
+	The table might consist table cells of both types.
+</info-box>
+
+### Inline content
+
+A table cell with inline content (single `<paragraph>`) will be rendered (ie. when using {@link module:core/editor/editor~Editor#getData()} directly in the `<td>` or `<th>` element without wrapping in `<p>`. A table with only inline content in table cells is considered a data table used to present tabular data. Such tables are ususally used with short content and additional paragraphs are often redundant.
+
+Example table with inline content (model representation):
+
+```html
+<table>
+	<tableRow>
+		<tableCell>
+			<paragraph>Foo <$text bold="true">Bar</$text></paragraph>
+		</tableCell>
+		<tableCell>
+			<paragraph></paragraph>
+		</tableCell>
+	</tableRow>
+</table>
+```
+will be rendered as:
+
+```html
+<figure class="table">
+	<table>
+		<tbody>
+			<tr>
+				<td>Foo <strong>Bar</strong></td>
+				<td></td>
+			</tr>
+		</tbody>
+	</table>
+</figure>
+```
+
+### Block content
+
+Blocks other then `<paragraph>`, even if being single, will be always rendered in the view. If there are other blocks in table cells the `<paragraph>` will be rendered as `<p>`. A single `<pargraph>` might be also rendered to the View when it has attributes.
+
+Example table with block content (model representation):
+
+```html
+<table>
+	<tableRow>
+		<tableCell>
+			<paragraph>Foo</paragraph>
+			<paragraph><$text bold="true">Bar</$text></paragraph>
+		</tableCell>
+		<tableCell>
+			<heading1>Some title</heading1>
+		</tableCell>
+		<tableCell>
+			<paragraph textAlign="right">Baz</paragraph>
+		</tableCell>
+	</tableRow>
+</table>
+```
+will be rendered as:
+
+```html
+<figure class="table">
+	<table>
+		<tbody>
+			<tr>
+				<td>
+					<p>Foo</p>
+					<p><strong>Bar</strong></p>
+				</td>
+				<td>
+					<h2>Some title</h2>
+				</td>
+				<td>
+					<p style="text-align:right;">Baz</p>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+</figure>
+```
+
+<info-box info>
+	At the moment the block content in table feature is not configurable. It means that you cannot enforce inline content in table cells. Right now we're [discussing it on github](https://github.com/ckeditor/ckeditor5-table/issues/101) as adding such configuration would intoduce complexity into the table editing feature.
+</info-box>
+
+
 ## Contribute
 
 The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-table.