Browse Source

Added decorable method for checking if block toolbar is allowed + improved docs.

Oskar Wróbel 7 years ago
parent
commit
00bd334645
1 changed files with 60 additions and 4 deletions
  1. 60 4
      packages/ckeditor5-ui/src/toolbar/block/blocktoolbar.js

+ 60 - 4
packages/ckeditor5-ui/src/toolbar/block/blocktoolbar.js

@@ -26,6 +26,35 @@ import iconPilcrow from '../../../theme/icons/pilcrow.svg';
 /**
  * The block toolbar plugin.
  *
+ * This plugin provides button attached to the block of content where the selection is currently placed.
+ * After clicking on the button, dropdown with editor features defined through editor configuration appears.
+ *
+ * By default button is allowed to be displayed next to {@link module:paragraph/paragraph~Paragraph paragraph element},
+ * {@link module:list/list~List list items} and all items defined in {@link module:heading/heading~Heading} plugin.
+ * This behavior can be customise through decorable {@link #checkAllowed} method.
+ *
+ * By default button will be attached to the left bound of the
+ * {@link module:ui/editorui/editoruiview~EditorUIView#editableElement} so editor integration should
+ * ensure that there is enough space between the editor content and left bound of the editable element
+ *
+ * 		| __
+ * 		||  |     This is a block of content that
+ * 		| ¯¯      button is attached to. This is a
+ * 		|  space  block of content that button is
+ * 		| <-----> attached to.
+ *
+ * The position of the button can be adjusted using css transform:
+ *
+ * 		.ck-block-toolbar-button {
+ * 			transform: translate( 10px, 10px );
+ * 		}
+ *
+ * 		|
+ * 		|   __    This is a block of content that
+ * 		|  |  |   button is attached to. This is a
+ * 		|   ¯¯    block of content that button is
+ * 		|         attached to.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class BlockToolbar extends Plugin {
@@ -90,6 +119,10 @@ export default class BlockToolbar extends Plugin {
 			}
 		} );
 
+		// Checking if button is allowed for displaying next to given element is event–driven.
+		// It is possible to override #checkAllowed method and apply custom validation.
+		this.decorate( 'checkAllowed' );
+
 		// Enable as default.
 		this._enable();
 	}
@@ -191,6 +224,31 @@ export default class BlockToolbar extends Plugin {
 		return elements;
 	}
 
+	/**
+	 * Checks if block button is allowed for displaying next to given element.
+	 *
+	 * Fires {@link #event:checkAllowed} event which can be handled and overridden to apply custom validation.
+	 *
+	 * Example how to disallow button for `h1` element:
+	 *
+	 * 		const blockToolbar = editor.plugins.get( 'BlockToolbar' );
+	 *
+	 * 		blockToolbar.on( 'checkAllowed', ( evt, args ) => {
+	 *			const viewElement = args[ 0 ];
+	 *
+	 *			if ( viewElement.name === 'h1' ) {
+	 *				evt.return = false;
+	 *			}
+	 * 		}, { priority: 'high' } );
+	 *
+	 * @fires checkAllowed
+	 * @param {module:engine/view/containerelement~ContainerElement} viewElement Container element where selection is.
+	 * @returns {Boolean} `true` when block button is allowed to display `false` otherwise.
+	 */
+	checkAllowed( viewElement ) {
+		return this._allowedElements.includes( viewElement.name );
+	}
+
 	/**
 	 * Starts displaying button next to allowed elements.
 	 *
@@ -213,10 +271,8 @@ export default class BlockToolbar extends Plugin {
 			// Get selection parent container, block button will be attached to this element.
 			targetElement = getParentContainer( viewDocument.selection.getFirstPosition() );
 
-			const targetName = targetElement.name;
-
-			// Do not attach block button when target element is not on the white list.
-			if ( !this._allowedElements.includes( targetName ) ) {
+			// Do not attach block button when is not allowed for given target element.
+			if ( !this.checkAllowed( targetElement ) ) {
 				this.buttonView.isVisible = false;
 
 				return;