Skip to content

Commit

Permalink
Add documentation how to create a new button
Browse files Browse the repository at this point in the history 
Fixes #2
  • Loading branch information
@ipeychev
ipeychev committed Jul 24, 2014
1 parent de6c955 commit 079e793
Showing 1 changed file with 150 additions and 29 deletions.
179 changes: 150 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
Alloy Editor
Alloy Editor - WYSIWYG editor, based on CKEditor, with completely rewritten UI.
==================

## What is that?
Alloy Editor is a WYSIWYG editor, based on CKEditor, with completely rewritten UI.

## How to build it

1. Fork the repository, so you can send then patches.
Expand Down Expand Up @@ -77,7 +74,7 @@ Please note that in this case there is **no need** to specify CKEDITOR_BASEPATH.

<li> Create instances of AlloyEditor and specify the configuration:</li>

```javascript
````javascript
var editor = new Y.AlloyEditor({
srcNode: '#description',
toolbars: {
Expand All @@ -92,7 +89,6 @@ var editor = new Y.AlloyEditor({
In the above configuration, "editable" is the ID of the element, which will be made editable. You can fully reconfigure the toolbars, or to remove them entirely. See below for more information.
````javascript
toolbars = {....}

````

Aloy Editor comes with optimized version of CKEditor. Many plugins were removed. However, if you prefer the OOTB version, then you have to remove some of its plugins, like this:
Expand All @@ -105,7 +101,7 @@ new Y.AlloyEditor({

"extraPlugins" config property is a list with the default plugins from Alloy Editor. However, you can customize these. For example, if you don't want the plugin for adding images via D&D, then just remove "dropimages" from "extraPlugins" property.

## What is wrong with the UI of CKEditor? Why do you think Alloy Editor provides better UI?
## What is wrong with the UI of CKEditor?

CKEditor's UI is just old school. The toolbar appears on top, in case of inline editing it appears on top or on bottom. However, any modern editor UI places the toolbar just above the selection.
Alloy Editor actually goes a step forward in this direction and it shows the toolbars in the most appropriate position. That might be where user releases the mouse after he finishes the selection, or just where selection begins or ends.
Expand All @@ -117,58 +113,171 @@ On top of that, Alloy Editor also offers some plugins. One of them is a plugin,
## Toolbar configuration
#### Default toolbar configuration

The defalt toolbar configuration in editor is as follows:
The defalt toolbars configuration in editor is as follows:

````
editor.config.toolbars = {
````javascript
toolbars = {
add: ['image', 'code'],
image: ['left', 'right'],
styles: ['strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter']
};
````

The configuration above represents the three toolbars - for adding (images, code, etc.), aligning images and styling text. You may remove any of those and this toolbar won't be shown. Not only that, but its code won't be loaded at all. This is just the opposite what most editor's UI do - they load everything and then just hide it.
The configuration above represents three toolbars - for adding content (images, code, etc.), aligning images and styling text. You may remove any of those and this toolbar won't be shown. Not only that, but **its code won't be loaded at all**. This is just the opposite what most editor's UI do - they load everything and then just hide it.

So, if you want to remove the toolbar for adding, just delete the property "add" from the object above.
So, if you want to remove the toolbar for adding, just **remove** the property "add" from the object above:

#### Buttons reordering
````javascript
toolbars = {
image: ['left', 'right'],
styles: ['strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter']
};
````

#### Passing attributes to Toolbar
In the default UI, which uses AlloyUI/YUI3, Toolbars are standard [Widgets](http://yuilibrary.com/yui/docs/widget/). This means that it is possible to configure them by passing all attributes, valid for YUI3 Widgets and also those, specific for the different Toolbars. See the API page for the list of supported attributes for each Toolbar.

If you are not happy with the order of the buttons, you can just reorder them in the toolbar configuration. If you remove them, then this button won't be available. Also, its code will be not loaded at all. For example, of you want "em" to be before "strong", then do the following:
Toolbar value in AlloyEditor configuration can be an **Array** with button's names, in which case this is considered as list of the Buttons which this Toolbar should have, or an **Object**.

Here is an example how can you pass attributes to a Toolbar:

````javascript
toolbars = {
styles: {
buttons: ['strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter'],
id: 'exampleId'
}
};
````
styles: ['em', 'strong']

In this case two properties are being passed to ToolbarStyles - buttons and [id](http://yuilibrary.com/yui/docs/api/classes/Widget.html#attr_id).

#### Buttons reordering

If you are not happy with the order of the buttons, you can just reorder them in the toolbar configuration. They will follow the order you specify them. For example, if you want "em" (italic) button to be before "strong" (bold) button, then do the following:

````javascript
toolbars = {
styles: ['em', 'strong']
};
````

Now the toolbar of styles will have only two buttons, and they will be for "em" (aka. italic) and "strong" (aka bold).
#### Removing Buttons from Toolbar
If you remove button from a Toolbar, then this button won't be available. No only that, but its code will be not loaded at all.

## How to create my own button?

If you run the editor with the default UI, which is written in YUI3, then adding a button will be straightforward. Buttons are standard YUI3 modules, which extend Widget. For your convenience, there is also base class, which you can extend.
Use CKEditor's API to do the real job and that is it!
If you run the editor with the default UI, which is written in AlloyUI/YUI3, then adding a button will be straightforward. Buttons are standard YUI3 modules, which extend Widget. For your convenience, there is also a base class, which you can extend (ButtonBase). Then, use CKEditor's API to do style the content and that is it!

For example, if you want to add a button, which posts the selected text to Facebook, create a YUI3 module, let's say Y.ButtonFacebook and load it on the page.
Then, add it to the configuration of the toolbar, like this:

```` styles: ['strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter', 'facebook'] ````
````javascript
styles: ['strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter', 'facebook']
````

Of course, the buttons accept configuration parameters, so you can do this with your button:

````javascript
styles: [
'strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter', 'facebook': {
customParam: 'param1',
customParam2: 'param2'
}
];
````
styles: ['strong', 'em', 'u', 'h1', 'h2', 'a', 'twitter', 'facebook': {
customParam: 'param1',
customParam2: 'param2'
}];

You may overwrite any of the params of the default buttons, just by passing such config object.

And then, add the configuration of styles toolbar to the toolbars attribute:

````javascript
toolbars: {
styles: [
'facebook': {
customParam: 'param1',
customParam2: 'param2'
}
];
}
````

Btw, you may overwrite any of the params of the default buttons, just by passing such config object.
#### Full example of creating a new button.
Here is an example how can you create a button which handles H3 styling of an selection:

````javascript
YUI.add('button-h3', function(Y) {
'use strict';

var Lang = Y.Lang;

/**
* The ButtonH3 class provides functionality for applying HTML heading, level 3
* to the selection.
*
* @class ButtonH3
*/
var H3 = Y.Base.create('h3', Y.Plugin.Base, [Y.ButtonBase], {
TPL_CONTENT: '<i class="alloy-editor-icon-h3"></i>' // the content of the button - if could be text or an icon
}, {
NAME: 'h3',

NS: 'h3',

ATTRS: {
/**
* Specifies the element (style) which this button handles.
*
* @attribute element
* @default 'h3'
* @type String
*/
element: {
validator: Lang.isString,
value: 'h3'
}
}
});

Y.ButtonH3 = H3;

}, '', {
requires: ['button-base']
});
````

Then, you have to add it to the configuration of the Toolbar where you want to use it. Buttons, which handle styles make sense to be added to styles toolbar:
````javascript
toolbars: {
styles: ['strong', 'em', 'u', 'h1', 'h2', 'h3', 'a', 'twitter', 'facebook']
}
````

In this case H3 button will appear after H2 button.

If course, the JavaScript file, which contains the code of the button, should be added on the page. You have two options here:
- to add this file to the page in the way you prefer. Add another ```` <script> ```` element, or join this file among your other files.
- To use AlloyUI/YUI3. If you use the default UI, which uses AlloyUI/YUI3, you will be able to get the benefits of the [Loader](http://yuilibrary.com/yui/docs/api/classes/Loader.html). Add a bit of JavaScript and register your button to the current YUI instance, like this:

````javascript
YUI.applyConfig({
modules: {
'button-h3': {
fullpath: './button-h3.js'
}
}
});
````

See YUI3 [documentation](http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_applyConfig) for more information.

## How to create my own toolbar?


Adding a new toolbar is also as straightforward, as adding a button. If you use the default YUI3 based UI, you may create a standard module, which extends Widget. For your convenience, there is an extension, called ToolbarBase, which you can mix in your Widget. Then, name your toolbar somehow, for example ToolbarTable and load it on the page. Don't forget to add it to the configuration of the toolbars, like this:

````
editor.config.toolbars = {
````javascript
toolbars = {
table: ['button1', 'button2'],
add: ['image', 'code'],
image: ['left', 'right'],
Expand Down Expand Up @@ -240,13 +349,25 @@ YUI.add('toolbar-table', function (Y) {

## AlloyEditor architecture

The main idea behind the editor is to fully separate the core from the UI. And not only to separate it, but to give opportunity of people to add very easy new Buttons and Toolbars.
The main idea behind the editor is to fully separate the core from the UI. And not only to separate it, but to give opportunity to people to add very easy new Buttons and Toolbars or to create completely new UI, based on different Framework or vanilla JavaScript.

### The core
AlloyEditor uses under the hood CKEditor. In general, there are two ways to create an editor - to start from scratch or to step on something already existing. To start creating an editor from scratch is challenging. It is challenging mainly because browsers generate very inconsistent HTML, not to mention how buggy they are. In fact, to create an editor, which is able to handle all browsers, let's say IE9+, Chrome, Firefox and Safari, is very hard. Fortunately, CKEditor does it well, so it was the natural choice not only because of that, but because it is mature, well documented and configurable.
AlloyEditor uses CKEditor under the hood to deal with the HTML. Browsers still generate very inconsistent HTML, not to mention how buggy they are. In fact, to create an editor, which is able to handle all browsers, let's say IE9+, Chrome, Firefox and Safari, is very challenging. Fortunately, CKEditor does it well, so it was the natural choice not only because of that, but because it is mature, well documented and configurable.
Not everything from CKEditor is being used. In fact, AlloyEditor uses only the core from it. The whole UI has been discarded and the version of CKEditor which comes in AlloyEditor is twice smaller than the version OOTB.
On top of what CKEditor provides, new plugins and modules were created, which form the core of AlloyEditor.
Among these plugins is a plugin, which adds new functions which provide information about the selection - its regions, direction and so on. This is the key part and that is what allows the Toolbars to display themselves just above or below the selection. Other plugins are related to Drag&Drop of images directly in the editor, or they provide common API for creating, editing and removing links and so on.
There is no much dependency of CKEditor in AlloyEditor. If there is better base, or if we reach the point when creation of new core would be easier but we still will be able to support the majority of the browsers, nothing prevents us of replacing CKEditor core with our own.
In this section we will talk about the default UI, which is built using AlloyUI/YUI3 and Bootstrap.
### The UI
The UI has been thought in the way that it should provide the following functionality:
- Toolbars should allow adding, removing and reordering Buttons.
- The developer should be able to add new Toolbars to the editor.
- If some Button or Toolbar is not being used, its code shouldn't be loaded at all. This is just the opposite of what most editors do - they load the whole UI, regardless of the fact some buttons are being removed from the Toolbar.
- It should be easy to create a new UI. The default one uses AlloyUI/YUI3 because it provides rich components infrastructure, flexibility and code loading on demand. However, if developer wants to use another Framework or to create UI using vanilla JavaScript and CSS - that should be possible.

Currently AlloyEditor supports only one UI - it uses AlloyUI/YUI3. Please feel free to contact us if you want to contribute another UI.

## How to help

Expand Down

0 comments on commit 079e793

Please sign in to comment.