Browse Source

Docs: Added a section about configuring color palettes in the table styling tools.

Aleksander Nowodzinski 5 years ago
parent
commit
34fc74d166

+ 40 - 0
packages/ckeditor5-table/docs/_snippets/features/table-styling-colors.html

@@ -0,0 +1,40 @@
+<div id="snippet-table-styling-colors">
+	<h3>A beautiful color palette</h3>
+	<figure class="table">
+		<table>
+			<tbody>
+				<tr>
+					<td style="width:120px;background-color:hsl(4,90%,58%)">Red</td>
+					<td style="width:120px;background-color:hsl(340,82%,52%)">Pink</td>
+					<td style="width:120px;background-color:hsl(291,64%,42%)">Purple</td>
+					<td style="width:120px;background-color:hsl(262,52%,47%)">Deep Purple</td>
+				</tr>
+				<tr>
+					<td style="width:120px;background-color:hsl(231,48%,48%)">Indigo</td>
+					<td style="width:120px;background-color:hsl(207,90%,54%)">Blue</td>
+					<td style="width:120px;background-color:hsl(199,98%,48%)">Light Blue</td>
+					<td style="width:120px;background-color:hsl(187,100%,42%)">Cyan</td>
+				</tr>
+				<tr>
+					<td style="width:120px;background-color:hsl(174,100%,29%)">Teal</td>
+					<td style="width:120px;background-color:hsl(122,39%,49%)">Green</td>
+					<td style="width:120px;background-color:hsl(88,50%,53%)">Light Green</td>
+					<td style="width:120px;background-color:hsl(66,70%,54%)">Lime</td>
+				</tr>
+				<tr>
+					<td style="width:120px;background-color:hsl(49,98%,60%)">Yellow</td>
+					<td style="width:120px;background-color:hsl(45,100%,51%)">Amber</td>
+					<td style="width:120px;background-color:hsl(36,100%,50%)">Orange</td>
+					<td style="width:120px;background-color:hsl(14,91%,54%)">Deep Orange</td>
+				</tr>
+				<tr>
+					<td style="width:120px;background-color:hsl(15,25%,34%)">Brown</td>
+					<td style="width:120px;background-color:hsl(0,0%,62%)">Grey</td>
+					<td style="width:120px;background-color:hsl(200,18%,46%)">Blue Grey</td>
+					<td style="width:120px;background-color:hsl(200,18%,100%)">White</td>
+				</tr>
+			</tbody>
+		</table>
+	</figure>
+</div>
+

+ 123 - 0
packages/ckeditor5-table/docs/_snippets/features/table-styling-colors.js

