8
0
Просмотр исходного кода

Updated the theme customization guide.

Aleksander Nowodzinski 8 лет назад
Родитель
Сommit
f8d38ed1db

+ 8 - 1
packages/ckeditor5-theme-lark/docs/_snippets/examples/theme-lark.html

@@ -1,3 +1,10 @@
 <div id="snippet-classic-editor">
-	<p>This is <a href="https://ckeditor5.github.io">CKEditor&nbsp;5</a>.</p>
+	<p>
+		This is <a href="https://ckeditor5.github.io">CKEditor&nbsp;5</a>.
+	</p>
+	<p>
+		It uses the default
+		<a href="https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark">Lark</a>
+		theme with various customizations.
+	</p>
 </div>

+ 10 - 8
packages/ckeditor5-theme-lark/docs/_snippets/examples/theme-lark.scss

@@ -1,19 +1,21 @@
 // Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
 // For licensing, see LICENSE.md or http://ckeditor.com/license
 
+// Allow using Lark's ck-box-shadow() mixin.
 @import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_shadow.scss';
+
+// Allow using colors defined in Lark and the ck-color() mixin.
 @import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_colors.scss';
-@import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_button.scss';
 
+// The shadow should be 10% brighter than the toolbar background.
 $shadow-color: ck-color( 'editor-toolbar-background', 10 );
 
 .ck-editor-toolbar {
-	.ck-button {
-		&.ck-dropdown__button {
-			@include ck-box-shadow(
-				0 0 0 1px $shadow-color inset,
-				0 0 5px $shadow-color inset
-			);
-		}
+	.ck-button.ck-dropdown__button {
+		// Apply a dedicated inner box-shadow to the dropdown button.
+		@include ck-box-shadow(
+			0 0 0 1px $shadow-color inset,
+			0 0 5px $shadow-color inset
+		);
 	}
 }

+ 67 - 8
packages/ckeditor5-theme-lark/docs/examples/theme/theme-lark.md

@@ -1,7 +1,7 @@
 ---
 title: Theme customization
-category: examples-framework
-order: 20
+category: framework-guides-ui
+order: 10
 ---
 
 The [`@ckeditor/ckeditor5-theme-lark`](https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark) is the default theme of CKEditor 5. Lark is modular, [BEM–friendly](https://en.bem.info/methodology/css/) and built in [SASS](http://sass-lang.com).
@@ -10,9 +10,11 @@ Although it has been designed with versatility and the most common editor use–
  * by building the editor with a set of custom SASS variables and overriding [defaults](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#Variable_Defaults___default), which does not change the size of the build,
  * by importing an extra `.scss` file and overriding the CSS rules, which increases the size of the build.
 
+You can see the demo of an editor with the dark theme as a result of customizations described later in this guide:
+
 {@snippet examples/theme-lark}
 
-## Styles in CKEditor
+## Styles processing and bundling
 
 CKEditor 5 is bundled using [webpack](https://webpack.js.org/) and it handles the importing and processing of the styles using the [loaders](https://webpack.js.org/concepts/loaders/). Its configuration can be found in the `webpack.config.js` file.
 
@@ -82,9 +84,6 @@ module: {
 
 Each single SASS file is compiled in a separate thread, so to override default variables (defined with `!default`) across the theme, new values must be imported/declared at the very beginning of **each single** SASS file's compilation process. SASS Loader offers the [`data`](https://www.npmjs.com/package/sass-loader#environment-variables) option to do this.
 
-<info-box hint>
-	Check out the [colors helper](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/helpers/_colors.scss) for the full list of customizable colors. You can also browse [other helpers](https://github.com/ckeditor/ckeditor5-theme-lark/tree/master/theme/helpers) to learn about other useful SASS variables.
-</info-box>
 
 Let's [`@import`](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#_import__import) a `custom.scss` file located in the root of the repository containing all custom variables.
 
@@ -103,6 +102,12 @@ use: [
 
 Using the full potential of the SASS variables, the customization will make the theme dark, with slightly bigger text and more rounded corners.
 
+<info-box hint>
+	Check out the [colors helper](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/helpers/_colors.scss) for the full list of customizable colors. You can also browse [other helpers](https://github.com/ckeditor/ckeditor5-theme-lark/tree/master/theme/helpers) to learn about other useful SASS variables.
+</info-box>
+
+The contents of `custom.scss` could look as below:
+
 ```scss
 // Overrides the border-radius setting in the theme.
 $ck-border-radius: 4px;
@@ -182,6 +187,60 @@ $ck-colors: (
 );
 ```
 
-Now let's build the editor using `npm run build-ckeditor` and see the results. From now on, the editor should always use customized styles.
+Now let's build the editor using `npm run build-ckeditor` and see the results. From now on, the editor's theme is using customized styles.
+
+## Adding extra styles to the build
+
+Not every element of the theme can be customized using SASS variables and some visual tweaking may require more complex CSS rules.
+
+In the editor demo presented and the very beginning of this guide, the drop down button in the toolbar has a complex inner [`box-shadow`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow?v=b) that makes it more appealing. By default, the [Lark](https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark) theme does not support such shadow and that is why it must be defined separately.
+
+```css
+.ck-editor-toolbar .ck-button.ck-dropdown__button {
+	box-shadow: 0 0 0 1px #5c5b5d inset, 0 0 5px #5c5b5d inset;
+}
+```
+
+The above rule could be added directly to any styles sheet in the web page and most certainly would work as expected.
+
+But what if the color set customized in the [previous part](#Customization-with-SASS-variables) of this guide has changed? Static CSS rules will not update along with the SASS variables and neither they can benefit from the mixins and functions provided by the theme. To add an extra styles and keep it within the ecosystem, a separate SASS file should be created (let's call it `extras.scss`):
+
+```scss
+// Allow using Lark's ck-box-shadow() mixin.
+@import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_shadow.scss';
+
+// Allow using colors defined in Lark and the ck-color() mixin.
+@import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_colors.scss';
+
+// The shadow should be 10% brighter than the toolbar background.
+$shadow-color: ck-color( 'editor-toolbar-background', 10 );
+
+.ck-editor-toolbar {
+	.ck-button.ck-dropdown__button {
+		// Apply a dedicated inner box-shadow to the dropdown button.
+		@include ck-box-shadow(
+			0 0 0 1px $shadow-color inset,
+			0 0 5px $shadow-color inset
+		);
+	}
+}
+```
+
+and then imported into a JavaScript file that is processed by webpack and the [loaders](#Styles-processing-and-bundling), like an e.g. an entry–point of the application.
+
+```js
+import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+import 'extras.scss';
+
+ClassicEditor
+	.create( ... )
+	.then( editor => {
+		console.log( editor );
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
+
+```
 
-## Adding custom styles to the build
+This way, the additional styles will stay up–to–date as the application develops and changes over the time.