Merge ba390fd into 69ec195

ckeditor · Nov 19, 2019 · 7471373 · 7471373
2 parents 69ec195 + ba390fd
commit 7471373
Show file tree

Hide file tree

Showing 33 changed files with 4,075 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,20 @@
 CKEditor 5 code block feature
 ========================================
 
-This is an initial package for development purposes. It does not contain code yet.
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-code-block.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block)
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-code-block.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block)
+[![Build Status](https://travis-ci.org/ckeditor/ckeditor5-code-block.svg?branch=master)](https://travis-ci.org/ckeditor/ckeditor5-code-block)
+[![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5-code-block/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5-code-block?branch=master)
+<br>
+[![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-code-block/status.svg)](https://david-dm.org/ckeditor/ckeditor5-code-block)
+[![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-code-block/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-code-block?type=dev)
+
+This package implements the code block feature for CKEditor 5.
+
+## Documentation
+
+See the [`@ckeditor/ckeditor5-code-block` package](https://ckeditor.com/docs/ckeditor5/latest/api/code-block.html) page as well as the [Code block feature guide](https://ckeditor.com/docs/ckeditor5/latest/features/code-block.html) in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+
+## License
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).
diff --git a/docs/_snippets/features/build-code-block-source.html b/docs/_snippets/features/build-code-block-source.html
@@ -0,0 +1,12 @@
+<style>
+	/* Override documentation styles for <pre> and <code>. */
+
+	.ck.ck-content pre {
+		overflow: visible;
+		line-height: 1.3em;
+	}
+
+	.ck.ck-content pre code {
+		background: transparent;
+	}
+</style>
diff --git a/docs/_snippets/features/build-code-block-source.js b/docs/_snippets/features/build-code-block-source.js
@@ -0,0 +1,15 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import CodeBlock from '@ckeditor/ckeditor5-code-block/src/codeblock';
+import Code from '@ckeditor/ckeditor5-basic-styles/src/code';
+import Indent from '@ckeditor/ckeditor5-indent/src/indent';
+
+ClassicEditor.builtinPlugins.push( CodeBlock, Code, Indent );
+
+window.ClassicEditor = ClassicEditor;
diff --git a/docs/_snippets/features/code-block-custom-languages.html b/docs/_snippets/features/code-block-custom-languages.html
@@ -0,0 +1,6 @@
+<div id="snippet-custom-languages">
+	<p>Put some text in the <code>&lt;body&gt;</code>:</p>
+<pre><code class="xml"><body>Hello world!</body></code></pre>
+	<p>Then set the font color:</p>
+<pre><code class="css">body { color: red }</code></pre>
+</div>
diff --git a/docs/_snippets/features/code-block-custom-languages.js b/docs/_snippets/features/code-block-custom-languages.js
@@ -0,0 +1,43 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-custom-languages' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'code',
+				'codeBlock',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		codeBlock: {
+			languages: [
+				{ class: 'css', label: 'CSS' },
+				{ class: 'xml', label: 'HTML/XML' }
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/docs/_snippets/features/code-block.html b/docs/_snippets/features/code-block.html
@@ -0,0 +1,23 @@
+<div id="snippet-highlight">
+	<h2>Getting started with CKEditor 5</h2>
+	<p>First, create an HTML element with the initial content:</p>
+<pre><code class="xml"><div id="editor">
+	&lt;p&gt;Here goes the initial content of the editor.&lt;/p&gt;
+</div></code></pre>
+
+<p>Then use the following code to run the editor:</p>
+<pre><code class="javascript">ClassicEditor
+	.create( document.querySelector( '#editor' ) )
+	.catch( error => {
+		console.error( error );
+	} );</code></pre>
+
+<p>Finally, let your artistic self shine:</p>
+<pre><code> ________________
+/                \
+| How about moo? |  ^__^
+\________________/  (oo)\_______
+				  \ (__)\       )\/\
+						||----w |
+						||     ||</code></pre>
+</div>
diff --git a/docs/_snippets/features/code-block.js b/docs/_snippets/features/code-block.js
@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-highlight' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'code',
+				'codeBlock',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/docs/api/code-block.md b/docs/api/code-block.md
@@ -0,0 +1,34 @@
+---
+category: api-reference
+---
+
+# CKEditor 5 code block feature
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-code-block.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-highlight)
+
+This package implements the code block feature for CKEditor 5.
+
+## Demo
+
+Check out the {@link features/code-block#demo demo in the Code block feature} guide.
+
+## Documentation
+
+See the {@link features/code-block Code block feature} guide and the {@link module:code-block/codeblock~CodeBlock} plugin documentation.
+
+## Installation
+
+```bash
+npm install --save @ckeditor/ckeditor5-code-block
+```
+
+## Contribute
+
+The source code of this package is available on GitHub in https://github.com/ckeditor/ckeditor5-code-block.
+
+## External links
+
+* [`@ckeditor/ckeditor5-code-block` on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block)
+* [`ckeditor/ckeditor5-code-block` on GitHub](https://github.com/ckeditor/ckeditor5-code-block)
+* [Issue tracker](https://github.com/ckeditor/ckeditor5/issues)
+* [Changelog](https://github.com/ckeditor/ckeditor5-code-block/blob/master/CHANGELOG.md)
diff --git a/docs/features/code-block.md b/docs/features/code-block.md
@@ -0,0 +1,162 @@
+---
+category: features
+---
+
+# Code block
+
+{@snippet features/build-code-block-source}
+
+The {@link module:code-block/codeblock~CodeBlock} feature allows inserting and editing blocks of pre–formatted code into the editor. Code blocks have their [specific languages](#configuring-code-block-languages) (e.g. "Java" or "CSS") and support basic editing tools, for instance, [changing the line indentation](#changing-line-indentation) using the keyboard.
+
+## Demo
+
+{@snippet features/code-block}
+
+## Configuring code block languages
+
+Each code block can have its language. The language of the code block is represented as a CSS class set on the `<code>` element, both when editing and in the editor data:
+
+```html
+<pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
+```
+
+It is possible to configure which languages are available in the editor. You can use the {@link module:code-block/codeblock~CodeBlockConfig#languages `codeBlock.languages`} configuration and define your own languages. For example, the following editor supports only two languages (CSS and XML/HTML):
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		codeBlock: {
+			languages: [
+				{ class: 'language-css', label: 'CSS' },
+				{ class: 'language-xml', label: 'HTML/XML' }
+			]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+{@snippet features/code-block-custom-languages}
+
+<info-box>
+	**Note**: The first language defined in the configuration is considered the default one. This means it will be applied to code blocks loaded from data that have no CSS `class` specified (or no  `class` matching the {@link module:code-block/codeblock~CodeBlockConfig#languages configuration}). It will also be used when creating new code blocks using the toolbar button. By default it is "Plain text" (`plaintext` CSS class).
+</info-box>
+
+### Integration with code highlighters
+
+Although the live code block highlighting is impossible when editing in CKEditor 5 ([learn more](https://github.com/ckeditor/ckeditor5/issues/436#issuecomment-548399675)), the content can be highlighted when displayed in the frontend (e.g. in blog posts, messages, etc.).
+
+The code language {@link module:code-block/codeblock~CodeBlockConfig#languages configuration} helps to integrate with external code highlighters (e.g. [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/)). Please refer to the documentation of the highlighter of your choice and make sure CSS classes configured in `codeBlock.languages` correspond with the code syntax auto–detection feature of the highlighter.
+
+## Tips and tweaks
+
+### Editing text around code blocks
+
+There could be situations when there is no obvious way to set the caret before or after a block of code and type. This can happen when the code block is preceded or followed by a widget (e.g. a table) or when the code block is the first or the last child of the document (or both).
+
+* To type **before the code block**: Put the selection at the beginning of the first line of the code block and press <kbd>Enter</kbd>. Move the selection to the empty line that has been created and press <kbd>Enter</kbd> again. A new paragraph will be created before the code block you can type in.
+* To type **after the code block**: Put the selection at the end of the last line of the code block and press <kbd>Enter</kbd> twice. A new paragraph will be created after the code block you can type in.
+
+### Changing line indentation
+
+You can change the indentation of the code using keyboard shortcuts and toolbar buttons:
+
+* To **increase** indentation: Select the line (or lines) you want to indent. Hit the <kbd>Tab</kbd> key or press the "Increase indent" button in the toolbar.
+* To **decrease** indentation: Select the line (or lines) the indent should decrease. Hit the <kbd>Shift</kbd>+<kbd>Tab</kbd> keys or press the "Decrease indent" button in the toolbar.
+
+<info-box>
+	The indentation created this way can be changed. Use the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`} configuration to choose some other character (or characters) of your preference (e.g. four spaces). By default, the indentation changes by a single tab (`\t`) character.
+</info-box>
+
+<info-box>
+	You can disable the indentation tools and their associated keystrokes altogether by setting the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`}  configuration `false`.
+</info-box>
+
+### Preserving line indentation
+
+To speed up the editing, when typing in a code block, the indentation of the current line is preserved when you hit <kbd>Enter</kbd> and create a new line. If you want to change the indentation of the new line, take a look at [some easy ways to do that](#changing-line-indentation).
+
+## Installation
+
+To add this feature to your editor install the [`@ckeditor/ckeditor5-code-block`](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-code-block
+```
+
+And add it to your plugin list and the toolbar configuration:
+
+```js
+import CodeBlock from '@ckeditor/ckeditor5-code-block/src/codeblock';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ CodeBlock, ... ],
+		toolbar: [ 'codeBlock', ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Common API
+
+The {@link module:code-block/codeblock~CodeBlock} plugin registers:
+
+* The `'codeBlock'` split button with a dropdown allowing to choose the language of the block,
+* The {@link module:code-block/codeblockcommand~CodeBlockCommand `'codeBlock'`} command.
+
+	The command converts selected editor content into a code block. If no content is selected, it creates a new code block at the place of the selection.
+
+	You can choose which language the code block is written in when executing the command. The language will be set in the editor model and reflected as a CSS class visible in the editing view and the editor (data) output:
+
+	```js
+	editor.execute( 'codeBlock', { language: 'css' } );
+	```
+
+	When executing the command, you can use languages defined by the {@link module:code-block/codeblock~CodeBlockConfig#languages `codeBlock.languages`} configuration. Make sure the `language` you use corresponds to the `class` property in the configuration object.
+
+	The default list of languages is as follows:
+
+	```js
+	codeBlock.languages: [
+		{ class: 'language-plaintext', label: 'Plain text' }, // The default language.
+		{ class: 'language-c', label: 'C' },
+		{ class: 'language-cs', label: 'C#' },
+		{ class: 'language-cpp', label: 'C++' },
+		{ class: 'language-css', label: 'CSS' },
+		{ class: 'language-diff', label: 'Diff' },
+		{ class: 'language-xml', label: 'HTML/XML' },
+		{ class: 'language-java', label: 'Java' },
+		{ class: 'language-javascript', label: 'JavaScript' },
+		{ class: 'language-php', label: 'PHP' },
+		{ class: 'language-python', label: 'Python' },
+		{ class: 'language-ruby', label: 'Ruby' },
+		{ class: 'language-typescript', label: 'TypeScript' },
+	]
+	```
+
+	**Note**: If you execute a command with a specific `language` when the selection is anchored in a code block and use the additional `forceValue: true` parameter, it will update the language of this particular block.
+
+	```js
+	editor.execute( 'codeBlock', { language: 'java', forceValue: true } );
+	```
+
+	**Note**: If the selection is already in a code block, executing the command will convert the block back into plain paragraphs.
+* The {@link module:code-block/indentcodeblockcommand~IndentCodeBlockCommand `'indentCodeBlock'`} and {@link module:code-block/outdentcodeblockcommand~OutdentCodeBlockCommand `'outdentCodeBlock'`} commands.
+
+	Both commands are used by the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keystrokes as described in [one of the chapters](#changing-line-indentation):
+
+	* The former is enabled when the selection is anchored anywhere in the code block and allows increasing the indentation of the lines of code. The indentation character (sequence) is configurable using the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`} configuration.
+	* The later is enabled when the indentation of any code lines within the selection can be decreased. Executing it will remove the indentation character (sequence) from those lines, as configured by {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`}.
+
+<info-box>
+	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-code-block.
diff --git a/lang/contexts.json b/lang/contexts.json
@@ -0,0 +1,4 @@
+{
+	"Insert code block": "A label of the button that allows inserting a new code block into the editor content.",
+	"Plain text": "A language of the code block in the editor content when no specific programming language is associated with it."
+}
diff --git a/package.json b/package.json
@@ -10,11 +10,22 @@
     "ckeditor5-plugin"
   ],
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "^12.3.0",
-    "@ckeditor/ckeditor5-utils": "^14.0.0",
+    "@ckeditor/ckeditor5-core": "^15.0.0",
+    "@ckeditor/ckeditor5-enter": "^15.0.0",
+    "@ckeditor/ckeditor5-ui": "^15.0.0",
+    "@ckeditor/ckeditor5-utils": "^15.0.0",
     "lodash-es": "^4.17.10"
   },
   "devDependencies": {
+    "@ckeditor/ckeditor5-alignment": "^15.0.0",
+    "@ckeditor/ckeditor5-autoformat": "^15.0.0",
+    "@ckeditor/ckeditor5-basic-styles": "^15.0.0",
+    "@ckeditor/ckeditor5-block-quote": "^15.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^15.0.0",
+    "@ckeditor/ckeditor5-engine": "^15.0.0",
+    "@ckeditor/ckeditor5-indent": "^15.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^15.0.0",
+    "@ckeditor/ckeditor5-undo": "^15.0.0",
     "eslint": "^5.5.0",
     "eslint-config-ckeditor5": "^2.0.0",
     "husky": "^1.3.1",