@@ -0,0 +1,123 @@
+/**
+ * @license Copyright (c) 2003-2020, 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 */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+const customColorPalette = [
+	{
+		color: 'hsl(4, 90%, 58%)',
+		label: 'Red'
+	},
+	{
+		color: 'hsl(340, 82%, 52%)',
+		label: 'Pink'
+	},
+	{
+		color: 'hsl(291, 64%, 42%)',
+		label: 'Purple'
+	},
+	{
+		color: 'hsl(262, 52%, 47%)',
+		label: 'Deep Purple'
+	},
+	{
+		color: 'hsl(231, 48%, 48%)',
+		label: 'Indigo'
+	},
+	{
+		color: 'hsl(207, 90%, 54%)',
+		label: 'Blue'
+	},
+	{
+		color: 'hsl(199, 98%, 48%)',
+		label: 'Light Blue'
+	},
+	{
+		color: 'hsl(187, 100%, 42%)',
+		label: 'Cyan'
+	},
+	{
+		color: 'hsl(174, 100%, 29%)',
+		label: 'Teal'
+	},
+	{
+		color: 'hsl(122, 39%, 49%)',
+		label: 'Green'
+	},
+	{
+		color: 'hsl(88, 50%, 53%)',
+		label: 'Light Green'
+	},
+	{
+		color: 'hsl(66, 70%, 54%)',
+		label: 'Lime'
+	},
+	{
+		color: 'hsl(49, 98%, 60%)',
+		label: 'Yellow'
+	},
+	{
+		color: 'hsl(45, 100%, 51%)',
+		label: 'Amber'
+	},
+	{
+		color: 'hsl(36, 100%, 50%)',
+		label: 'Orange'
+	},
+	{
+		color: 'hsl(14, 91%, 54%)',
+		label: 'Deep Orange'
+	},
+	{
+		color: 'hsl(15, 25%, 34%)',
+		label: 'Brown'
+	},
+	{
+		color: 'hsl(0, 0%, 62%)',
+		label: 'Grey'
+	},
+	{
+		color: 'hsl(200, 18%, 46%)',
+		label: 'Blue Grey'
+	},
+	{
+		color: 'hsl(200, 18%, 100%)',
+		label: 'White'
+	},
+];
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-table-styling-colors' ), {
+		extraPlugins: [
+			CKEditorPlugins.TableProperties,
+			CKEditorPlugins.TableCellProperties,
+		],
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'insertTable', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		table: {
+			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties', 'tableCellProperties' ],
+			tableProperties: {
+				borderColors: customColorPalette,
+				backgroundColors: customColorPalette
+			},
+			tableCellProperties: {
+				borderColors: customColorPalette,
+				backgroundColors: customColorPalette
+			}
+		}
+	} )
+	.then( editor => {
+		window.editorStyling = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 98 - 2
packages/ckeditor5-table/docs/features/table.md

@@ -23,7 +23,7 @@ In addition to the default table features described in the [previous section](#b
 
 {@snippet features/table-styling}
 
-Put the caret anywhere inside the table and click the **"Table properties"** button in the toolbar to open a pop–up with multiple options that will allow you to shape the look of the entire table to your needs. If you click the **"Cell properties"** button, a similar interface will appear but for individual table cells.
+Put the caret anywhere inside the table and click the **"Table properties"** button in the toolbar to open a pop–up with multiple options that will allow you to shape the look of the entire table to your needs. If you click the **"Cell properties"** button, a similar interface will appear but for individual table cells. [Learn more](#configuring-background-and-border-colors) about configuring color palettes in the table styling pop–up interfaces.
 
 <info-box>
 	By default, table styling tools are not included in {@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.
@@ -85,17 +85,113 @@ ClassicEditor
 			contentToolbar: [
 				'tableColumn', 'tableRow', 'mergeTableCells',
 				'tableProperties', 'tableCellProperties'
-			]
+			],
+
+			// Configuration of the TableProperties plugin.
+			tableProperties: {
+				// ...
+			},
+
+			// Configuration of the TableCellProperties plugin.
+			tableCellProperties: {
+				// ...
+			}
 		}
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
+[Learn more](#configuring-background-and-border-colors) about configuring color palettes in the table and table cell properties pop–ups.
+
 <info-box info>
 	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 </info-box>
 
+## Configuring background and border colors
+
+<info-box>
+	By default, table styling tools are not included in {@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 and cell styling tools allow users to create tables with colorful backgrounds and borders. These colors can be easily picked using color palettes in **"Table properties"** and **"Cell properties"** pop–ups. To help users choose the right colors for the content, the color palettes can be pre–configured, like in the editor below:
+
+{@snippet features/table-styling-colors}
+
+With the selection inside any table cell, use the **"Table properties"** and **"Cell properties"** buttons in the toolbar to inspect available styling and color options.
+
+### Customizing color palettes
+
+You can use these specific configuration options to define customized color palettes for background and border colors to match your document:
+
+* {@link module:table/table~TableConfig#tableProperties `config.tableProperties.borderColors`} — defines the color palette for table borders,
+* {@link module:table/table~TableConfig#tableProperties `config.tableProperties.backgroundColors`} — defines the color palette for table backgrounds,
+* {@link module:table/table~TableConfig#tableCellProperties `config.tableCellProperties.borderColors`} — defines the color palette for cell borders,
+* {@link module:table/table~TableConfig#tableCellProperties `config.tableCellProperties.backgroundColors`} – defines the color palette for cell backgrounds.
+
+<info-box>
+	The above configurations **do not** impact the {@link builds/guides/integration/basic-api#setting-the-editor-data data loaded into the editor}, i.e. they do not limit or filter the colors in the data. They are used only in the user interface allowing users to pick colors in a more convenient way.
+</info-box>
+
+For instance, to the define the same color palette for all border and background configurations, use the following code snippet:
+
+```js
+const customColorPalette = [
+	{
+		color: 'hsl(4, 90%, 58%)',
+		label: 'Red'
+	},
+	{
+		color: 'hsl(340, 82%, 52%)',
+		label: 'Pink'
+	},
+	{
+		color: 'hsl(291, 64%, 42%)',
+		label: 'Purple'
+	},
+	{
+		color: 'hsl(262, 52%, 47%)',
+		label: 'Deep Purple'
+	},
+	{
+		color: 'hsl(231, 48%, 48%)',
+		label: 'Indigo'
+	},
+	{
+		color: 'hsl(207, 90%, 54%)',
+		label: 'Blue'
+	},
+
+	// ...
+];
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Table, TableToolbar, TableProperties, TableCellProperties, Bold, ... ],
+		toolbar: [ 'insertTable', ... ],
+		table: {
+			contentToolbar: [
+				'tableColumn', 'tableRow', 'mergeTableCells',
+				'tableProperties', 'tableCellProperties'
+			],
+
+			// Set the palettes for tables.
+			tableProperties: {
+				borderColors: customColorPalette,
+				backgroundColors: customColorPalette
+			},
+
+			// Set the palettes for table cells.
+			tableCellProperties: {
+				borderColors: customColorPalette,
+				backgroundColors: customColorPalette
+			}
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
 ## 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 content is considered "inline" and the paragraph is not rendered.

+ 1 - 1
packages/ckeditor5-table/src/tablecellproperties.js

@@ -61,7 +61,7 @@ export default class TableCellProperties extends Plugin {
  *			}
  *		};
  *
- * **Note**: The configurations do not impact the data being loaded into the editor,
+ * **Note**: The configurations do not impact the data loaded into the editor,
  * i.e. they do not limit or filter the colors in the data. They are used only in the user interface
  * allowing users to pick colors in a more convenient way.
  *

+ 1 - 1
packages/ckeditor5-table/src/tableproperties.js

@@ -62,7 +62,7 @@ export default class TableProperties extends Plugin {
  *			}
  *		};
  *
- * **Note**: The configurations do not impact the data being loaded into the editor,
+ * **Note**: The configurations do not impact the data loaded into the editor,
  * i.e. they do not limit or filter the colors in the data. They are used only in the user interface
  * allowing users to pick colors in a more convenient way.
  *