| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551 |
- /**
- * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
- /**
- * @module heading/title
- */
- import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
- import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
- import ViewDocumentFragment from '@ckeditor/ckeditor5-engine/src/view/documentfragment';
- import ViewDowncastWriter from '@ckeditor/ckeditor5-engine/src/view/downcastwriter';
- import ViewDocument from '@ckeditor/ckeditor5-engine/src/view/document';
- import first from '@ckeditor/ckeditor5-utils/src/first';
- import {
- needsPlaceholder,
- showPlaceholder,
- hidePlaceholder,
- enablePlaceholder
- } from '@ckeditor/ckeditor5-engine/src/view/placeholder';
- // A list of element names that should be treated by the Title plugin as title-like.
- // This means that an element of a type from this list will be changed to a title element
- // when it is the first element in the root.
- const titleLikeElements = new Set( [ 'paragraph', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6' ] );
- /**
- * The Title plugin.
- *
- * It splits the document into `Title` and `Body` sections.
- *
- * @extends module:core/plugin~Plugin
- */
- export default class Title extends Plugin {
- /**
- * @inheritDoc
- */
- static get pluginName() {
- return 'Title';
- }
- /**
- * @inheritDoc
- */
- static get requires() {
- return [ Paragraph ];
- }
- /**
- * @inheritDoc
- */
- init() {
- const editor = this.editor;
- const model = editor.model;
- /**
- * A reference to an empty paragraph in the body
- * created when there is no element in the body for the placeholder purposes.
- *
- * @private
- * @type {null|module:engine/model/element~Element}
- */
- this._bodyPlaceholder = null;
- // To use the schema for disabling some features when the selection is inside the title element
- // it is needed to create the following structure:
- //
- // <title>
- // <title-content>The title text</title-content>
- // </title>
- //
- // See: https://github.com/ckeditor/ckeditor5/issues/2005.
- model.schema.register( 'title', { isBlock: true, allowIn: '$root' } );
- model.schema.register( 'title-content', { isBlock: true, allowIn: 'title', allowAttributes: [ 'alignment' ] } );
- model.schema.extend( '$text', { allowIn: 'title-content' } );
- // Disallow all attributes in `title-content`.
- model.schema.addAttributeCheck( context => {
- if ( context.endsWith( 'title-content $text' ) ) {
- return false;
- }
- } );
- // Because `title` is represented by two elements in the model
- // but only one in the view, it is needed to adjust Mapper.
- editor.editing.mapper.on( 'modelToViewPosition', mapModelPositionToView( editor.editing.view ) );
- editor.data.mapper.on( 'modelToViewPosition', mapModelPositionToView( editor.editing.view ) );
- // Conversion.
- editor.conversion.for( 'downcast' ).elementToElement( { model: 'title-content', view: 'h1' } );
- // Custom converter is used for data v -> m conversion to avoid calling post-fixer when setting data.
- // See https://github.com/ckeditor/ckeditor5/issues/2036.
- editor.data.upcastDispatcher.on( 'element:h1', dataViewModelH1Insertion, { priority: 'high' } );
- editor.data.upcastDispatcher.on( 'element:h2', dataViewModelH1Insertion, { priority: 'high' } );
- editor.data.upcastDispatcher.on( 'element:h3', dataViewModelH1Insertion, { priority: 'high' } );
- // Take care about correct `title` element structure.
- model.document.registerPostFixer( writer => this._fixTitleContent( writer ) );
- // Create and take care of correct position of a `title` element.
- model.document.registerPostFixer( writer => this._fixTitleElement( writer ) );
- // Create element for `Body` placeholder if it is missing.
- model.document.registerPostFixer( writer => this._fixBodyElement( writer ) );
- // Prevent from adding extra at the end of the document.
- model.document.registerPostFixer( writer => this._fixExtraParagraph( writer ) );
- // Attach `Title` and `Body` placeholders to the empty title and/or content.
- this._attachPlaceholders();
- // Attach Tab handling.
- this._attachTabPressHandling();
- }
- /**
- * Returns the title of the document. Note that because this plugin does not allow any formatting inside
- * the title element, the output of this method will be a plain text, with no HTML tags.
- *
- * Note that it is not recommended to use this method together with features which insert markers to the
- * data output, like comments or track changes features. If such markers start in the title and end in the
- * body the result of this method might be incorrect.
- *
- * @returns {String} The title of the document.
- */
- getTitle() {
- const titleElement = this._getTitleElement();
- const titleContentElement = titleElement.getChild( 0 );
- return this.editor.data.stringify( titleContentElement );
- }
- /**
- * Returns the body of the document.
- *
- * Note that it is not recommended to use this method together with features which insert markers to the
- * data output, like comments or track changes features. If such markers start in the title and end in the
- * body the result of this method might be incorrect.
- *
- * @returns {String} The body of the document.
- */
- getBody() {
- const data = this.editor.data;
- const model = this.editor.model;
- const root = this.editor.model.document.getRoot();
- const viewWriter = new ViewDowncastWriter( new ViewDocument() );
- const rootRange = model.createRangeIn( root );
- const viewDocumentFragment = new ViewDocumentFragment();
- // Convert the entire root to view.
- data.mapper.clearBindings();
- data.mapper.bindElements( root, viewDocumentFragment );
- data.downcastDispatcher.convertInsert( rootRange, viewWriter );
- // Convert all markers that intersects with body.
- const bodyStartPosition = model.createPositionAfter( root.getChild( 0 ) );
- const bodyRange = model.createRange( bodyStartPosition, model.createPositionAt( root, 'end' ) );
- for ( const marker of model.markers ) {
- const intersection = bodyRange.getIntersection( marker.getRange() );
- if ( intersection ) {
- data.downcastDispatcher.convertMarkerAdd( marker.name, intersection, viewWriter );
- }
- }
- // Remove title element from view.
- viewWriter.remove( viewWriter.createRangeOn( viewDocumentFragment.getChild( 0 ) ) );
- // view -> data
- return this.editor.data.processor.toData( viewDocumentFragment );
- }
- /**
- * Returns the `title` element when it is in the document. Returns `undefined` otherwise.
- *
- * @private
- * @returns {module:engine/model/element~Element|undefined}
- */
- _getTitleElement() {
- const root = this.editor.model.document.getRoot();
- for ( const child of root.getChildren() ) {
- if ( isTitle( child ) ) {
- return child;
- }
- }
- }
- /**
- * Model post-fixer callback that ensures that `title` has only one `title-content` child.
- * All additional children should be moved after the `title` element and renamed to a paragraph.
- *
- * @private
- * @param {module:engine/model/writer~Writer} writer
- * @returns {Boolean}
- */
- _fixTitleContent( writer ) {
- const title = this._getTitleElement();
- // There's no title in the content - it will be created by _fixTitleElement post-fixer.
- if ( !title || title.maxOffset === 1 ) {
- return false;
- }
- const titleChildren = Array.from( title.getChildren() );
- // Skip first child because it is an allowed element.
- titleChildren.shift();
- for ( const titleChild of titleChildren ) {
- writer.move( writer.createRangeOn( titleChild ), title, 'after' );
- writer.rename( titleChild, 'paragraph' );
- }
- return true;
- }
- /**
- * Model post-fixer callback that creates a title element when it is missing,
- * takes care of the correct position of it and removes additional title elements.
- *
- * @private
- * @param {module:engine/model/writer~Writer} writer
- * @returns {Boolean}
- */
- _fixTitleElement( writer ) {
- const model = this.editor.model;
- const modelRoot = model.document.getRoot();
- const titleElements = Array.from( modelRoot.getChildren() ).filter( isTitle );
- const firstTitleElement = titleElements[ 0 ];
- const firstRootChild = modelRoot.getChild( 0 );
- // When title element is at the beginning of the document then try to fix additional
- // title elements (if there are any) and stop post-fixer as soon as possible.
- if ( firstRootChild.is( 'title' ) ) {
- return fixAdditionalTitleElements( titleElements, writer, model );
- }
- // When there is no title in the document and first element in the document cannot be changed
- // to the title then create an empty title element at the beginning of the document.
- if ( !firstTitleElement && !titleLikeElements.has( firstRootChild.name ) ) {
- const title = writer.createElement( 'title' );
- writer.insert( title, modelRoot );
- writer.insertElement( 'title-content', title );
- return true;
- }
- // At this stage, we are sure the title is somewhere in the content. It has to be fixed.
- // Change the first element in the document to the title if it can be changed (is title-like).
- if ( titleLikeElements.has( firstRootChild.name ) ) {
- changeElementToTitle( firstRootChild, writer, model );
- // Otherwise, move the first occurrence of the title element to the beginning of the document.
- } else {
- writer.move( writer.createRangeOn( firstTitleElement ), modelRoot, 0 );
- }
- fixAdditionalTitleElements( titleElements, writer, model );
- return true;
- }
- /**
- * Model post-fixer callback that adds an empty paragraph at the end of the document
- * when it is needed for the placeholder purpose.
- *
- * @private
- * @param {module:engine/model/writer~Writer} writer
- * @returns {Boolean}
- */
- _fixBodyElement( writer ) {
- const modelRoot = this.editor.model.document.getRoot();
- if ( modelRoot.childCount < 2 ) {
- this._bodyPlaceholder = writer.createElement( 'paragraph' );
- writer.insert( this._bodyPlaceholder, modelRoot, 1 );
- return true;
- }
- return false;
- }
- /**
- * Model post-fixer callback that removes a paragraph from the end of the document
- * if it was created for the placeholder purposes and is not needed anymore.
- *
- * @private
- * @param {module:engine/model/writer~Writer} writer
- * @returns {Boolean}
- */
- _fixExtraParagraph( writer ) {
- const root = this.editor.model.document.getRoot();
- const placeholder = this._bodyPlaceholder;
- if ( shouldRemoveLastParagraph( placeholder, root ) ) {
- this._bodyPlaceholder = null;
- writer.remove( placeholder );
- return true;
- }
- return false;
- }
- /**
- * Attaches the `Title` and `Body` placeholders to the title and/or content.
- *
- * @private
- */
- _attachPlaceholders() {
- const editor = this.editor;
- const t = editor.t;
- const view = editor.editing.view;
- const viewRoot = view.document.getRoot();
- const bodyPlaceholder = editor.config.get( 'placeholder' ) || t( 'Body' );
- const titlePlaceholder = t( 'Title' );
- // Attach placeholder to the view title element.
- editor.editing.downcastDispatcher.on( 'insert:title-content', ( evt, data, conversionApi ) => {
- enablePlaceholder( {
- view,
- element: conversionApi.mapper.toViewElement( data.item ),
- text: titlePlaceholder
- } );
- } );
- // Attach placeholder to first element after a title element and remove it if it's not needed anymore.
- // First element after title can change so we need to observe all changes keep placeholder in sync.
- let oldBody;
- // This post-fixer runs after the model post-fixer so we can assume that
- // the second child in view root will always exist.
- view.document.registerPostFixer( writer => {
- const body = viewRoot.getChild( 1 );
- let hasChanged = false;
- // If body element has changed we need to disable placeholder on the previous element
- // and enable on the new one.
- if ( body !== oldBody ) {
- if ( oldBody ) {
- hidePlaceholder( writer, oldBody );
- writer.removeAttribute( 'data-placeholder', oldBody );
- }
- writer.setAttribute( 'data-placeholder', bodyPlaceholder, body );
- oldBody = body;
- hasChanged = true;
- }
- // Then we need to display placeholder if it is needed.
- if ( needsPlaceholder( body ) && viewRoot.childCount === 2 && body.name === 'p' ) {
- hasChanged = showPlaceholder( writer, body ) ? true : hasChanged;
- // Or hide if it is not needed.
- } else {
- hasChanged = hidePlaceholder( writer, body ) ? true : hasChanged;
- }
- return hasChanged;
- } );
- }
- /**
- * Creates navigation between the title and body sections using <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.
- *
- * @private
- */
- _attachTabPressHandling() {
- const editor = this.editor;
- const model = editor.model;
- // Pressing <kbd>Tab</kbd> inside the title should move the caret to the body.
- editor.keystrokes.set( 'TAB', ( data, cancel ) => {
- model.change( writer => {
- const selection = model.document.selection;
- const selectedElements = Array.from( selection.getSelectedBlocks() );
- if ( selectedElements.length === 1 && selectedElements[ 0 ].is( 'title-content' ) ) {
- const firstBodyElement = model.document.getRoot().getChild( 1 );
- writer.setSelection( firstBodyElement, 0 );
- cancel();
- }
- } );
- } );
- // Pressing <kbd>Shift</kbd>+<kbd>Tab</kbd> at the beginning of the body should move the caret to the title.
- editor.keystrokes.set( 'SHIFT + TAB', ( data, cancel ) => {
- model.change( writer => {
- const selection = model.document.selection;
- if ( !selection.isCollapsed ) {
- return;
- }
- const root = editor.model.document.getRoot();
- const selectedElement = first( selection.getSelectedBlocks() );
- const selectionPosition = selection.getFirstPosition();
- const title = root.getChild( 0 );
- const body = root.getChild( 1 );
- if ( selectedElement === body && selectionPosition.isAtStart ) {
- writer.setSelection( title.getChild( 0 ), 0 );
- cancel();
- }
- } );
- } );
- }
- }
- // A view-to-model converter for the h1 that appears at the beginning of the document (a title element).
- //
- // @see module:engine/conversion/upcastdispatcher~UpcastDispatcher#event:element
- // @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
- // @param {Object} data An object containing conversion input, a placeholder for conversion output and possibly other values.
- // @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion interface to be used by the callback.
- function dataViewModelH1Insertion( evt, data, conversionApi ) {
- const modelCursor = data.modelCursor;
- const viewItem = data.viewItem;
- if ( !modelCursor.isAtStart || !modelCursor.parent.is( '$root' ) ) {
- return;
- }
- if ( !conversionApi.consumable.consume( viewItem, { name: true } ) ) {
- return;
- }
- const modelWriter = conversionApi.writer;
- const title = modelWriter.createElement( 'title' );
- const titleContent = modelWriter.createElement( 'title-content' );
- modelWriter.append( titleContent, title );
- modelWriter.insert( title, modelCursor );
- conversionApi.convertChildren( viewItem, modelWriter.createPositionAt( titleContent, 0 ) );
- data.modelRange = modelWriter.createRangeOn( title );
- data.modelCursor = modelWriter.createPositionAt( data.modelRange.end );
- }
- // Maps position from the beginning of the model `title` element to the beginning of the view `h1` element.
- //
- // <title>^<title-content>Foo</title-content></title> -> <h1>^Foo</h1>
- //
- // @param {module:editor/view/view~View} editingView
- function mapModelPositionToView( editingView ) {
- return ( evt, data ) => {
- const positionParent = data.modelPosition.parent;
- if ( !positionParent.is( 'title' ) ) {
- return;
- }
- const modelTitleElement = positionParent.parent;
- const viewElement = data.mapper.toViewElement( modelTitleElement );
- data.viewPosition = editingView.createPositionAt( viewElement, 0 );
- evt.stop();
- };
- }
- // Returns true when given element is a title. Returns false otherwise.
- //
- // @param {module:engine/model/element~Element} element
- // @returns {Boolean}
- function isTitle( element ) {
- return element.is( 'title' );
- }
- // Changes the given element to the title element.
- //
- // @param {module:engine/model/element~Element} element
- // @param {module:engine/model/writer~Writer} writer
- // @param {module:engine/model/model~Model} model
- function changeElementToTitle( element, writer, model ) {
- const title = writer.createElement( 'title' );
- writer.insert( title, element, 'before' );
- writer.insert( element, title, 0 );
- writer.rename( element, 'title-content' );
- model.schema.removeDisallowedAttributes( [ element ], writer );
- }
- // Loops over the list of title elements and fixes additional ones.
- //
- // @param {Array.<module:engine/model/element~Element>} titleElements
- // @param {module:engine/model/writer~Writer} writer
- // @param {module:engine/model/model~Model} model
- // @returns {Boolean} Returns true when there was any change. Returns false otherwise.
- function fixAdditionalTitleElements( titleElements, writer, model ) {
- let hasChanged = false;
- for ( const title of titleElements ) {
- if ( title.index !== 0 ) {
- fixTitleElement( title, writer, model );
- hasChanged = true;
- }
- }
- return hasChanged;
- }
- // Changes given title element to a paragraph or removes it when it is empty.
- //
- // @param {module:engine/model/element~Element} title
- // @param {module:engine/model/writer~Writer} writer
- // @param {module:engine/model/model~Model} model
- function fixTitleElement( title, writer, model ) {
- const child = title.getChild( 0 );
- // Empty title should be removed.
- // It is created as a result of pasting to the title element.
- if ( child.isEmpty ) {
- writer.remove( title );
- return;
- }
- writer.move( writer.createRangeOn( child ), title, 'before' );
- writer.rename( child, 'paragraph' );
- writer.remove( title );
- model.schema.removeDisallowedAttributes( [ child ], writer );
- }
- // Returns true when the last paragraph in the document was created only for the placeholder
- // purpose and it's not needed anymore. Returns false otherwise.
- //
- // @param {module:engine/model/rootelement~RootElement} root
- // @param {module:engine/model/element~Element} placeholder
- // @returns {Boolean}
- function shouldRemoveLastParagraph( placeholder, root ) {
- if ( !placeholder || !placeholder.is( 'paragraph' ) || placeholder.childCount ) {
- return false;
- }
- if ( root.childCount <= 2 || root.getChild( root.childCount - 1 ) !== placeholder ) {
- return false;
- }
- return true;
- }
|