Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Unified button and command naming convention #8394

Merged
merged 14 commits into from
Feb 12, 2021
8 changes: 4 additions & 4 deletions docs/_snippets/examples/inline-editor.js
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,17 @@ Array.from( inlineInjectElements ).forEach( inlineElement => {
config.image = {
resizeOptions: [
{
name: 'imageResize:original',
name: 'resizeImage:original',
pomek marked this conversation as resolved.
Show resolved Hide resolved
label: 'Original',
value: null
},
{
name: 'imageResize:50',
name: 'resizeImage:50',
label: '50%',
value: '50'
},
{
name: 'imageResize:75',
name: 'resizeImage:75',
label: '75%',
value: '75'
}
Expand All @@ -59,7 +59,7 @@ Array.from( inlineInjectElements ).forEach( inlineElement => {
'imageStyle:full',
'imageStyle:alignRight',
'|',
'imageResize',
'resizeImage',
'|',
'imageTextAlternative'
]
Expand Down
2 changes: 1 addition & 1 deletion docs/_snippets/examples/multi-root-editor.js
Original file line number Diff line number Diff line change
Expand Up @@ -391,7 +391,7 @@ MultirootEditor
}, {
plugins: [ Essentials, Paragraph, Heading, Bold, Italic, List, Link, BlockQuote, Image, ImageCaption,
ImageStyle, ImageToolbar, ImageUpload, Table, TableToolbar, MediaEmbed, EasyImage, CloudServices ],
toolbar: [ 'heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'imageUpload', 'blockQuote',
toolbar: [ 'heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'uploadImage', 'blockQuote',
'insertTable', 'mediaEmbed', 'undo', 'redo' ],
image: {
toolbar: [ 'imageTextAlternative', '|', 'imageStyle:full',
Expand Down
2 changes: 1 addition & 1 deletion docs/_snippets/features/toolbar-breakpoint.js
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ ClassicEditor
'code', 'codeBlock', '|',
'insertTable', '|',
'outdent', 'indent', '|',
'imageUpload', 'blockQuote', '|',
'uploadImage', 'blockQuote', '|',
'undo', 'redo'
],
shouldNotGroupWhenFull: true,
Expand Down
2 changes: 1 addition & 1 deletion docs/_snippets/features/toolbar-grouping.js
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ ClassicEditor
'bulletedList', 'numberedList', 'todoList', '|',
'code', 'codeBlock', '|',
'outdent', 'indent', '|',
'imageUpload', 'blockQuote', '|',
'uploadImage', 'blockQuote', '|',
'undo', 'redo'
],
viewportTopOffset: window.getViewportTopOffsetConfig()
Expand Down
2 changes: 1 addition & 1 deletion docs/_snippets/features/toolbar-wrapping.js
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ ClassicEditor
'bulletedList', 'numberedList', 'todoList', '|',
'code', 'codeBlock', '|',
'insertTable', '|',
'imageUpload', 'blockQuote', '|',
'uploadImage', 'blockQuote', '|',
'undo', 'redo'
],
shouldNotGroupWhenFull: true,
Expand Down
2 changes: 1 addition & 1 deletion docs/builds/guides/development/dll-builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ An example classic editor build configuration using dll bundles:
'indent',
'outdent',
'|',
'imageUpload',
'uploadImage',
'blockQuote',
'insertTable',
'mediaEmbed',
Expand Down
4 changes: 2 additions & 2 deletions docs/builds/guides/integration/advanced-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ ClassicEditor.defaultConfig = {
'link',
'bulletedList',
'numberedList',
'imageUpload',
'uploadImage',
'blockQuote',
'undo',
'redo'
Expand Down Expand Up @@ -344,7 +344,7 @@ ClassicEditor
'link',
'bulletedList',
'numberedList',
'imageUpload',
'uploadImage',
'blockQuote',
'undo',
'redo'
Expand Down
2 changes: 1 addition & 1 deletion docs/builds/guides/integration/installing-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ ClassicEditor.defaultConfig = {
'link',
'bulletedList',
'numberedList',
'imageUpload',
'uploadImage',
'blockQuote',
'undo',
'redo'
Expand Down
4 changes: 2 additions & 2 deletions docs/features/toolbar.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ toolbar: {
'bulletedList', 'numberedList', 'todoList', '|',
'code', 'codeBlock', '|',
'insertTable', '|',
'imageUpload', 'blockQuote', '|',
'uploadImage', 'blockQuote', '|',
'undo', 'redo'
],
shouldNotGroupWhenFull: true
Expand Down Expand Up @@ -140,7 +140,7 @@ toolbar: {
'code', 'codeBlock', '|',
'insertTable', '|',
'outdent', 'indent', '|',
'imageUpload', 'blockQuote', '|',
'uploadImage', 'blockQuote', '|',
'undo', 'redo'
],
shouldNotGroupWhenFull: true
Expand Down
54 changes: 52 additions & 2 deletions docs/framework/guides/contributing/code-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -447,7 +447,7 @@ You can use ES6 getters to simplify class API:
class Position {
// ...
get offset() {
return this.path[ this.path.length - 1 ];
return this.path[ this.path.length * 1 ];
pomek marked this conversation as resolved.
Show resolved Hide resolved
}
}
```
Expand Down Expand Up @@ -520,7 +520,7 @@ There are some special rules and tips for tests.
* Use [sinon-chai assertions](https://www.chaijs.com/plugins/sinon-chai/)

```js
expect( myMethodSpy ).to.be.calledOnce
expect( myMethodSpy ).to.be.calledOnce
pomek marked this conversation as resolved.
Show resolved Hide resolved
// expected myMethod to be called once but was called twice
```

Expand Down Expand Up @@ -604,6 +604,56 @@ this.canObserve;
this.mustRefresh;
```

### Buttons, Commands and Plugins
pomek marked this conversation as resolved.
Show resolved Hide resolved

#### Buttons

All buttons should follow the **verb + noun** or the **noun** convention. Examples:
* The **verb + noun** convention:
* `insertTable`
* `selectAll`
* `uploadImage`
* The **noun** convention:
* `bold`
* `mediaEmbed`
* `restrictedEditing`

#### Commands

As for commands it is trickier, because there are many more possible combinations of their names than there are for buttons. Examples:
* The **feature-related** convention:
* **noun-based** case:
* `codeBlock`
* `fontColor`
* `shiftEnter`
* **verb-based** case:
* `indent`
* `removeFormat`
* `selectAll`
* The **feature + sub-feature** convention:
* `imageStyle`
* `imageTextAlternative`
* `tableAlignment`

For commands, the **noun + verb** (or the **feature + action**) naming conventions **should not be used**, because it does not sound natural (_what do_ vs. _do what_). In most cases the proper name should start with the **action** followed by the **feature** name:
* `checkTodoList`
* `insertTable`
* `uploadImage`

#### Plugins

Plugins should follow the **feature** or the **feature + sub-feature** convention. Examples:
* The **feature** convention:
* `Bold`
* `Paragraph`
* `SpecialCharacters`
* The **feature + sub-feature** convention:
* `ImageResize`
* `ListStyle`
* `TableClipboard`

Plugins must be named in [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase).

### Shortcuts

For local variables **commonly accepted short versions** for long names are fine:
Expand Down
2 changes: 1 addition & 1 deletion docs/framework/guides/custom-editor-creator.md
Original file line number Diff line number Diff line change
Expand Up @@ -439,7 +439,7 @@ MultirootEditor
}, {
plugins: [ Essentials, Paragraph, Heading, Bold, Italic, List, Link, BlockQuote, Image, ImageCaption,
ImageStyle, ImageToolbar, ImageUpload, Table, TableToolbar, MediaEmbed, EasyImage ],
toolbar: [ 'heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'imageUpload', 'blockQuote',
toolbar: [ 'heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'uploadImage', 'blockQuote',
'insertTable', 'mediaEmbed', 'undo', 'redo' ],
image: {
toolbar: [ 'imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:alignRight' ],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ ClassicEditor
Enter, Typing, Paragraph, Heading, Undo, Bold, Italic, Heading, List, Image, ImageToolbar, Clipboard,
ImageCaption, ImageStyle, ImageUpload, CKFinderUploadAdapter
],
toolbar: [ 'heading', '|', 'undo', 'redo', 'bold', 'italic', 'bulletedList', 'numberedList', 'imageUpload' ],
toolbar: [ 'heading', '|', 'undo', 'redo', 'bold', 'italic', 'bulletedList', 'numberedList', 'uploadImage' ],
ckfinder: {
// eslint-disable-next-line max-len
uploadUrl: 'https://cksource.com/weuy2g4ryt278ywiue/core/connector/php/connector.php?command=QuickUpload&type=Files&responseType=json'
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-build-balloon-block/src/ckeditor.js
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ BalloonEditor.defaultConfig = {
'indent',
'outdent',
'|',
'imageUpload',
'uploadImage',
'blockQuote',
'insertTable',
'mediaEmbed',
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-build-balloon/src/ckeditor.js
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ BalloonEditor.defaultConfig = {
'indent',
'outdent',
'|',
'imageUpload',
'uploadImage',
'blockQuote',
'insertTable',
'mediaEmbed',
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-build-classic/src/ckeditor.js
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ ClassicEditor.defaultConfig = {
'indent',
'outdent',
'|',
'imageUpload',
'uploadImage',
'blockQuote',
'insertTable',
'mediaEmbed',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ DecoupledEditor.defaultConfig = {
'|',
'link',
'blockquote',
'imageUpload',
'uploadImage',
'insertTable',
'mediaEmbed',
'|',
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-build-inline/src/ckeditor.js
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ InlineEditor.defaultConfig = {
'indent',
'outdent',
'|',
'imageUpload',
'uploadImage',
'blockQuote',
'insertTable',
'mediaEmbed',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ ClassicEditor
.create( document.querySelector( '#snippet-ckfinder-upload-only' ), {
toolbar: {
items: [
'imageUpload', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
'uploadImage', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
],
viewportTopOffset: 100
},
Expand Down
8 changes: 4 additions & 4 deletions packages/ckeditor5-ckfinder/docs/features/ckfinder.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ ClassicEditor
plugins: [ CKFinder, ... ],

// Enable the "Insert image" button in the toolbar.
toolbar: [ 'imageUpload', ... ],
toolbar: [ 'uploadImage', ... ],

ckfinder: {
// Upload the images to the server using the CKFinder QuickUpload command.
Expand Down Expand Up @@ -189,7 +189,7 @@ import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ CKFinder, ... ],
toolbar: [ 'ckfinder', 'imageUpload' ... ], // Depending on your preference.
toolbar: [ 'ckfinder', 'uploadImage' ... ], // Depending on your preference.
ckfinder: {
// Feature configuration.
}
Expand All @@ -213,8 +213,8 @@ The {@link module:ckfinder/ckfinder~CKFinder} plugin registers:

Additionally, in the "image upload only" integration, you can use the following button and command registered by the {@link module:image/imageupload~ImageUpload} plugin:

* The `'imageUpload'` UI button component.
* The `'imageUpload'` command implemented by the {@link module:image/imageupload/imageuploadcommand~ImageUploadCommand}.
* The `'uploadImage'` UI button component.
* The `'uploadImage'` command implemented by the {@link module:image/imageupload/uploadimagecommand~UploadImageCommand}.

<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.
Expand Down
8 changes: 4 additions & 4 deletions packages/ckeditor5-ckfinder/src/ckfindercommand.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import { CKEditorError } from 'ckeditor5/src/utils';
* editor.execute( 'ckfinder' );
*
* **Note:** This command uses other features to perform tasks:
* - To insert images the {@link module:image/image/imageinsertcommand~ImageInsertCommand 'imageInsert'} command
* - To insert images the {@link module:image/image/insertimagecommand~InsertImageCommand 'insertImage'} command
* from the {@link module:image/image~Image Image feature}.
* - To insert links to files the {@link module:link/linkcommand~LinkCommand 'link'} command
* from the {@link module:link/link~Link Link feature}.
Expand All @@ -44,7 +44,7 @@ export default class CKFinderCommand extends Command {
* @inheritDoc
*/
refresh() {
const imageCommand = this.editor.commands.get( 'imageInsert' );
const imageCommand = this.editor.commands.get( 'insertImage' );
const linkCommand = this.editor.commands.get( 'link' );

// The CKFinder command is enabled when one of image or link command is enabled.
Expand Down Expand Up @@ -135,7 +135,7 @@ export default class CKFinderCommand extends Command {
}

function insertImages( editor, urls ) {
const imageCommand = editor.commands.get( 'imageInsert' );
const imageCommand = editor.commands.get( 'insertImage' );

// Check if inserting an image is actually possible - it might be possible to only insert a link.
if ( !imageCommand.isEnabled ) {
Expand All @@ -150,5 +150,5 @@ function insertImages( editor, urls ) {
return;
}

editor.execute( 'imageInsert', { source: urls } );
editor.execute( 'insertImage', { source: urls } );
}
4 changes: 2 additions & 2 deletions packages/ckeditor5-ckfinder/tests/ckfindercommand.js
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,9 @@ describe( 'CKFinderCommand', () => {
expect( command.isEnabled ).to.be.false;
} );

it( 'should be true when imageInsert or link command is enabled', () => {
it( 'should be true when insertImage or link command is enabled', () => {
setModelData( model, '<paragraph>[]</paragraph>' );
const insertImage = editor.commands.get( 'imageInsert' );
const insertImage = editor.commands.get( 'insertImage' );
const linkCommand = editor.commands.get( 'link' );

insertImage.isEnabled = false;
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-core/src/command.js
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ export default class Command {
* For example, the `'bold'` command's value indicates whether the selection starts in a bolded text.
* And the value of the `'link'` command may be an object with links details.
*
* It is possible for a command to have no value (e.g. for stateless actions such as `'imageUpload'`).
* It is possible for a command to have no value (e.g. for stateless actions such as `'uploadImage'`).
*
* A concrete command class should control this value by overriding the {@link #refresh `refresh()`} method.
*
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-easy-image/docs/features/easy-image.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ import EasyImage from '@ckeditor/ckeditor5-easy-image/src/easyimage';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ EasyImage, ... ],
toolbar: [ 'imageUpload', ... ],
toolbar: [ 'uploadImage', ... ],

// Configure the endpoint. See the "Configuration" section above.
cloudServices: {
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-easy-image/tests/easyimage.js
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ describe( 'EasyImage', () => {
}
} );

editor.execute( 'imageUpload', { file: createNativeFileMock() } );
editor.execute( 'uploadImage', { file: createNativeFileMock() } );

setTimeout( () => {
upload._uploadGateway.resolveLastUpload();
Expand Down
2 changes: 1 addition & 1 deletion packages/ckeditor5-easy-image/tests/manual/easyimage.js
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ ClassicEditor
'bulletedList',
'numberedList',
'blockQuote',
'imageUpload',
'uploadImage',
'insertTable',
'mediaEmbed',
'undo',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -325,7 +325,7 @@ describe( 'transform', () => {
john.split();
john.setSelection( [ 1, 0 ] );
john._processExecute( 'bold' );
john._processExecute( 'forwardDelete' );
john._processExecute( 'deleteForward' );

expectClients( '<paragraph>Foo</paragraph><paragraph>Bar</paragraph>' );

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ BaloonBlockEditor
'outdent',
'indent',
'|',
'imageUpload',
'uploadImage',
'blockQuote',
'insertTable',
'mediaEmbed'
Expand Down
Loading