Преглед на файлове

Docs: Added 'Loading a content with a custom attribute' section. [skip ci]

Aleksander Nowodzinski преди 7 години
родител
ревизия
8c004958c9

+ 10 - 0
packages/ckeditor5-engine/docs/_snippets/framework/extending-content-allow-link-target.html

@@ -0,0 +1,10 @@
+<style>
+	#snippet-link-target + .ck-editor .ck-content a[target="_blank"]::after {
+		content: '\29C9';
+	}
+</style>
+
+<div id="snippet-link-target">
+	<p><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a">Links</a> with a <code>target</code> attribute can be loaded into this <a href="https://ckeditor.com" target="_blank">editor</a>.</p>
+	<p><b>Note</b>: Links with the <code>target="_blank"</code> have a "&#10697;" symbol.</p>
+</div>

+ 44 - 0
packages/ckeditor5-engine/docs/_snippets/framework/extending-content-allow-link-target.js

@@ -0,0 +1,44 @@
+/**
+ * @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 AllowLinkTarget( editor ) {
+	editor.model.schema.extend( '$text', { allowAttributes: 'linkTarget' } );
+
+	editor.conversion.for( 'downcast' ).attributeToElement( {
+		model: 'linkTarget',
+		view: ( attributeValue, writer ) => {
+			return writer.createAttributeElement( 'a', { target: attributeValue }, { priority: 5 } );
+		},
+		converterPriority: 'low'
+	} );
+
+	editor.conversion.for( 'upcast' ).attributeToAttribute( {
+		view: {
+			name: 'a',
+			key: 'target'
+		},
+		model: 'linkTarget',
+		converterPriority: 'low'
+	} );
+}
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-link-target' ), {
+		cloudServices: CS_CONFIG,
+		extraPlugins: [ AllowLinkTarget ],
+		toolbar: {
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 67 - 2
packages/ckeditor5-engine/docs/framework/guides/deep-dive/extending-content.md

@@ -11,7 +11,7 @@ This article will help you learn how to quickly extend (customize) the content p
 
 ## Basics of editor conversion
 
-TODO (converters, pipelines, block elements, inline attributes)
+TODO (converters, pipelines, block elements, inline attributes).
 
 ## Examples
 
@@ -314,4 +314,69 @@ Add some CSS styles for `.my-heading` to see the customization in action:
 }
 ```
 
-### Enabling custom attributes in the editor input ("upcast")
+### Loading custom content into the editor ("upcast")
+
+TODO.
+
+#### Loading a content with a custom attribute
+
+In this example links (`<a href="...">...</a>`) loaded in editor content will preserve their `target` attribute, which is not supported by the {@link features/link Link} feature. The DOM `target` attribute will be stored in the editor model as a `linkTarget` attribute.
+
+Unlike the [downcast–only solution](#adding-an-html-attribute-to-certain-inline-elements), this approach does not change the content loaded into the editor. Links without the `target` attribute will not get one and links with the attribute will preserve its value.
+
+##### Demo
+
+{@snippet framework/extending-content-allow-link-target}
+
+##### Code
+
+Allowing the `target` attribute in the editor is made by two custom converters plugged into the downcast and upcast pipelines, following the default converters brought by the {@link features/link Link} feature:
+
+```js
+function AllowLinkTarget( editor ) {
+	// Allow the "linkTarget" attribute in the editor model.
+	editor.model.schema.extend( '$text', { allowAttributes: 'linkTarget' } );
+
+	// Tell the editor that the model "linkTarget" attribute converts into <a target="..."></a>
+	editor.conversion.for( 'downcast' ).attributeToElement( {
+		model: 'linkTarget',
+		view: ( attributeValue, writer ) => {
+			return writer.createAttributeElement( 'a', { target: attributeValue }, { priority: 5 } );
+		},
+		converterPriority: 'low'
+	} );
+
+	// Tell the editor that <a target="..."></a> converts into "linkTarget" attribute in the model.
+	editor.conversion.for( 'upcast' ).attributeToAttribute( {
+		view: {
+			name: 'a',
+			key: 'target'
+		},
+		model: 'linkTarget',
+		converterPriority: 'low'
+	} );
+}
+```
+
+Activate the plugin in the editor:
+
+```js
+ClassicEditor
+	.create( ..., {
+		extraPlugins: [ AllowLinkTarget ],
+	} )
+	.then( editor => {
+		// ...
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
+```
+
+Add some CSS styles for links with `target="_blank"` to mark them with with the "&#10697;" symbol:
+
+```css
+a[target="_blank"]::after {
+	content: '\29C9';
+}
+```