8
0

codeblock.js 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module code-block/codeblock
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import CodeBlockEditing from './codeblockediting';
  10. import CodeBlockUI from './codeblockui';
  11. /**
  12. * The code block plugin.
  13. *
  14. * For more information about this feature check the {@glink api/code-block package page} and the
  15. * {@glink features/code-blocks code block feature guide}.
  16. *
  17. * This is a "glue" plugin that loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
  18. * and the {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
  19. *
  20. * @extends module:core/plugin~Plugin
  21. */
  22. export default class CodeBlock extends Plugin {
  23. /**
  24. * @inheritDoc
  25. */
  26. static get requires() {
  27. return [ CodeBlockEditing, CodeBlockUI ];
  28. }
  29. /**
  30. * @inheritDoc
  31. */
  32. static get pluginName() {
  33. return 'CodeBlock';
  34. }
  35. }
  36. /**
  37. * The configuration of the {@link module:code-block/codeblock~CodeBlock} feature.
  38. *
  39. * Read more in {@link module:code-block/codeblock~CodeBlockConfig}.
  40. *
  41. * @member {module:code-block/codeblock~CodeBlockConfig} module:core/editor/editorconfig~EditorConfig#codeBlock
  42. */
  43. /**
  44. * The configuration of the {@link module:code-block/codeblock~CodeBlock code block feature}.
  45. *
  46. * ClassicEditor
  47. * .create( editorElement, {
  48. * codeBlock: ... // The code block feature configuration.
  49. * } )
  50. * .then( ... )
  51. * .catch( ... );
  52. *
  53. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  54. *
  55. * @interface CodeBlockConfig
  56. */
  57. /**
  58. * The code block language descriptor. See {@link module:code-block/codeblock~CodeBlockConfig#languages} to learn more.
  59. *
  60. * {
  61. * language: 'javascript',
  62. * label: 'JavaScript'
  63. * }
  64. *
  65. * @typedef {Object} module:code-block/codeblock~CodeBlockLanguageDefinition
  66. * @property {String} language The name of the language that will be stored in the model attribute. Also, when `class`
  67. * is not specified, it will be used to create the CSS class associated with the language (prefixed by "language-").
  68. * @property {String} label The human–readable label associated with the language and displayed in the UI.
  69. * @property {String} [class] The CSS class associated with the language. When not specified the `language`
  70. * property is used to create a class prefixed by "language-".
  71. */
  72. /**
  73. * The list of code languages available in the user interface to choose for a particular code block.
  74. *
  75. * The language of the code block is represented as a CSS class (by default prefixed by "language-") set on the
  76. * `<code>` element, both when editing and in the editor data. The CSS class associated with the language
  77. * can be used by third–party code syntax highlighters to detect and apply the correct highlighting.
  78. *
  79. * For instance, this language configuration:
  80. *
  81. * ClassicEditor
  82. * .create( document.querySelector( '#editor' ), {
  83. * codeBlock: {
  84. * languages: [
  85. * // ...
  86. * { language: 'javascript', label: 'JavaScript' },
  87. * // ...
  88. * ]
  89. * }
  90. * } )
  91. * .then( ... )
  92. * .catch( ... );
  93. *
  94. * will result in the following structure of JavaScript code blocks in the editor editing and data:
  95. *
  96. * <pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
  97. *
  98. * You can customize the CSS class by specifying an optional `class` property in the language definition:
  99. *
  100. * ClassicEditor
  101. * .create( document.querySelector( '#editor' ), {
  102. * codeBlock: {
  103. * languages: [
  104. * // Do not render the CSS class for the plain text code blocks.
  105. * { language: 'plaintext', label: 'Plain text', class: '' },
  106. *
  107. * // Use the "php-code" class for PHP code blocks.
  108. * { language: 'php', label: 'PHP', class: 'php-code' },
  109. *
  110. * // Use the "js" class for JavaScript code blocks.
  111. * { language: 'javascript', label: 'JavaScript', class: 'js' },
  112. *
  113. * // Python code blocks will have the default "language-python" CSS class.
  114. * { language: 'python', label: 'Python' }
  115. * ]
  116. * }
  117. * } )
  118. * .then( ... )
  119. * .catch( ... );
  120. *
  121. * The default value of the language configuration is as follows:
  122. *
  123. * languages: [
  124. * { language: 'plaintext', label: 'Plain text' }, // The default language.
  125. * { language: 'c', label: 'C' },
  126. * { language: 'cs', label: 'C#' },
  127. * { language: 'cpp', label: 'C++' },
  128. * { language: 'css', label: 'CSS' },
  129. * { language: 'diff', label: 'Diff' },
  130. * { language: 'xml', label: 'HTML/XML' },
  131. * { language: 'java', label: 'Java' },
  132. * { language: 'javascript', label: 'JavaScript' },
  133. * { language: 'php', label: 'PHP' },
  134. * { language: 'python', label: 'Python' },
  135. * { language: 'ruby', label: 'Ruby' },
  136. * { language: 'typescript', label: 'TypeScript' },
  137. * ]
  138. *
  139. * **Note**: The first language defined in the configuration is considered the default one. This means it will be
  140. * applied to code blocks loaded from the data that have no CSS `class` specified (or no matching `class` in the configuration).
  141. * It will also be used when creating new code blocks using the main UI button. By default it is "Plain text".
  142. *
  143. * @member {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} module:code-block/codeblock~CodeBlockConfig#languages
  144. */
  145. /**
  146. * A sequence of characters inserted or removed from the code block lines when its indentation
  147. * is changed by the user, for instance, using <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.
  148. *
  149. * The default value is a single tab character (" ", `\u0009` in Unicode).
  150. *
  151. * This configuration is used by `indentCodeBlock` and `outdentCodeBlock` commands (instances of
  152. * {@link module:code-block/indentcodeblockcommand~IndentCodeBlockCommand}).
  153. *
  154. * **Note**: Setting this configuration to `false` will disable the code block indentation commands
  155. * and associated keystrokes.
  156. *
  157. * @member {String} module:code-block/codeblock~CodeBlockConfig#indentSequence
  158. */