Parcourir la source

Docs: Improved the block toolbar guide by using the balloon editor instead of the classic editor to showcase the integration.

Aleksander Nowodzinski il y a 7 ans
Parent
commit
f869925d19

+ 3 - 0
packages/ckeditor5-ui/docs/_snippets/features/blocktoolbar.html

@@ -1,5 +1,8 @@
 <div id="snippet-block-toolbar">
 	<h2>The three greatest things you learn from traveling</h2>
+	<figure class="image image-style-side">
+		<img src="../assets/img/umbrellas.jpg" alt="Three Monks walking on ancient temple." />
+	</figure>
 	<p>Like all the great things on earth traveling teaches us by example. Here are some of the most precious lessons I’ve learned over the years of traveling.</p>
 	<h3>Appreciation of diversity</h3>
 	<p>Getting used to an entirely different culture can be challenging. While it’s also nice to learn about cultures online or from books, nothing comes close to experiencing cultural diversity in person. You learn to appreciate each and every single one of the differences while you become more culturally fluid.</p>

+ 11 - 5
packages/ckeditor5-ui/docs/_snippets/features/blocktoolbar.js

@@ -5,20 +5,26 @@
 
 /* globals console, window, document */
 
-import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import BalloonEditor from '@ckeditor/ckeditor5-build-balloon/src/ckeditor';
 import BlockToolbar from '@ckeditor/ckeditor5-ui/src/toolbar/block/blocktoolbar';
 import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
 import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
 import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
 
-ClassicEditor
+BalloonEditor
 	.create( document.querySelector( '#snippet-block-toolbar' ), {
-		plugins: ClassicEditor.builtinPlugins.concat( [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI ] ),
+		plugins: BalloonEditor.builtinPlugins.concat( [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI ] ),
 		toolbar: {
-			items: [ 'bold', 'italic', 'code', 'link', 'blockQuote', 'undo', 'redo' ],
+			items: [ 'bold', 'italic', 'code', 'link', 'undo', 'redo' ],
 			viewportTopOffset: 60
 		},
-		blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', '|', 'bulletedList', 'numberedList' ],
+		blockToolbar: [
+			'paragraph', 'heading1', 'heading2', 'heading3',
+			'|',
+			'bulletedList', 'numberedList',
+			'|',
+			'blockQuote', 'imageUpload'
+		],
 		cloudServices: CS_CONFIG
 	} )
 	.then( editor => {

+ 14 - 4
packages/ckeditor5-ui/docs/features/blocktoolbar.md

@@ -5,12 +5,12 @@ category: features
 
 The {@link module:ui/toolbar/block/blocktoolbar~BlockToolbar} plugin provides an additional [configurable](#configuration) toolbar on the left-hand side of the content area (the gutter). The toolbar is represented by a button with a pilcrow, or a paragraph mark, &#182;. It is positioned next to the block element that the selection is anchored to (e.g. a paragraph), following the caret as the user edits the content and navigates the document.
 
-Since the toolbar is always connected to the block of content, it naturally accomodates the features that modify entire blocks (e.g. create headers or paragraphs) rather than inline styles (e.g. bold, italic, etc.).
+The block toolbar comes in handy when the main editor toolbar cannot be accessed. It complements the {@link builds/guides/overview#balloon-editor Balloon editor} when it falls short, e.g. when some content must be inserted (e.g. an image) but the selection is collapsed, leaving the user unable to access the toolbar.
 
 ## Example
 
 <info-box hint>
-	Move the caret around to see the block toolbar button following the selection. Click the button to use the toolbar.
+	Move the caret around to see the block toolbar button following the selection. Click the button (&#182;) to use the toolbar, e.g. create a header or insert an image.
 </info-box>
 
 {@snippet features/blocktoolbar}
@@ -19,6 +19,10 @@ Since the toolbar is always connected to the block of content, it naturally acco
 
 The content of the toolbar can be defined using the {@link module:core/editor/editorconfig~EditorConfig#blockToolbar} configuration. See the [installation instructions](#installation) to learn more.
 
+<info-box hint>
+	Because the toolbar is always connected to the block of content, it works best with the features that modify entire blocks (e.g. create {@link features/headings headers}) or insert objects (e.g. {@link features/image images} or {@link features/table tables}) rather than inline styles (e.g. {@link features/basic-styles bold or italic}).
+</info-box>
+
 To adjust the position of the block toolbar button to match the styles of your website, use the CSS `transform` property:
 
 ```css
@@ -46,10 +50,16 @@ import BlockToolbar from '@ckeditor/ckeditor5-ui/src/toolbar/block/blocktoolbar'
 import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
 import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
 
-ClassicEditor
+BalloonEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI, ... ],
-		blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', '|', 'bulletedList', 'numberedList' ]
+		blockToolbar: [
+			'paragraph', 'heading1', 'heading2', 'heading3',
+			'|',
+			'bulletedList', 'numberedList',
+			'|',
+			'blockQuote', 'imageUpload'
+		],
 		toolbar: [ ... ]
 	} )
 	.then( ... )

+ 1 - 0
packages/ckeditor5-ui/package.json

@@ -16,6 +16,7 @@
   "devDependencies": {
     "@ckeditor/ckeditor5-basic-styles": "^10.0.1",
     "@ckeditor/ckeditor5-block-quote": "^10.0.1",
+    "@ckeditor/ckeditor5-build-balloon": "^10.1.0",
     "@ckeditor/ckeditor5-cloud-services": "^10.0.1",
     "@ckeditor/ckeditor5-editor-balloon": "^10.0.1",
     "@ckeditor/ckeditor5-editor-classic": "^10.0.1",