8
0
Quellcode durchsuchen

Merge pull request #116 from ckeditor/t/114

Docs: Add section about block vs inline content to the table feature documentation: Closes #114.
Piotrek Koszuliński vor 7 Jahren
Ursprung
Commit
fa16ef8de4
1 geänderte Dateien mit 108 neuen und 0 gelöschten Zeilen
  1. 108 0
      packages/ckeditor5-table/docs/features/table.md

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

@@ -72,6 +72,114 @@ The {@link module:table/tabletoolbar~TableToolbar} plugin introduces two balloon
 * The content toolbar shows up when table cell is selected and is anchored to the table. It is possible to {@link module:table/table~TableConfig#contentToolbar configure} its content. Normally, it contains the table-related tools such as `'tableColumn'`, `'tableRow'`, and `'mergeTableCells'` dropdowns.
 * The table toolbar shows up when the whole table is selected, for instance using the widget handler. It is possible to {@link module:table/table~TableConfig#tableToolbar configure} its content.
 
+## Block vs inline content in table cells
+
+The table feature allows creating block content (like paragraphs, lists, headings, etc.) in table cells. However, if a table cell contains just one paragraph and this paragraph has no special attributes (like text alignment), this cell contents is considered "inline" and the paragraph is not rendered.
+
+This means that a table cell can be in two states – with an inline content or with a block content. The reason for this differentiation is that most tables contain only inline content (e.g. in the [demo](#demo) above) and it is common for "data tables" to not contain any block content. In such a scenario, printing out `<p>` elements would be semantically incorrect and also unnecessary. There are, however, scenarios where the user wants to create for example a list inside a table and then the support for block content is necessary too.
+
+<info-box>
+	When we talk about "rendering" we mean the view layer. In the model, a cell is always filled with at least a `<paragraph>`. The reasons for that are consistency (a cell always has a block content – text is never directly inside `<tableCell>`) and making features like the <kbd>Enter</kbd> support work out of the box (since a `<paragraph>` exists in the model it can be split, despite the fact that it is not present in the view).
+</info-box>
+
+### Inline content
+
+The model representation of table cells with an inline content only (a single `<paragraph>` inside):
+
+```html
+<table>
+	<tableRow>
+		<tableCell>
+			<paragraph>Foo</paragraph>
+		</tableCell>
+		<tableCell>
+			<paragraph>Bar</paragraph>
+		</tableCell>
+	</tableRow>
+</table>
+```
+
+The above model structure will be rendered to the {@link module:editor-classic/classiceditor~ClassicEditor#getData data} as:
+
+```html
+<figure class="table">
+	<table>
+		<tbody>
+			<tr>
+				<td>Foo</td>
+				<td>Bar</td>
+			</tr>
+		</tbody>
+	</table>
+</figure>
+```
+
+In the editing view (the editable container in which the user edits the content) additional `<span>` elements are create to compensate for the hidden `<paragraph>` elements:
+
+```html
+<figure class="table">
+	<table>
+		<tbody>
+			<tr>
+				<td><span>Foo</span></td>
+				<td><span>Bar</span></td>
+			</tr>
+		</tbody>
+	</table>
+</figure>
+```
+
+### Block content
+
+If a table cell contains anything else than a single `<paragraph>` with no attributes, all those block elements will be rendered.
+
+Example table with a block content (model representation):
+
+```html
+<table>
+	<tableRow>
+		<tableCell>
+			<paragraph>Foo</paragraph>
+			<paragraph>Bar</paragraph>
+		</tableCell>
+		<tableCell>
+			<heading1>Some title</heading1>
+		</tableCell>
+		<tableCell>
+			<paragraph textAlign="right">Baz</paragraph>
+		</tableCell>
+	</tableRow>
+</table>
+```
+
+The above model structure will be rendered to the data and to the editing view as:
+
+```html
+<figure class="table">
+	<table>
+		<tbody>
+			<tr>
+				<td>
+					<p>Foo</p>
+					<p>Bar</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 it is not possible to completely disallow block content in tables. See the [discussing on GitHub](https://github.com/ckeditor/ckeditor5-table/issues/101) about adding a configuration option that would enable that. 👍 if you need this feature.
+</info-box>
+
+
 ## Contribute
 
 The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-table.