Skip to content

Latest commit

 

History

History
121 lines (85 loc) · 8.03 KB

README.md

File metadata and controls

121 lines (85 loc) · 8.03 KB
Raw
category order url menu-title meta-title-short
inserting-content
40
features/pastefromword
Paste from Word
Paste from Word

Pasting Content from Microsoft Word

This feature is provided through the Paste from Word plugin that is included in the Standard and Full presets available from the official CKEditor 4 Download site. You can also {@link guide/dev/plugins/README add it to your custom build} with online builder.

The Paste from Word plugin allows you to paste content from Microsoft Word and maintain original content structure and formatting.

When enabled, it automatically detects Word content and transforms its structure and formatting to clean HTML. It also adds the Paste from Word toolbar button (Paste from Word toolbar button) which makes it possible to paste clipboard data this way only on demand.

Supported Features

Paste from Word retains the following formatting:

  • Text formatting
    • Text and background colors
    • Font name, style and size
    • Basic formatting (bold, italic, underline)
    • Font effects (strikethrough, superscript, subscript)
    • Heading levels
    • Text alignment
  • Lists
    • Numbered and bulleted lists
    • Multilevel lists
    • Different numbering formats (Roman, decimal, alphanumeric)
    • Custom start number (e.g. you can start the list from number 4)
  • Tables
    • Borders and shading
    • Cell size (width and height)
    • Cell alignment
  • Images
  • Paste from Excel
    • Cell formatting (size, background, borders, special characters)
    • Row and column size
    • Text formatting (as listed above)
  • Advanced formatting
    • Default styles
    • User-defined styles

The Paste from Word plugin maintains most of Microsoft Word text formatting features with some exceptions related to advanced styling, customizations, or stylings that are not supported by HTML. For example, it will paste only standard bullets from the bullet library, or will not use a double strikethrough effect. Such elements are replaced by the default ones to resemble your Word content in the most accurate way.

Advanced Paste from Word — CKEditor 4.6+

Pasting from Word is, in general, as tricky as it can get. With plenty of possible combinations of Microsoft Word, operating system and browser versions Word output that comes through clipboard to CKEditor 4 can significantly differ. This makes it extremely hard to support some of the more complicated content formatting cases that include text, images, lists, tables, nested objects, plenty of colors, styles and so on.

CKEditor 4 has always been a market leader in parsing Word content and transforming it to valid HTML, but handling some of the more complex cases and working around vendor bugs takes a lot of time, effort and experience. With some new tools available, such as {@link guide/dev/acf/README Advanced Content Filter} or {@link features/drop_paste/README Clipboard API}, we have decided to rewrite the Paste from Word feature from scratch.

Here are some areas where the new, Advanced Paste from Word really shines:

  • Preservation of list numbering, styling and indentation (for example, nested lists with multiple levels, with different styling or custom list markers).
  • Document structure parsing that fixes plenty of issues with distorted or missing content after paste.
  • Smarter inline formatting, including preserving text or background color.
  • Handling hotlinked images.
  • Tight integration with Advanced Content Filter to efficiently adjust formatting coming from Word to what is allowed in a particular editor configuration.
  • Clean and valid HTML markup.

Note: Some Paste from Word configuration options were either dropped in CKEditor 4.6 or changed their default values. Please refer to the release notes for more details.

Sample

The following sample content from a Microsoft Word document:

{@img assets/img/pastefromword_01.png 683 A sample Microsoft Word document.}

will look like below after pasting to CKEditor 4 with the Paste from Word plugin enabled:

{@img assets/img/pastefromword_02.png 951 Microsoft Word content pasted into CKEditor 4 WYSIWYG editor.}

Here is another sample with some more complicated formatting and styling as well as an image:

{@img assets/img/pastefromword_03.png 628 A sample Microsoft Word document with complex formatting and image.}

It will look like this after pasting into CKEditor 4:

{@img assets/img/pastefromword_04.png 953 Complex Word content pasted into CKEditor 4 WYSIWYG editor.}

In the example above you can see that after pasting into CKEditor 4, the first list has different list item markers than in the Word document. Although pasting lists with different markers is supported in CKEditor 4 (check the second and third list in the example above), this is a specific case. Such list style is not natively supported by the browser. However, it can be adjusted by using extra CSS rules (see a related StackOverflow thread how to style it properly).

Filters

HTML exposed by Microsoft Word does not comply to any imaginable rules. It is a poetry of what can be done wrong. Therefore, a separate filter had to be created to normalize this content. It is implemented in the Paste from Word plugin and, beside the {@link features/drop_paste/README#filtering-content standard filtering options}, it has additional settings:

  • {@linkapi CKEDITOR.config.pasteFromWordCleanupFile CKEDITOR.config.pasteFromWordCleanupFile}
  • {@linkapi CKEDITOR.config.pasteFromWordPromptCleanup CKEDITOR.config.pasteFromWordPromptCleanup}

Starting from version 4.6 of CKEditor the following options were deprecated:

  • {@linkapi CKEDITOR.config.pasteFromWordRemoveFontStyles CKEDITOR.config.pasteFromWordRemoveFontStyles} (deprecated in favor of Advanced Content Filter, see {@link guide/dev/deep_dive/advanced_content_filter/README#example-removing-font-styles an example of removing font styles})

For CKEditor versions older than 4.6 the following options were available, too:

  • {@linkapi CKEDITOR.config.pasteFromWordNumberedHeadingToList CKEDITOR.config.pasteFromWordNumberedHeadingToList}
  • {@linkapi CKEDITOR.config.pasteFromWordRemoveStyles CKEDITOR.config.pasteFromWordRemoveStyles}

Paste from Word Demo

See the {@linkexample pastefromword working "Pasting content from Microsoft Word" sample} that showcases the Paste from Word plugin.

Related Features

Refer to the following resources for more information about pasting content:

  • The {@link features/pastefromgoogledocs/README Pasting content from Google Docs} article contains more information about the Paste from Google Docs feature.
  • The {@link features/pastefromexcel/README Pasting content from Microsoft Excel} article contains more information about the Paste from Excel feature.
  • The {@link features/pastefromlibreoffice/README Pasting content from LibreOffice Writer} article contains more information about the Paste from LibreOffice feature.
  • The {@link guide/dev/deep_dive/clipboard/README Clipboard Integration} article explains how Clipboard API is implemented in CKEditor 4.
  • The {@link guide/dev/integration/file_browse_upload/file_upload/README Uploading Dropped or Pasted Files} article describes drag&drop in CKEditor 4.
  • The {@link guide/dev/acf/README Content Filtering (ACF)} is an introduction to CKEditor's unique content filtering system.
  • The {@link features/styles/README Applying Styles to Editor Content} article discusses creating more semantically correct text styles.