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

Docs: Block quote documentation. [skip ci]

godai78 преди 5 години
родител
ревизия
63bc501251

+ 26 - 0
packages/ckeditor5-block-quote/docs/_snippets/features/block-quote.html

@@ -0,0 +1,26 @@
+<div id="snippet-block-quote">
+	<h1 style="text-align:center"><span style="font-family:Arial">The Famous Einstein Quote that never was</span></h1>
+	
+	<blockquote>
+	<p><span style="font-size:11pt"><span style="font-family:Arial">Everybody is a genius. But if you judge a fish by its ability to climb a tree, it will live its whole life believing that it is stupid.</span></span></p>
+	
+	<p><span style="font-size:11pt"><span style="font-family:Arial">Albert Einstein</span></span></p>
+	</blockquote>
+	
+	<p><span style="font-size:11pt"><span style="font-family:Arial">All of us - well, maybe most of us - have encountered the quote above in the past few years. It is mostly popular on Facebook and other social networks, where people share it aplenty. No wonder, as this sounds great, it sounds smart, it is neat and, well, let&rsquo;s be frank - Albert is one hell of a figure!</span></span></p>
+	
+	<p><span style="font-size:11pt"><span style="font-family:Arial">The truth, however, is not as neat, not as great and people who mindlessly forward the quote are not as smart. Because, in fact, Einstein has never said that. It comes from a 2004 book &ldquo;The Rhythm of Life: Living Every Day with Passion and Purpose&rdquo; by Mathew Kelly, published almost 50 years after Albert&rsquo;s death in 1955.</span></span></p>
+	
+	<p><span style="font-size:11pt"><span style="font-family:Arial">He was, most probably, inspired by an essay by Amos E. Dolbear of Tufts titled &ldquo;An Educational Allegory&rdquo;, describing animals educated to work on their weakest features instead of their strongest ones. So an eagle was made to run, a penguin was forced to fly and so on. There is also the 1903 &ldquo;Jungle School Boards&rdquo; fable from an Illinois newspaper in which a monkey, a kangaroo and an elephant cannot agree on the curriculum for their animal school - should little animals be taught tree-climbing, jumping or looking wise?&nbsp;</span></span></p>
+	
+	<p><span style="font-size:11pt"><span style="font-family:Arial">In the late 1940s, something that appears to be an amalgam of the two was published and later reprinted with various changes in 1960s. The idea evolved for decades and got mixed up with a few other quotes about being a genius originating back to the 1970s. Finally, Kelly wrote in his 2004 book:</span></span></p>
+	
+	<blockquote>
+	<p><span style="font-size:11pt"><span style="font-family:Arial">Albert Einstein wrote, &ldquo;Everybody is a genius. But if you judge a fish by its ability to climb a tree, it will live its whole life believing that it is stupid.&rdquo; The question I have for you at this point of our journey together is, &ldquo;What is your genius?&rdquo;</span></span></p>
+	</blockquote>
+	
+	<p><span style="font-size:11pt"><span style="font-family:Arial">Why he attributed this to Albert Einstein remains unclear. The fact is, the quote got popular. But apparently not everybody is a genius when it comes to fact-checking and sources...</span></span><br />
+	&nbsp;</p>
+	
+</div>
+

+ 60 - 0
packages/ckeditor5-block-quote/docs/_snippets/features/block-quote.js

@@ -0,0 +1,60 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment';
+
+ClassicEditor.builtinPlugins.push( Alignment );
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-block-quote' ), {
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'|',
+				'alignment',
+				'|',
+				'blockQuote',
+				'outdent',
+				'indent',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+
+		// The "Print editor data" button logic.
+		document.querySelector( '#print-data-action' ).addEventListener( 'click', () => {
+			const snippetCSSElement = [ ...document.querySelectorAll( 'link' ) ]
+				.find( linkElement => linkElement.href.endsWith( 'snippet.css' ) );
+
+			const iframeElement = document.querySelector( '#print-data-container' );
+
+			iframeElement.srcdoc = '<html>' +
+				'<head>' +
+					`<title>${ document.title }</title>` +
+					`<link rel="stylesheet" href="${ snippetCSSElement.href }" type="text/css">` +
+				'</head>' +
+				'<body class="ck-content">' +
+					editor.getData() +
+					'<script>' +
+						'window.addEventListener( \'DOMContentLoaded\', () => { window.print(); } );' +
+					'</script>' +
+				'</body>' +
+				'</html>';
+		} );
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 69 - 0
packages/ckeditor5-block-quote/docs/features/block-quote.md

@@ -0,0 +1,69 @@
+---
+category: features
+menu-title: Block quote
+---
+
+# Block quote
+
+The {@link module:block-quote/blockquote~BlockQuote} feature implements block quote support to easily include quotations and passages in the rich-text content. This provides attractive ways to draw the readers' attention to selected parts of text, help organize the content in a structured, elegant way and manage the flow better.
+
+## Demo
+
+Use the editor to see the {@link module:block-quote/blockquote~BlockQuote} plugin in action.
+
+{@snippet features/block-quote}
+
+## Installation
+
+To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-block-quote`](https://www.npmjs.com/package/@ckeditor/ckeditor5-block-quote) package:
+
+```plaintext
+npm install --save @ckeditor/ckeditor5-block-quote
+```
+
+And add it to your plugin list configuration:
+
+```js
+import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ BlockQuote, ... ],
+		toolbar: [ 'blockQuote', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Related features
+
+Here are some other CKEditor 5 features that you can use similarly to the block quote plugin for an all-around paged editing experience:
+
+* The {@link features/indent indentation feature} allows you to control the text position in a similar manner.
+* The {@link features/code-blocks code blocks} allow for insertion of various code listings.
+
+## Common API - TODO: check correctness
+ 
+The {@link module:block-quote/blockquote~BlockQuote} plugin registers:
+
+* the UI button component (`'blockQuote'`) implemented by {@link module:block-quote/blockquoteui~BlockQuoteUI block quote UI feature},
+* the `'blockQuote'` command implemented by {@link module:block-quote/blockquoteediting~BlockQuoteEditing block quote editing feature}.
+
+The command can be executed using the {@link module:core/editor/editor~Editor#execute `editor.execute()`} method:
+
+```js
+// Applies block quote to the selected content.
+editor.execute( 'blockQuote' );
+```
+
+<info-box>
+	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-block-quote.