Explorar el Código

Docs: Update documentation.

Maciej Gołaszewski hace 8 años
padre
commit
fc60b025c8

+ 14 - 32
packages/ckeditor5-highlight/src/highlightcommand.js

@@ -10,38 +10,12 @@
 import Command from '@ckeditor/ckeditor5-core/src/command';
 
 /**
- * The highlight command.
+ * The highlight command. It is used by the {@link module:highlight/highlight~HighlightEditing highlight feature}
+ * to apply text highlighting.
  *
  * @extends module:core/command~Command
  */
 export default class HighlightCommand extends Command {
-	/**
-	 * Creates an instance of the command.
-	 *
-	 * @param {module:core/editor/editor~Editor} editor The editor instance.
-	 * @param {'left'|'right'|'center'|'justify'} type Highlight type to be handled by this command.
-	 */
-	constructor( editor, type ) {
-		super( editor );
-
-		/**
-		 * The type of the list created by the command.
-		 *
-		 * @readonly
-		 * @member {'left'|'right'|'center'|'justify'}
-		 */
-		this.type = type;
-
-		/**
-		 * A flag indicating whether the command is active, which means that the selection starts in a block
-		 * that has defined highlight of the same type.
-		 *
-		 * @observable
-		 * @readonly
-		 * @member {Boolean} #value
-		 */
-	}
-
 	/**
 	 * @inheritDoc
 	 */
@@ -57,15 +31,15 @@ export default class HighlightCommand extends Command {
 	 *
 	 * @protected
 	 * @param {Object} [options] Options for the executed command.
-	 * @param {String} options.class Name of marker class name.
+	 * @param {String} options.class Name of highlighter class.
 	 * @param {module:engine/model/batch~Batch} [options.batch] A batch to collect all the change steps.
 	 * A new batch will be created if this option is not set.
 	 */
 	execute( options = {} ) {
 		const doc = this.editor.document;
 		const selection = doc.selection;
-		const value = options.class;
 
+		// Do not apply highlight no collapsed selection.
 		if ( selection.isCollapsed ) {
 			return;
 		}
@@ -75,8 +49,8 @@ export default class HighlightCommand extends Command {
 			const batch = options.batch || doc.batch();
 
 			for ( const range of ranges ) {
-				if ( value ) {
-					batch.setAttribute( range, 'highlight', value );
+				if ( options.class ) {
+					batch.setAttribute( range, 'highlight', options.class );
 				} else {
 					batch.removeAttribute( range, 'highlight' );
 				}
@@ -84,3 +58,11 @@ export default class HighlightCommand extends Command {
 		} );
 	}
 }
+
+/**
+ * Holds current highlight class. If there is no highlight in selection then value will be undefined.
+ *
+ * @observable
+ * @readonly
+ * @member {undefined|String} HighlightCommand#value
+ */

+ 51 - 1
packages/ckeditor5-highlight/src/highlightediting.js

@@ -9,13 +9,16 @@
 
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 
-import HighlightCommand from './highlightcommand';
 import buildViewConverter from '@ckeditor/ckeditor5-engine/src/conversion/buildviewconverter';
 import buildModelConverter from '@ckeditor/ckeditor5-engine/src/conversion/buildmodelconverter';
 
 import AttributeElement from '@ckeditor/ckeditor5-engine/src/view/attributeelement';
 
+import HighlightCommand from './highlightcommand';
+
 /**
+ * The highlight editing feature. It introduces `highlight` command which allow to highlight selected text with defined 'marker' or 'pen'.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class HighlightEditing extends Plugin {
@@ -69,3 +72,50 @@ export default class HighlightEditing extends Plugin {
 		editor.commands.add( 'highlight', new HighlightCommand( editor ) );
 	}
 }
+
+/**
+ * Highlight option descriptor.
+ *
+ * @typedef {Object} module:highlight/highlightediting~HeadingOption
+ * @property {String} class The class which is used to differentiate highlighters.
+ * @property {String} title The user-readable title of the option.
+ * @property {String} color Color used for highlighter. Should be coherent with CSS class definition.
+ * @property {'marker'|'pen'} type The type of highlighter. Either "marker" - will use #color as background name
+ * of the view element that will be used to represent the model element in the view.
+ */
+
+/**
+ * The configuration of the {@link module:highlight/highlightediting~HighlightEditing Highlight feature}.
+ *
+ * Read more in {@link module:highlight/highlightediting~HighlightEditingConfig}.
+ *
+ * @member {module:highlight/highlightediting~HighlightEditingConfig} module:core/editor/editorconfig~EditorConfig#alignment
+ */
+
+/**
+ * The configuration of the {@link module:highlight/highlightediting~HighlightEditing Highlight feature}.
+ *
+ *        ClassicEditor
+ *            .create( editorElement, {
+ * 				highlight:  ... // Highlight feature config.
+ *			} )
+ *            .then( ... )
+ *            .catch( ... );
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface HighlightEditingConfig
+ */
+
+/**
+ * Available highlighters options.
+ *
+ * There are two types of highlighters:
+ * - 'marker' - rendered as `<mark>` element with defined background color.
+ * - 'pen' - rendered as `<mark>` element with defined foreground (font) color.
+ *
+ * Note: Each highlighter must have it's own CSS class defined to properly match content data. Also it is advised
+ * that color value should match the values defined in content CSS stylesheet.
+ *
+ * @member {Array.<module:heading/heading~HeadingOption>} module:heading/heading~HeadingConfig#options
+ */

+ 0 - 7
packages/ckeditor5-highlight/src/highlightui.js

@@ -30,11 +30,4 @@ export default class HighlightUI extends Plugin {
 	static get pluginName() {
 		return 'HighlightUI';
 	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		// TODO
-	}
 }