From 1b2f4666a62f258bf0920007fa14152effd8c526 Mon Sep 17 00:00:00 2001 From: Kamil Piechaczek Date: Thu, 30 Jul 2020 15:18:05 +0200 Subject: [PATCH] Docs: Edited and amended: API docs; plugin disabling instructions. --- packages/ckeditor5-widget/docs/api/widget.md | 12 +- .../guides/deep-dive/widget-internals.md | 40 +++--- .../src/widgettypearound/utils.js | 16 +-- .../src/widgettypearound/widgettypearound.js | 114 +++++++++--------- 4 files changed, 91 insertions(+), 91 deletions(-) diff --git a/packages/ckeditor5-widget/docs/api/widget.md b/packages/ckeditor5-widget/docs/api/widget.md index b4e8a057d2f..89e52de208b 100644 --- a/packages/ckeditor5-widget/docs/api/widget.md +++ b/packages/ckeditor5-widget/docs/api/widget.md @@ -16,21 +16,21 @@ Browse the API documentation of this package by using the module tree on the lef The widget API consists of two layers: -* The {@link module:widget/widget~Widget} plugin which enables base support for this feature. Usually, your plugin which implements a specific widget will define its reliance on the `Widget` plugin via its {@link module:core/plugin~Plugin.requires `Plugin.requires`} property. -* The {@link module:widget/utils~toWidget `toWidget()`} {@link module:widget/utils~toWidgetEditable `toWidgetEditable()`} functions which need to be used during the conversion in order to make a specific element either a widget or a widget's nested editable. See their documentation for more details. +* The {@link module:widget/widget~Widget} plugin that enables base support for this feature. Usually, your plugin which implements a specific widget will define its reliance on the `Widget` plugin via its {@link module:core/plugin~Plugin.requires `Plugin.requires`} property. +* The {@link module:widget/utils~toWidget `toWidget()`} and {@link module:widget/utils~toWidgetEditable `toWidgetEditable()`} functions that need to be used during the conversion in order to make a specific element either a widget or a widget's nested editable. See their documentation for more details. -Besides the above mentioned core functionalities, this package implements the following utils: +Besides the above mentioned core functionalities, this package implements the following utilities: * The {@link module:widget/widgettoolbarrepository~WidgetToolbarRepository `WidgetToolbarRepository`} plugin which exposes a nice API for registering widget toolbars. -* A couple of helper functions for managing widgets in the {@link module:widget/utils `@ckeditor/ckeditor5-widget/utils`} module. +* A few helper functions for managing widgets in the {@link module:widget/utils `@ckeditor/ckeditor5-widget/utils`} module. - The widget API is proposed in a very different way than it was in CKEditor 4. It is just a set of utilities that allow you to implement typical object-like entities. Most of the work actually happens in the {@link api/engine engine} and this API's role is only to properly conduct the engine. + The widget API is proposed in a very different way than it was in CKEditor 4. It is just a set of utilities that allow you to implement typical object-like entities. Most of the work actually happens in the {@link api/engine engine} and this API's only role is to control it. ## Installation -```bash +```plaintext npm install --save @ckeditor/ckeditor5-widget ``` diff --git a/packages/ckeditor5-widget/docs/framework/guides/deep-dive/widget-internals.md b/packages/ckeditor5-widget/docs/framework/guides/deep-dive/widget-internals.md index 1d57b1ce074..ce471a9b10e 100644 --- a/packages/ckeditor5-widget/docs/framework/guides/deep-dive/widget-internals.md +++ b/packages/ckeditor5-widget/docs/framework/guides/deep-dive/widget-internals.md @@ -7,19 +7,19 @@ menu-title: Widget internals ## Disabling the widget type around feature -The {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin allows users to type around widgets where normally it is impossible to place the caret due to limitations of web browsers. Although this feature boosts the productivity, some integrations may not want or need it, for instance: +The {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin allows users to type around the widgets, in places where it is normally impossible to place the caret due to limitations of the web browsers. Although this feature boosts the productivity and ease of typing, some integrations may not want or need it, for instance: -* when the UI of the feature collides with the integration, -* when typing outside widgets should be impossible (content made exclusively of widgets), -* when certain widgets have a fixed location in the document that should never change. +* When the UI of the feature collides with the integration. +* When typing outside widgets should be impossible (content made exclusively of widgets). +* When certain widgets have a fixed location in the document that should never change. -In the sections that follows, you will learn how to configure the editor to address these specific cases. +In the sections that follow, you will learn how to configure CKEditor 5 WYSIWYG editor to address these specific needs. -### Hiding the buttons that insert paragraphs +### Hiding the buttons that insert paragraphs around widgets {@img assets/img/framework-deep-dive-widget-type-around-buttons.gif A screenshot showing the location of the buttons that insert paragraphs around widgets.} -The easiest way to get rid of the type around buttons is to hide them using CSS. Put the following code snippet anywhere in your application and the buttons will no longer bother the users: +The easiest way to get rid of the type around widget buttons is to hide them using CSS. Put the following code snippet anywhere in your application and the buttons will no longer be displayed: ```css .ck.ck-editor__editable .ck-widget .ck-widget__type-around__button { @@ -27,18 +27,18 @@ The easiest way to get rid of the type around buttons is to hide them using CSS. } ``` -If you only want to customize the type around buttons you can use the same CSS selector to modify their look or the position. +If you only want to customize the type around widget buttons, you can use the same CSS selector to modify their look or position. - Hiding the type around buttons does not disable the feature. Users will still be able to activate the caret before or after individual widgets using the keyboard and start typing. [Learn how to disable the entire feature](#disabling-the-entire-feature). + Hiding the type around widget buttons does not disable the feature. Users will still be able to activate the caret before or after individual widgets using the arrow keys and typing. [Learn how to disable the entire feature](#disabling-the-entire-feature). ### Disabling the entire feature -Although the {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin is an integral part of the {@link module:widget/widget~Widget widget} sub–system and loaded by default whenever an editor feature uses widgets (for instance, {@link features/image images} or {@link features/table tables}), you can still disable on the fly. Disabling the feature will both hide the buttons in the widgets and disable other behaviors, for instance: +Although the {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin is an integral part of the {@link module:widget/widget~Widget widget} subsystem and is loaded by default whenever an editor feature uses widgets (for instance, for {@link features/image images} or {@link features/table tables}), you can still disable it on the fly. Turning off the feature will both hide the widget buttons and disable other behaviors, for instance: -* the caret will not be rendered before or after a widget when a user navigates the document using arrow keys, -* the Enter and Shift+Enter keystrokes will no longer insert paragraphs if pressed when a widget is selected. +* The caret will not be rendered before or after a widget when the user navigates the document using arrow keys. +* The Enter and Shift+Enter keystrokes will no longer insert paragraphs if pressed when a widget is selected. Use the {@link module:core/plugin~Plugin#forceDisabled `forceDisabled()`} method of the plugin to disable it on the fly like in the snippet below: @@ -50,7 +50,7 @@ ClassicEditor .then( editor => { const widgetTypeAroundPlugin = editor.plugins.get( 'WidgetTypeAround' ); - // Disable the WidgetTypeAround plugin. + // Disable the widget type around plugin. widgetTypeAroundPlugin.forceDisabled( 'MyApplication' ); } ) .catch( err => { @@ -58,10 +58,10 @@ ClassicEditor } ); ``` - - You can always re–enable the plugin using the following snippet - ```js - widgetTypeAroundPlugin.clearForceDisabled( 'MyApplication' ); - ``` - Please refer to the {@link module:core/plugin~Plugin#clearForceDisabled API documentation} to learn more. - +You can always re–enable the plugin using the following snippet + +```js +widgetTypeAroundPlugin.clearForceDisabled( 'MyApplication' ); +``` + +Refer to the {@link module:core/plugin~Plugin#clearForceDisabled API documentation} to learn more. diff --git a/packages/ckeditor5-widget/src/widgettypearound/utils.js b/packages/ckeditor5-widget/src/widgettypearound/utils.js index 7c1983c3e47..159bf8bc354 100644 --- a/packages/ckeditor5-widget/src/widgettypearound/utils.js +++ b/packages/ckeditor5-widget/src/widgettypearound/utils.js @@ -11,12 +11,12 @@ import { isWidget } from '../utils'; /** * The name of the type around model selection attribute responsible for - * displaying a "fake caret" next to a selected widget. + * displaying a fake caret next to a selected widget. */ export const TYPE_AROUND_SELECTION_ATTRIBUTE = 'widget-type-around'; /** - * Checks if an element is a widget that qualifies to get the type around UI. + * Checks if an element is a widget that qualifies to get the widget type around UI. * * @param {module:engine/view/element~Element} viewElement * @param {module:engine/model/element~Element} modelElement @@ -28,7 +28,7 @@ export function isTypeAroundWidget( viewElement, modelElement, schema ) { } /** - * For the passed HTML element, this helper finds the closest type around button ancestor. + * For the passed HTML element, this helper finds the closest widget type around button ancestor. * * @param {HTMLElement} domElement * @returns {HTMLElement|null} @@ -38,12 +38,12 @@ export function getClosestTypeAroundDomButton( domElement ) { } /** - * For the passed type around button element, this helper determines at which position + * For the passed widget type around button element, this helper determines at which position * the paragraph would be inserted into the content if, for instance, the button was * clicked by the user. * * @param {HTMLElement} domElement - * @returns {'before'|'after'} Position of the button. + * @returns {'before'|'after'} The position of the button. */ export function getTypeAroundButtonPosition( domElement ) { return domElement.classList.contains( 'ck-widget__type-around__button_before' ) ? 'before' : 'after'; @@ -63,12 +63,12 @@ export function getClosestWidgetViewElement( domElement, domConverter ) { } /** - * For the passed selection instance, it returns the position of the "fake caret" displayed next to a widget. + * For the passed selection instance, it returns the position of the fake caret displayed next to a widget. * - * **Note**: If the "fake caret" is not currently displayed, `null` is returned. + * **Note**: If the fake caret is not currently displayed, `null` is returned. * * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection - * @returns {'before'|'after'|null} Position of the fake caret or `null` when none is preset. + * @returns {'before'|'after'|null} The position of the fake caret or `null` when none is present. */ export function getTypeAroundFakeCaretPosition( selection ) { return selection.getAttribute( TYPE_AROUND_SELECTION_ATTRIBUTE ); diff --git a/packages/ckeditor5-widget/src/widgettypearound/widgettypearound.js b/packages/ckeditor5-widget/src/widgettypearound/widgettypearound.js index 3eca84ca0eb..a58a46408a1 100644 --- a/packages/ckeditor5-widget/src/widgettypearound/widgettypearound.js +++ b/packages/ckeditor5-widget/src/widgettypearound/widgettypearound.js @@ -46,7 +46,7 @@ const PLUGIN_DISABLED_EDITING_ROOT_CLASS = 'ck-widget__type-around_disabled'; * to limitations of web browsers. These "tight spots" occur, for instance, before (or after) a widget being * the first (or last) child of its parent or between two block widgets. * - * This plugin extends the {@link module:widget/widget~Widget `Widget`} plugin and injects a user interface + * This plugin extends the {@link module:widget/widget~Widget `Widget`} plugin and injects the user interface * with two buttons into each widget instance in the editor. Each of the buttons can be clicked by the * user if the widget is next to the "tight spot". Once clicked, a paragraph is created with the selection anchored * in it so that users can type (or insert content, paste, etc.) straight away. @@ -68,8 +68,8 @@ export default class WidgetTypeAround extends Plugin { super( editor ); /** - * A reference to the model widget element that has the "fake caret" active - * on either side of it. It is later used to remove CSS classes associated with the "fake caret" + * A reference to the model widget element that has the fake caret active + * on either side of it. It is later used to remove CSS classes associated with the fake caret * when the widget no longer needs it. * * @private @@ -167,11 +167,11 @@ export default class WidgetTypeAround extends Plugin { /** * Similar to {@link #_insertParagraph}, this method inserts a paragraph except that it - * does not expect a position but it performs the insertion next to a selected widget - * according to the "widget-type-around" model selection attribute value ("fake caret" position). + * does not expect a position. Instead, it performs the insertion next to a selected widget + * according to the `widget-type-around` model selection attribute value (fake caret position). * - * Because this method requires the "widget-type-around" attribute to be set, - * the insertion can only happen when the widget "fake caret" is active (e.g. activated + * Because this method requires the `widget-type-around` attribute to be set, + * the insertion can only happen when the widget's fake caret is active (e.g. activated * using the keyboard). * * @private @@ -195,7 +195,7 @@ export default class WidgetTypeAround extends Plugin { } /** - * Creates a listener in the editing conversion pipeline that injects the type around + * Creates a listener in the editing conversion pipeline that injects the widget type around * UI into every single widget instance created in the editor. * * The UI is delivered as a {@link module:engine/view/uielement~UIElement} @@ -223,28 +223,28 @@ export default class WidgetTypeAround extends Plugin { } /** - * Brings support for the "fake caret" that appears when either: + * Brings support for the fake caret that appears when either: * - * * the selection moves from a position next to a widget (to a widget) using arrow keys, + * * the selection moves to a widget from a position next to it using arrow keys, * * the arrow key is pressed when the widget is already selected. * - * The "fake caret" lets the user know that they can start typing or just press - * enter to insert a paragraph at the position next to a widget as suggested by the "fake caret". + * The fake caret lets the user know that they can start typing or just press + * Enter to insert a paragraph at the position next to a widget as suggested by the fake caret. * - * The "fake caret" disappears when the user changes the selection or the editor + * The fake caret disappears when the user changes the selection or the editor * gets blurred. * * The whole idea is as follows: * * 1. A user does one of the 2 scenarios described at the beginning. - * 2. The "keydown" listener is executed and the decision is made whether to show or hide the "fake caret". - * 3. If it should show up, the "widget-type-around" model selection attribute is set indicating + * 2. The "keydown" listener is executed and the decision is made whether to show or hide the fake caret. + * 3. If it should show up, the `widget-type-around` model selection attribute is set indicating * on which side of the widget it should appear. * 4. The selection dispatcher reacts to the selection attribute and sets CSS classes responsible for the - * "fake caret" on the view widget. - * 5. If the "fake caret" should disappear, the selection attribute is removed and the dispatcher + * fake caret on the view widget. + * 5. If the fake caret should disappear, the selection attribute is removed and the dispatcher * does the CSS class clean-up in the view. - * 6. Additionally, "change:range" and FocusTracker#isFocused listeners also remove the selection + * 6. Additionally, `change:range` and `FocusTracker#isFocused` listeners also remove the selection * attribute (the former also removes widget CSS classes). * * @private @@ -256,7 +256,7 @@ export default class WidgetTypeAround extends Plugin { const schema = model.schema; const editingView = editor.editing.view; - // This is the main listener responsible for the "fake caret". + // This is the main listener responsible for the fake caret. // Note: The priority must precede the default Widget class keydown handler ("high") and the // TableKeyboard keydown handler ("high-10"). this._listenToIfEnabled( editingView.document, 'keydown', ( evt, domEventData ) => { @@ -359,13 +359,13 @@ export default class WidgetTypeAround extends Plugin { * A listener executed on each "keydown" in the view document, a part of * {@link #_enableTypeAroundFakeCaretActivationUsingKeyboardArrows}. * - * It decides whether the arrow key press should activate the "fake caret" or not (also whether it should + * It decides whether the arrow keypress should activate the fake caret or not (also whether it should * be deactivated). * - * The "fake caret" activation is done by setting the "widget-type-around" model selection attribute - * in this listener and stopping&preventing the event that would normally be handled by the Widget + * The fake caret activation is done by setting the `widget-type-around` model selection attribute + * in this listener, and stopping and preventing the event that would normally be handled by the widget * plugin that is responsible for the regular keyboard navigation near/across all widgets (that - * includes inline widgets, which are ignored by the WidgetTypeAround plugin). + * includes inline widgets, which are ignored by the widget type around plugin). * * @private */ @@ -400,14 +400,14 @@ export default class WidgetTypeAround extends Plugin { /** * Handles the keyboard navigation on "keydown" when a widget is currently selected and activates or deactivates - * the "fake caret" for that widget, depending on the current value of the "widget-type-around" model + * the fake caret for that widget, depending on the current value of the `widget-type-around` model * selection attribute and the direction of the pressed arrow key. * * @private * @param {Boolean} isForward `true` when the pressed arrow key was responsible for the forward model selection movement * as in {@link module:utils/keyboard~isForwardArrowKeyCode}. - * @returns {Boolean} `true` when the key press was handled and no other keydown listener of the editor should - * process the event any further. `false` otherwise. + * @returns {Boolean} Returns `true` when the keypress was handled and no other keydown listener of the editor should + * process the event any further. Returns `false` otherwise. */ _handleArrowKeyPressOnSelectedWidget( isForward ) { const editor = this.editor; @@ -425,7 +425,7 @@ export default class WidgetTypeAround extends Plugin { // and do not let the Widget plugin listener move the selection. This brings // the widget back to the state, for instance, like if was selected using the mouse. // - // **Note**: If leaving the widget when the "fake caret" is active, then the default + // **Note**: If leaving the widget when the fake caret is active, then the default // Widget handler will change the selection and, in turn, this will automatically discard // the selection attribute. if ( !isLeavingWidget ) { @@ -448,18 +448,18 @@ export default class WidgetTypeAround extends Plugin { /** * Handles the keyboard navigation on "keydown" when **no** widget is selected but the selection is **directly** next - * to one and upon the "fake caret" should become active for this widget upon arrow key press + * to one and upon the fake caret should become active for this widget upon arrow keypress * (AKA entering/selecting the widget). * - * **Note**: This code mirrors the implementation from the Widget plugin but also adds the selection attribute. - * Unfortunately, there's no safe way to let the Widget plugin do the selection part first and then just set the - * selection attribute here in the WidgetTypeAround plugin. This is why this code must duplicate some from the Widget plugin. + * **Note**: This code mirrors the implementation from the widget plugin but also adds the selection attribute. + * Unfortunately, there is no safe way to let the widget plugin do the selection part first and then just set the + * selection attribute here in the widget type around plugin. This is why this code must duplicate some from the widget plugin. * * @private * @param {Boolean} isForward `true` when the pressed arrow key was responsible for the forward model selection movement * as in {@link module:utils/keyboard~isForwardArrowKeyCode}. - * @returns {Boolean} `true` when the key press was handled and no other keydown listener of the editor should - * process the event any further. `false` otherwise. + * @returns {Boolean} Returns `true` when the keypress was handled and no other keydown listener of the editor should + * process the event any further. Returns `false` otherwise. */ _handleArrowKeyPressWhenSelectionNextToAWidget( isForward ) { const editor = this.editor; @@ -487,7 +487,7 @@ export default class WidgetTypeAround extends Plugin { /** * Registers a `mousedown` listener for the view document which intercepts events - * coming from the type around UI, which happens when a user clicks one of the buttons + * coming from the widget type around UI, which happens when a user clicks one of the buttons * that insert a paragraph next to a widget. * * @private @@ -515,16 +515,16 @@ export default class WidgetTypeAround extends Plugin { } /** - * Creates the "enter" key listener on the view document that allows the user to insert a paragraph + * Creates the Enter key listener on the view document that allows the user to insert a paragraph * near the widget when either: * - * * The "fake caret" was first activated using the arrow keys, + * * The fake caret was first activated using the arrow keys, * * The entire widget is selected in the model. * - * In the first case, the new paragraph is inserted according to the "widget-type-around" selection + * In the first case, the new paragraph is inserted according to the `widget-type-around` selection * attribute (see {@link #_handleArrowKeyPress}). * - * It the second case, the new paragraph is inserted based on whether a soft (Shift+Enter) keystroke + * In the second case, the new paragraph is inserted based on whether a soft (Shift+Enter) keystroke * was pressed or not. * * @private @@ -540,11 +540,11 @@ export default class WidgetTypeAround extends Plugin { let wasHandled; // First check if the widget is selected and there's a type around selection attribute associated - // with the "fake caret" that would tell where to insert a new paragraph. + // with the fake caret that would tell where to insert a new paragraph. if ( this._insertParagraphAccordingToFakeCaretPosition() ) { wasHandled = true; } - // Then, if there is no selection attribute associated with the "fake caret", check if the widget + // Then, if there is no selection attribute associated with the fake caret, check if the widget // simply is selected and create a new paragraph according to the keystroke (Shift+)Enter. else if ( isTypeAroundWidget( selectedViewElement, selectedModelElement, schema ) ) { this._insertParagraph( selectedModelElement, domEventData.isSoft ? 'before' : 'after' ); @@ -561,17 +561,17 @@ export default class WidgetTypeAround extends Plugin { /** * Similar to the {@link #_enableInsertingParagraphsOnEnterKeypress}, it allows the user - * to insert a paragraph next to a widget when the "fake caret" was activated using arrow - * keys but it responds to "typing keystrokes" instead of "enter". + * to insert a paragraph next to a widget when the fake caret was activated using arrow + * keys but it responds to typing keystrokes instead of Enter. * - * "Typing keystrokes" are keystrokes that insert new content into the document - * like, for instance, letters ("a") or numbers ("4"). The "keydown" listener enabled by this method - * will insert a new paragraph according to the "widget-type-around" model selection attribute - * as the user simply starts typing, which creates the impression that the "fake caret" - * behaves like a "real one" rendered by the browser (AKA your text appears where the caret was). + * "Typing keystrokes" are keystrokes that insert new content into the document, + * for instance, letters ("a") or numbers ("4"). The "keydown" listener enabled by this method + * will insert a new paragraph according to the `widget-type-around` model selection attribute + * as the user simply starts typing, which creates the impression that the fake caret + * behaves like a real one rendered by the browser (AKA your text appears where the caret was). * - * **Note**: ATM this listener creates 2 undo steps: one for the "insertParagraph" command - * and the second for the actual typing. It's not a disaster but this may need to be fixed + * **Note**: At the moment this listener creates 2 undo steps: one for the `insertParagraph` command + * and another one for actual typing. It is not a disaster but this may need to be fixed * sooner or later. * * Learn more in {@link module:typing/utils/injectunsafekeystrokeshandling}. @@ -598,12 +598,12 @@ export default class WidgetTypeAround extends Plugin { } /** - * It creates a "delete" event listener on the view document to handle cases when delete/backspace - * is pressed and the "fake caret" is currently active. + * It creates a "delete" event listener on the view document to handle cases when the Delete or Backspace + * is pressed and the fake caret is currently active. * - * The "fake caret" should create an illusion of a "real browser caret" so that when it appears - * before/after a widget, pressing delete/backspace should remove a widget or delete a content - * before/after a widget (depending on the content surrounding the widget). + * The fake caret should create an illusion of a real browser caret so that when it appears before or after + * a widget, pressing Delete or Backspace should remove a widget or delete the content + * before or after a widget (depending on the content surrounding the widget). * * @private */ @@ -617,7 +617,7 @@ export default class WidgetTypeAround extends Plugin { this._listenToIfEnabled( editingView.document, 'delete', ( evt, domEventData ) => { const typeAroundFakeCaretPosition = getTypeAroundFakeCaretPosition( model.document.selection ); - // This listener handles only these cases when the "fake caret" is active. + // This listener handles only these cases when the fake caret is active. if ( !typeAroundFakeCaretPosition ) { return; } @@ -682,9 +682,9 @@ export default class WidgetTypeAround extends Plugin { /** * Attaches the {@link module:engine/model/model~Model#event:insertContent} event listener that, for instance, allows the user to paste - * content near a widget when the "fake caret" was first activated using the arrow keys. + * content near a widget when the fake caret is first activated using the arrow keys. * - * The content is inserted according to the "widget-type-around" selection attribute (see {@link #_handleArrowKeyPress}). + * The content is inserted according to the `widget-type-around` selection attribute (see {@link #_handleArrowKeyPress}). * * @private */