codeblock.js 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  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}.
  15. *
  16. * This is a "glue" plugin which loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
  17. * and {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
  18. *
  19. * @extends module:core/plugin~Plugin
  20. */
  21. export default class CodeBlock extends Plugin {
  22. /**
  23. * @inheritDoc
  24. */
  25. static get requires() {
  26. return [ CodeBlockEditing, CodeBlockUI ];
  27. }
  28. /**
  29. * @inheritDoc
  30. */
  31. static get pluginName() {
  32. return 'CodeBlock';
  33. }
  34. }
  35. /**
  36. * The configuration of the {@link module:code-block/codeblock~CodeBlock} feature.
  37. *
  38. * Read more in {@link module:code-block/codeblock~CodeBlockConfig}.
  39. *
  40. * @member {module:code-block/codeblock~CodeBlockConfig} module:core/editor/editorconfig~EditorConfig#codeBlock
  41. */
  42. /**
  43. * The configuration of the {@link module:code-block/codeblock~CodeBlock code block feature}.
  44. *
  45. * ClassicEditor
  46. * .create( editorElement, {
  47. * codeBlock: ... // Code block feature configuration.
  48. * } )
  49. * .then( ... )
  50. * .catch( ... );
  51. *
  52. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  53. *
  54. * @interface CodeBlockConfig
  55. */
  56. /**
  57. * The code block language descriptor. See {@link module:code-block/codeblock~CodeBlockConfig#languages} to learn more.
  58. *
  59. * {
  60. * class: 'language-javascript',
  61. * label: 'JavaScript'
  62. * }
  63. *
  64. * @typedef {Object} module:code-block/codeblock~CodeBlockLanguageDefinition
  65. * @property {String} label The human–readable label associated with the language displayed in the UI.
  66. * @property {String} class The CSS class associated with the language.
  67. */
  68. /**
  69. * The list of code languages available in the user interface to choose for a particular code block.
  70. * The language of the code block is represented as a CSS class set on the `<code>` element, both
  71. * when editing and in the editor data:
  72. *
  73. * <pre><code class="javascript">window.alert( 'Hello world!' )</code></pre>
  74. *
  75. * The CSS class associated with the language can be then used by third–party code syntax
  76. * highlighters to detect and apply the correct highlighting. Use this configuration
  77. * to match requirements of your integration:
  78. *
  79. * ClassicEditor
  80. * .create( editorElement, {
  81. * codeBlock: {
  82. * languages: [
  83. * { class: 'language-plaintext', label: 'Plain text' }, // The default language.
  84. * { class: 'language-php', label: 'PHP' },
  85. * { class: 'language-java', label: 'Java' },
  86. * { class: 'language-javascript', label: 'JavaScript' },
  87. * { class: 'language-python', label: 'Python' }
  88. * ]
  89. * }
  90. * } )
  91. * .then( ... )
  92. * .catch( ... );
  93. *
  94. * The default value is as follows:
  95. *
  96. * languages: [
  97. * { class: 'language-plaintext', label: 'Plain text' }, // The default language.
  98. * { class: 'language-c', label: 'C' },
  99. * { class: 'language-cs', label: 'C#' },
  100. * { class: 'language-cpp', label: 'C++' },
  101. * { class: 'language-css', label: 'CSS' },
  102. * { class: 'language-diff', label: 'Diff' },
  103. * { class: 'language-xml', label: 'HTML/XML' },
  104. * { class: 'language-java', label: 'Java' },
  105. * { class: 'language-javascript', label: 'JavaScript' },
  106. * { class: 'language-php', label: 'PHP' },
  107. * { class: 'language-python', label: 'Python' },
  108. * { class: 'language-ruby', label: 'Ruby' },
  109. * { class: 'language-typescript', label: 'TypeScript' },
  110. * ]
  111. *
  112. * **Note**: The first language defined in the configuration is considered the default one. This means it will be
  113. * applied to code blocks loaded from data that have no CSS `class` specified (or no matching `class` in the config).
  114. * It will also be used when creating new code blocks using the main UI button. By default it is "Plain text".
  115. *
  116. * @member {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} module:code-block/codeblock~CodeBlockConfig#languages
  117. */
  118. /**
  119. * A sequence of characters inserted or removed from the code block lines when its indentation
  120. * is changed by the user, for instance, using <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.
  121. *
  122. * The default value is a single tab character (" ", `\u0009` in Unicode).
  123. *
  124. * This configuration is used by `indentCodeBlock` and `outdentCodeBlock` commands (instances of
  125. * {@link module:code-block/indentcodeblockcommand~IndentCodeBlockCommand}).
  126. *
  127. * **Note**: Setting this configuration to `false` will disable the code block indentation commands
  128. * and associated keystrokes.
  129. *
  130. * @member {String} module:code-block/codeblock~CodeBlockConfig#indentSequence
  131. */