Merge pull request #9610 from ckeditor/table-cell-default-properties

Feature (table): Support for the default table cell properties.

MINOR BREAKING CHANGE (table): Classes `TableCellHorizontalAlignmentCommand`, `TableCellVerticalAlignmentCommand`, `TableCellBackgroundColorCommand`, `TableCellBorderColorCommand`, `TableCellBorderStyleCommand`, `TableCellBorderWidthCommand`, `TableCellHeightCommand`, `TableCellPropertyCommand`, `TableCellWidthCommand`, `TableCellPaddingCommand` require the second argument called `defaultValue` which is the default value for the command.

MINOR BREAKING CHANGE (table): The `TableCellPropertiesView` class requires additional property in the object as the second constructor argument (`options.defaultTableCellProperties`).

MINOR BREAKING CHANGE (table): The `upcastBorderStyles()` conversion helper requires the third argument called `defaultBorder`. An object that defines default border (`width`, `color`, `style`) definitions.

packages/ckeditor5-table/docs/_snippets/features/table-default-properties.html

@@ -1,15 +1,21 @@
 <style id="table-default-properties-styles">
-    .table-default-properties-container .ck-content .table {
+    .live-snippet .table-default-properties-container .ck.ck-content .table {
         float: right;
         width: 500px;
         height: 250px;
     }
 
-    .table-default-properties-container .ck-content .table table {
+    .live-snippet .table-default-properties-container .ck.ck-content .table table {
         border-style: dashed;
         border-color: hsl(90, 75%, 60%);
         border-width: 3px;
     }
+
+    .live-snippet .table-default-properties-container .ck.ck-content .table table td {
+        text-align: center;
+        vertical-align: bottom;
+        padding: 10px
+    }
 </style>
 
 <div class="table-default-properties-container">

packages/ckeditor5-table/docs/_snippets/features/table-default-properties.js

@@ -22,6 +22,13 @@ ClassicEditor
 					width: '500px',
 					height: '250px'
 				}
+			},
+			tableCellProperties: {
+				defaultProperties: {
+					horizontalAlignment: 'center',
+					verticalAlignment: 'bottom',
+					padding: '10px'
+				}
 			}
 		},
 		image: {

packages/ckeditor5-table/docs/features/table.md

@@ -221,11 +221,11 @@ ClassicEditor
 	.catch( ... );
 ```
 
-### Default table styles
+### Default table and table cell styles
 
 The table styles feature allows for configuring the default look of the tables in the editor. The configuration object should be synchronized with the {@link builds/guides/integration/content-styles editor content styles}.
 
-The **“Table properties”** button in the toolbar will show the table properties applied to the table.
+The **“Table properties”**, and **“Table cell properties”** buttons in the toolbar will show the table and table cell properties applied to the table or table cells.
 
 The stylesheet for the editor displayed below looks as follows:
 
@@ -241,9 +241,18 @@ The stylesheet for the editor displayed below looks as follows:
     border-color: 'hsl(90, 75%, 60%)';
     border-width: 3px;
 }
+
+.ck-content .table table td {
+    text-align: center;
+    vertical-align: bottom;
+    padding: 10px
+}
 ```
 
-The same values must be passed to the editor configuration as the {@link module:table/tableproperties~TablePropertiesOptions `table.tableProperties.defaultProperties`} object:
+The same values must be passed to the editor configuration as:
+
+* the {@link module:table/tableproperties~TablePropertiesOptions `table.tableProperties.defaultProperties`} object for the table properties,
+* the {@link module:table/tablecellproperties~TableCellPropertiesOptions `table.tableCellProperties.defaultProperties`} object for the table cell properties.
 
 ```js
 const tableConfig = {
@@ -257,20 +266,32 @@ const tableConfig = {
 	            alignment: 'right',
 	            width: '500px',
 	            height: '250px'
-            }
+            },
+            // The default styles for table cells in the editor. They should be synchronized with the content styles.
+	        tableCellProperties: {
+		        defaultProperties: {
+			        horizontalAlignment: 'center',
+			        verticalAlignment: 'bottom',
+			        padding: '10px'
+		        }
+	        }
         }
     }
 };
 ```
 
-The table element should be aligned to the `right` side by default. Its size should be `500x250px`. Border style should be `dashed`, `3px` of its width, and the color specified as `“Light green”`. The same will be applied for new tables if they will be inserted into the editor
+The table element should be aligned to the `right` side by default. Its size should be `500x250px`. Border style should be `dashed`, `3px` of its width, and the color specified as `“Light green”`. 
+
+The content should be away about `10px` from the cell's edges (`padding`), vertically aligned to `bottom` and horizontally to `center`.
+
+The same will be applied for new tables and cells if they will be inserted into the editor.
 
 {@snippet features/table-default-properties}
 
-Read more about {@link module:table/tableproperties~TablePropertiesOptions all supported styles} for the table default properties feature.
+Read more about all supported properties for the {@link module:table/tableproperties~TablePropertiesOptions table}, and {@link module:table/tablecellproperties~TableCellPropertiesOptions table cells} features.
 
 <info-box>
-	The default table styles **do** impact the {@link builds/guides/integration/basic-api#setting-the-editor-data data loaded into the editor}. Default properties will not be kept in the editor model.
+	The default table, and table cell styles **do** impact the {@link builds/guides/integration/basic-api#setting-the-editor-data data loaded into the editor}. Default properties will not be kept in the editor model.
 </info-box>
 
 ## Block vs inline content in table cells

packages/ckeditor5-table/src/converters/tableproperties.js

@@ -47,12 +47,12 @@ export function upcastStyleToAttribute( conversion, options ) {
  *
  * @param {module:engine/conversion/conversion~Conversion} conversion
  * @param {String} viewElementName
- * @param {Object} [defaultBorder={}] The default border values.
+ * @param {Object} defaultBorder The default border values.
  * @param {String} defaultBorder.color The default `borderColor` value.
  * @param {String} defaultBorder.style The default `borderStyle` value.
  * @param {String} defaultBorder.width The default `borderWidth` value.
  */
-export function upcastBorderStyles( conversion, viewElementName, defaultBorder = {} ) {
+export function upcastBorderStyles( conversion, viewElementName, defaultBorder ) {
 	conversion.for( 'upcast' ).add( dispatcher => dispatcher.on( 'element:' + viewElementName, ( evt, data, conversionApi ) => {
 		// If the element was not converted by element-to-element converter,
 		// we should not try to convert the style. See #8393.

packages/ckeditor5-table/src/tablecellproperties.js

@@ -64,9 +64,24 @@ export default class TableCellProperties extends Plugin {
  *			}
  *		};
  *
- * **Note**: The configurations do not impact the data loaded into the editor,
+ * * The default styles for table cells (`tableCellProperties.defaultProperties`):
+ *
+ *		const tableConfig = {
+ *			tableCellProperties: {
+ *				defaultProperties: {
+ *					horizontalAlignment: 'right',
+ *					verticalAlignment: 'bottom',
+ *					padding: '5px'
+ *				}
+ *			}
+ *		}
+ *
+ * 	 {@link module:table/tableproperties~TablePropertiesOptions Read more about the supported properties.}
+ *
+ * **Note**: The `borderColors` and `backgroundColors` options 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.
+ * allowing users to pick colors in a more convenient way. The `defaultProperties` option does impact the data.
+ * Default values will not be kept in the editor model.
  *
  * The default color palettes for the cell background and the cell border are the same
  * ({@link module:table/utils/ui/table-properties~defaultColors check out their content}).
@@ -78,3 +93,28 @@ export default class TableCellProperties extends Plugin {
  *
  * @member {Object} module:table/table~TableConfig#tableCellProperties
  */
+
+/**
+ * The configuration of the table cell default properties feature.
+ *
+ * @typedef {Object} module:table/tablecellproperties~TableCellPropertiesOptions
+ *
+ * @property {String} width The default `width` of the table cell.
+ *
+ * @property {String} height The default `height` of the table cell.
+ *
+ * @property {String} padding The default `padding` of the table cell.
+ *
+ * @property {String} backgroundColor The default `background-color` of the table cell.
+ *
+ * @property {String} borderColor The default `border-color` of the table cell.
+ *
+ * @property {String} borderWidth The default `border-width` of the table cell.
+ *
+ * @property {String} [borderStyle='none'] The default `border-style` of the table cell.
+ *
+ * @property {String} [horizontalAlignment='center'] The default `horizontalAlignment` of the table cell.
+ *
+ * @property {String} [verticalAlignment='middle'] The default `verticalAlignment` of the table cell.
+ */
+

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellbackgroundcolorcommand.js

@@ -28,8 +28,9 @@ export default class TableCellBackgroundColorCommand extends TableCellPropertyCo
 	 * Creates a new `TableCellBackgroundColorCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'backgroundColor' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'backgroundColor', defaultValue );
 	}
 }

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellbordercolorcommand.js

@@ -29,9 +29,10 @@ export default class TableCellBorderColorCommand extends TableCellPropertyComman
 	 * Creates a new `TableCellBorderColorCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'borderColor' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'borderColor', defaultValue );
 	}
 
 	/**
@@ -42,6 +43,12 @@ export default class TableCellBorderColorCommand extends TableCellPropertyComman
 			return;
 		}
 
-		return getSingleValue( tableCell.getAttribute( this.attributeName ) );
+		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 }

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellborderstylecommand.js

@@ -29,9 +29,10 @@ export default class TableCellBorderStyleCommand extends TableCellPropertyComman
 	 * Creates a new `TableCellBorderStyleCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'borderStyle' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'borderStyle', defaultValue );
 	}
 
 	/**
@@ -42,6 +43,12 @@ export default class TableCellBorderStyleCommand extends TableCellPropertyComman
 			return;
 		}
 
-		return getSingleValue( tableCell.getAttribute( this.attributeName ) );
+		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 }

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellborderwidthcommand.js

@@ -37,9 +37,10 @@ export default class TableCellBorderWidthCommand extends TableCellPropertyComman
 	 * Creates a new `TableCellBorderWidthCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'borderWidth' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'borderWidth', defaultValue );
 	}
 
 	/**
@@ -50,13 +51,25 @@ export default class TableCellBorderWidthCommand extends TableCellPropertyComman
 			return;
 		}
 
-		return getSingleValue( tableCell.getAttribute( this.attributeName ) );
+		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 
 	/**
 	 * @inheritDoc
 	 */
 	_getValueToSet( value ) {
-		return addDefaultUnitToNumericValue( value, 'px' );
+		value = addDefaultUnitToNumericValue( value, 'px' );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 }

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellheightcommand.js

@@ -37,15 +37,22 @@ export default class TableCellHeightCommand extends TableCellPropertyCommand {
 	 * Creates a new `TableCellHeightCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'height' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'height', defaultValue );
 	}
 
 	/**
 	 * @inheritDoc
 	 */
 	_getValueToSet( value ) {
-		return addDefaultUnitToNumericValue( value, 'px' );
+		value = addDefaultUnitToNumericValue( value, 'px' );
+
+		if ( value === this._defaultValue ) {
+			return null;
+		}
+
+		return value;
 	}
 }

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellhorizontalalignmentcommand.js

@@ -28,8 +28,9 @@ export default class TableCellHorizontalAlignmentCommand extends TableCellProper
 	 * Creates a new `TableCellHorizontalAlignmentCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value for the "alignment" attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'horizontalAlignment' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'horizontalAlignment', defaultValue );
 	}
 }

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellpaddingcommand.js

@@ -37,9 +37,10 @@ export default class TableCellPaddingCommand extends TableCellPropertyCommand {
 	 * Creates a new `TableCellPaddingCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'padding' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'padding', defaultValue );
 	}
 
 	/**
@@ -50,13 +51,25 @@ export default class TableCellPaddingCommand extends TableCellPropertyCommand {
 			return;
 		}
 
-		return getSingleValue( tableCell.getAttribute( this.attributeName ) );
+		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 
 	/**
 	 * @inheritDoc
 	 */
 	_getValueToSet( value ) {
-		return addDefaultUnitToNumericValue( value, 'px' );
+		value = addDefaultUnitToNumericValue( value, 'px' );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 }