Browse Source

Docs: Another example in the extending content guide.

Aleksander Nowodzinski 6 years ago
parent
commit
c61a8fca2a

+ 14 - 0
packages/ckeditor5-engine/docs/_snippets/framework/extending-content-add-heading-class.html

@@ -0,0 +1,14 @@
+<style>
+	.ck-content h2.my-heading {
+		font-family: Georgia, Times, Times New Roman, serif;
+		border-left: 6px solid #fd0000;
+		padding-left: .8em;
+		padding: .1em .8em;
+	}
+</style>
+
+<div id="snippet-heading-class">
+	<h2>Heading with <code>.my-heading</code> class</h2>
+	<h3>Regular heading</h3>
+	<p>Some content.</p>
+</div>

+ 33 - 0
packages/ckeditor5-engine/docs/_snippets/framework/extending-content-add-heading-class.js

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+function AddClassToAllHeading1( editor ) {
+	editor.conversion.for( 'downcast' ).add( dispatcher => {
+		dispatcher.on( 'insert:heading1', ( evt, data, conversionApi ) => {
+			const viewWriter = conversionApi.writer;
+
+			viewWriter.addClass( 'my-heading', conversionApi.mapper.toViewElement( data.item ) );
+		}, { priority: 'low' } );
+	} );
+}
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-heading-class' ), {
+		cloudServices: CS_CONFIG,
+		extraPlugins: [ AddClassToAllHeading1 ],
+		toolbar: {
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 2 - 1
packages/ckeditor5-engine/docs/_snippets/framework/extending-content-add-unsafe-link-class.html

@@ -1,7 +1,8 @@
 <style>
 	.unsafe-link {
 		padding: 0 2px;
-		outline: 1px dashed #ff0000;
+		outline: 2px dashed red;
+		background: #ffff00;
 	}
 </style>
 

+ 71 - 10
packages/ckeditor5-engine/docs/framework/guides/deep-dive/extending-content.md

@@ -7,7 +7,7 @@ menu-title: Extending editor content
 
 # Extending editor content
 
-This article will help you learn how to extend (customize) the content produced by the rich text editor, for instance, with your custom attributes and CSS classes. It requires some basic knowledge about the editor model and editing view layers you can find in the {@link framework/guides/architecture/editing-engine introduction to the editing engine architecture}.
+This article will help you learn how to quickly extend (customize) the content produced by the core rich text editor features, for instance, with how to add your custom attributes and CSS classes to the output data. It requires some basic knowledge about the editor model and editing view layers you can find in the {@link framework/guides/architecture/editing-engine introduction to the editing engine architecture}.
 
 ## Basics of editor conversion
 
@@ -17,10 +17,12 @@ TODO (converters, pipelines, block elements, inline attributes)
 
 Customisations in the examples are brought by plugins loaded by the editor. For the sake of simplicity, all examples use the same {@link module:editor-classic/classiceditor~ClassicEditor `ClassicEditor`} but keep in mind that code snippets will work with other editors too.
 
-### Extending editor output ("downcast")
+### Extending editor output ("downcast" only)
 
 In this section, we will focus on customization to the "downcast" pipeline of the editor, which transforms data from the model to the editing view and the output data. The following examples do not customize the model and do not process the (input) data — you can picture them as post–processors (filters) applied to the output only.
 
+If you want to learn how to load some extra content (element, attributes, classes) into the editor, check out the [next chapter](#enabling-custom-attributes-in-the-editor-input-upcast) of this guide.
+
 <info-box>
 	You can create separate converters for data and editing (downcast) pipelines. The former (`dataDowncast`) will customize the data in the editor output (e.g. when {@link module:core/editor/utils/dataapimixin~DataApi#getData `editor.getData()`}) and the later (`editingDowncast`) will only work for the content of the editor when editing.
 
@@ -44,7 +46,7 @@ In this section, we will focus on customization to the "downcast" pipeline of th
 	```
 </info-box>
 
-#### Adding a CSS class to all inline elements (e.g. links)
+#### Adding a CSS class to inline elements
 
 In this example all links (`<a href="...">...</a>`) get the `.my-green-link` CSS class. That includes all links in the editor output (`editor.getData()`) and all links in the edited content (existing and future ones).
 
@@ -52,7 +54,7 @@ In this example all links (`<a href="...">...</a>`) get the `.my-green-link` CSS
 
 {@snippet framework/extending-content-add-link-class}
 
-##### Code snippets
+##### Code
 
 Adding a custom CSS class to all links is made by a custom converter plugged into the downcast pipeline, following the default converters brought by the {@link features/link Link} feature:
 
@@ -112,7 +114,7 @@ Add some CSS styles for `.my-green-link` to see the customization in action:
 }
 ```
 
-#### Adding an HTML attribute to certain inline elements (e.g. links)
+#### Adding an HTML attribute to certain inline elements
 
 In this example all links (`<a href="...">...</a>`) which do not have "ckeditor.com" in their `href="..."` get the `target="_blank"` attribute. That includes all links in the editor output (`editor.getData()`) and all links in the edited content (existing and future ones).
 
@@ -122,7 +124,7 @@ In this example all links (`<a href="...">...</a>`) which do not have "ckeditor.
 
 **Note:** Edit the URL of the links including "ckeditor.com" and other domains to see them marked as "internal" or "external".
 
-##### Code snippet
+##### Code
 
 Adding the `target` attribute to all "external" links is made by a custom converter plugged into the downcast pipeline, following the default converters brought by the {@link features/link Link} feature:
 
@@ -182,7 +184,7 @@ a[target="_blank"]::after {
 }
 ```
 
-#### Adding a CSS class to certain inline elements (e.g. links)
+#### Adding a CSS class to certain inline elements
 
 In this example all links (`<a href="...">...</a>`) which do not have "https://" in their `href="..."` attribute get the `.unsafe-link` CSS class. That includes all links in the editor output (`editor.getData()`) and all links in the edited content (existing and future ones).
 
@@ -192,7 +194,7 @@ In this example all links (`<a href="...">...</a>`) which do not have "https://"
 
 **Note:** Edit the URL of the links using "http://" or "https://" to see see them marked as "safe" or "unsafe".
 
-##### Code snippet
+##### Code
 
 Adding the `.unsafe-link` CSS class to all "unsafe" links is made by a custom converter plugged into the downcast pipeline, following the default converters brought by the {@link features/link Link} feature:
 
@@ -248,8 +250,67 @@ Add some CSS styles for "unsafe" to make them visible:
 
 ```css
 .unsafe-link {
-	color: #ff0000;
-	outline: 1px dashed #ff0000;
+	padding: 0 2px;
+	outline: 2px dashed red;
+	background: #ffff00;
+}
+```
+
+#### Adding a CSS class to block elements
+
+In this example all second–level headings (`<h2>...</h2>`) get the `.my-heading` CSS class. That includes all heading elements in the editor output (`editor.getData()`) and in the edited content (existing and future ones).
+
+##### Demo
+
+{@snippet framework/extending-content-add-heading-class}
+
+##### Code
+
+Adding a custom CSS class to all `<h2>...</h2>` elements is made by a custom converter plugged into the downcast pipeline, following the default converters brought by the {@link features/headings Headings} feature:
+
+<info-box>
+	The `heading1` element in the model corresponds to `<h2>...</h2>` in the output HTML because in the default {@link features/headings#configuring-heading-levels headings feature configuration} `<h1>...</h1>` is reserved for the top–most heading of a webpage.
+</info-box>
+
+```js
+// This plugin brings a customization to the downcast pipeline of the editor.
+function AddClassToAllHeading1( editor ) {
+	// Both data and editing pipelines are affected by this conversion.
+	editor.conversion.for( 'downcast' ).add( dispatcher => {
+		// Headings are represented in the model as a "heading1" element.
+		// Use the "low" listener priority to apply the changes after the Headings feature.
+		dispatcher.on( 'insert:heading1', ( evt, data, conversionApi ) => {
+			const viewWriter = conversionApi.writer;
+
+			viewWriter.addClass( 'my-heading', conversionApi.mapper.toViewElement( data.item ) );
+		}, { priority: 'low' } );
+	} );
+}
+```
+
+Activate the plugin in the editor:
+
+```js
+ClassicEditor
+	.create( ..., {
+		extraPlugins: [ AddClassToAllHeading1 ],
+	} )
+	.then( editor => {
+		// ...
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
+```
+
+Add some CSS styles for `.my-heading` to see the customization in action:
+
+```css
+.my-heading {
+	font-family: Georgia, Times, Times New Roman, serif;
+	border-left: 6px solid #fd0000;
+	padding-left: .8em;
+	padding: .1em .8em;
 }
 ```