Improve "how to use ckeditor plugins" documentation

srad commented 8 years ago

I'm currently stuck in the (bare) docs on how to use ckeditor plugins. I will just list the thoughts I went through trying to make it work, which will probably help you to improve the documentation.

I'm referring to http://alloyeditor.com/guides/how_to_use_ckeditor_plugins/

1) Find and download the one of your choosing into your project ckeditor dist folder

Which ckeditor dist folder? I installed your project via bower. I only have at the dist folder: dist/alloy-editor/plugins/*.

Do I have to copy them into that folder and they are dynamically loaded?
What are these files under plugins doing there? Could the doc make an example how to include one of those, so one can test it it right away?
Or do I have to make a custom build and copy the plugin first to /lib/ckeditor/plugins/*

I don't know what is going on, stuck right here. Tests didn't help.

2) Add the CKEditor plugin

So I do:

// Extend the extraPlugins value adding the new plugins to the default ones
AlloyEditor.editable('contentEditable', {
    extraPlugins: AlloyEditor.Core.ATTRS.extraPlugins.value + ',myplugin,myplugindependency'
});

Again related: 2.1. To what do these names correspond to (literally)? 2.2. Are there Plugins loaded dynamically or is a build needed, 2.3. or do I have to include the files and extend your AlloyEditor object manually??

(I guess you internally keep a reference to CKEDITOR or something, no clue).

3) "Bridge" Section

This section is not understandable, probably if you already know the ckeditor source code, I don't know.

3.1. First of all, which plugins can be bridged? Do I have to try that for each one of them? 3.2. Make more clear what your bridge-plugin does/means.

I guess that ckeditors plugins can either implement a button, drop-down menu or rich-combo(?) and you need to render them inside your floating toolbar, so you need to delegate the rendering output, is that right? Make that please more clear.

Another point is that the source code there is a little confusing because of the Array.prototype.concat, could you only give a trivial complete example with the referenced font plugin (better would be of course with one that you provide, like pastefromword, or something).

jbalsas commented 8 years ago

Hi @srad, thanks a lot for the comments. I'm sorry if the documentation is not 100% clear. I'll try to make our technical writer go through the articles to see what can be improved considering your comments.

However, keep in mind that most of the missing information is CKEditor related, and you should be able to find it in their documentation. I'll see if we can add the proper links.

For now,

Which ckeditor dist folder? I installed your project via bower. I only have at the dist folder: dist/alloy-editor/plugins/*.

Do I have to copy them into that folder and they are dynamically loaded?

What are these files under plugins doing there? Could the doc make an example how to include one of those, so one can test it it right away?

Or do I have to make a custom build and copy the plugin first to /lib/ckeditor/plugins/*

[...]

2.1. To what do these names correspond to (literally)? 2.2. Are there Plugins loaded dynamically or is a build needed, 2.3. or do I have to include the files and extend your AlloyEditor object manually??

If you are installing via bower and using alloy-editor-all.js, the only thing you should need is to download the plugins you want directly from the CKEditor addons page and extract them in the plugins folder.

If you had an external CKEditor and used alloy-editor-no-ckeditor.js, then you'd need to extract them in your CKEditor respective plugins folder.

Pretty much all this information should be available in the Installing Plugins page.

3) "Bridge" Section

This section is not understandable, probably if you already know the ckeditor source code, I don't know.

3.1. First of all, which plugins can be bridged? Do I have to try that for each one of them? 3.2. Make more clear what your bridge-plugin does/means.

As you guessed, plugins that add ui controls to the toolbars such as buttons, dropdowns, menu-buttons can be bridged. Our plugin captures the CKEditor API for that and creates the AlloyEditor counterpart so you can use them inside our toolbars.

Please, let us know if you still have questions.

Thanks again for your suggestions!

sanvuthy commented 8 years ago

Hi @jbalsas

I have followed the instruction from this link http://alloyeditor.com/guides/how_to_use_ckeditor_plugins/ to add mediaembed CKeditor plugin to use in alloyeditor as below:

Step 1: Copy mediaembed that I downloaded from CKeditor to alloyeditor/dist/alloy-editor/plugins

Step 2:

AlloyEditor.editable('editable', { extraPlugins: AlloyEditor.Core.ATTRS.extraPlugins.value + ',mediaembed' });

then I try to run it then it show an error: "Uncaught TypeError: editor.ui.addButton is not a function"

screen shot 2015-12-11 at 9 42 47 am copy

And it seem you already have a solution to do it as you said in this link: https://github.com/liferay/alloy-editor/issues/233

Could you advice the way to do it in more detail?

Thanks in advance.

jbalsas commented 8 years ago

Hey @sanvuthy,

That message means the plugin you're adding is trying to add a button to the ui. You'll need our ui-bridge-* plugins to automatically convert that call to a button you could use in a toolbar.

AlloyEditor.editable('editable', {
extraPlugins: AlloyEditor.Core.ATTRS.extraPlugins.value + ',ae_uibridge,ae_buttonbridge,mediaembed',
toolbars: {
        add: {
            buttons: ['table', 'hline', 'image', 'camera', 'MediaEmbed'],
            tabIndex: 2
        },
        styles: {
            selections: AlloyEditor.Selections,
            tabIndex: 1
        }
    }
});

We're working on improving this documentation, so hopefully it would be clearer.

Anyway, regarding #233, I meant you could use the official embed plugins.

EDITED: UI Bridge Plugin names use an underscore rather than a dash

sanvuthy commented 8 years ago

Hi @jbalsas ,

When I use ae-uibridge,ae-buttonbridge it show another error.

Does it required something else? In this message it point to dist/alloy-editor/plugins/ae-buttonbridge/plugin.js?t=FACH location. Do I need to download these plugin to the plugin folder?

jbalsas commented 8 years ago

Hey @sanvuthy, I'm so sorry, that was my mistake :cry:

The plugin names use an underscore rather than a dash. They should be ae_uibridge and ae_buttondrige.

Could you check again, please?

sanvuthy commented 8 years ago

Hey @jbalsas , It works :+1:

Thank you very much for your good and quick support.

beeant commented 8 years ago

:+1: PS: ae_buttondrige has been fixed to ae_buttonbridge

kushal commented 8 years ago

Is there a way to compile a plugin into the bundles generated by gulp release?

jbalsas commented 8 years ago

Hey @kushal, I assume you want the plugins to be bundled in the ckeditor.js or one of the alloy-editor-*.js generated scripts, right?

If so, and since you seem to want to build your own flavour of AlloyEditor, you should:

Navigate to http://ckeditor.com/builder
Click on the Upload build-config.js button and upload the file you'll find in /lib/ckeditor/build-config.js. This will configure the builder with the same exact CKEditor settings we are currently using
Add the additional plugins you want to use
Download the optimized CKEditor generated version
Uncompress and replace the lib/ckeditor folder for the one you just downloaded
Run gulp release

Keep in mind that this will make your branch out of sync with ours, so if you want to update later on, you'll have to repeat this process using the new bundled build-config.js files of the newer versions.

Let us know if that helps!

kushal commented 8 years ago

Sweet. I thought about doing something similar but wasn't sure how kosher it was. I'll give it a shot! :)

On Mon, Jan 4, 2016 at 2:46 PM Chema Balsas notifications@github.com wrote:

Hey @kushal https://github.com/kushal, I assume you want the plugins to be bundled in the ckeditor.js or one of the alloy-editor-*.min.js generated scripts, right?

If so, and since you seem to want to build your own flavour of AlloyEditor, you should:

Navigate to http://ckeditor.com/builder

Click on the Upload build-config.js button and upload the file https://github.com/liferay/alloy-editor/blob/master/lib/ckeditor/build-config.js you'll find in /lib/ckeditor. This will configure the builder with the same exact CKEditor settings we are currently using

Add the additional plugins you want to add

Download the optimized CKEditor generated version

Uncompress and replace the lib/ckeditor folder for the one you just downloaded

Run gulp release

Keep in mind that this will make your branch out of sync with ours, so if you want to update later on, you'll have to repeat this process using the new bundled build-config.js files of the newer versions.

Let us know if that helps!

— Reply to this email directly or view it on GitHub https://github.com/liferay/alloy-editor/issues/384#issuecomment-168835856 .

Ofer-Gal commented 7 years ago

@jbalsas , I tried your instructions for adding 'MediaEmbed' , it works fine. I am trying to do exactly the same with 'pastefromword' and I get no errors but the icon does not show in the + toolbar here is the code ` var editor = AlloyEditor.editable('editable', { extraPlugins: AlloyEditor.Core.ATTRS.extraPlugins.value +',ae_uibridge,ae_buttonbridge,pastefromword,mediaembed,clipboard,dialog,dialogui', toolbars: { add: { buttons: ['table', 'hline', 'image', 'camera','pastefromword','MediaEmbed'], tabIndex: 2 }, styles: { selections:AlloyEditor.Selections , //selections, tabIndex: 1 } } });

`

Could you help please?

jbalsas commented 7 years ago

Hey @Ofer-Gal, the name of the button the Paste from Word plugin add is actually PasteFromWord (notice the uppercase). You can see that here.

@ipeychev, I see this causing some problems regularly... I think we might want to expose some kind of API so people don't need to go digging into the CKEditor source code for the plugins... maybe something like:

buttons: ['table', 'hline', ...AlloyEditor.getButtonsFor('pastefromword'), 'MediaEmbed']

What do you think?

jbalsas commented 7 years ago

FYI, we're working on a new site and with improved docs, so we'll get to this soon.

ipeychev commented 7 years ago

I think it is a good idea, let's create an issue and do it.

Thanks,

jbalsas commented 7 years ago

Done: https://github.com/liferay/alloy-editor/issues/667

Ofer-Gal commented 7 years ago

I managed to make it work but the icon is not the one in the /plugins/pastefromword/icons. It shows like an X Do I need to add it to the { extraPlugins: ?

On Mon, Jan 9, 2017 at 4:41 AM, Chema Balsas notifications@github.com wrote:

Hey @Ofer-Gal https://github.com/Ofer-Gal, the name of the button the Paste from Word plugin add is actually PasteFromWord (notice the uppercase). You can see that here https://github.com/ckeditor/ckeditor-dev/blob/master/plugins/pastefromword/plugin.js#L53 .

@ipeychev https://github.com/ipeychev, I see this causing some problems regularly... I think we might want to expose some kind of API so people don't need to go dig in the CKEditor source code for the plugins... maybe something like:

buttons: ['table', 'hline', ...AlloyEditor.getButtonsFor('pastefromword'), 'MediaEmbed']

What do you think?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/liferay/alloy-editor/issues/384#issuecomment-271254341, or mute the thread https://github.com/notifications/unsubscribe-auth/AE0h049hOVOc726DTZ9tfB5hCM9J4ceAks5rQg7wgaJpZM4Gn2pN .

-- Ofer Gal

לפני הפצת שרשרת, נא מחקו את שמי וכתובתי מהדוא"ל, כדי שהפרטים לא יגיעו לחורשי מרעין בישין ברחבי האינטרנט

jbalsas commented 7 years ago

Hey @Ofer-Gal, I assume that you already added it to the extraPlugins... can you make sure the icon.png for the pastefromword plugin is accessible in your site?

Ofer-Gal commented 7 years ago

There are /alloy-editor/plugins/icons.png containing the icon and /alloy-editor/plugins/pastefromword/icons/pastefromword.png and /alloy-editor/plugins/pastefromword/icons/hidpi/pastefromword.png Icons All accesible from the root.

The script is at the root var editor = AlloyEditor.editable('editable', {extraPlugins: AlloyEditor.Core.ATTRS.extraPlugins.value +',ae_uibridge,ae_buttonbridge,pastefromword,mediaembed,clipboard,dialog,dialogui', toolbars: { add: { buttons: ['table', 'hline', 'image', 'PasteFromWord','MediaEmbed'], tabIndex: 2 }, styles: { selections:AlloyEditor.Selections , //selections, tabIndex: 1 } } });

Should the script mention something about Icons?

On Fri, Jan 13, 2017 at 2:40 AM, Chema Balsas notifications@github.com wrote:

Hey @Ofer-Gal https://github.com/Ofer-Gal, I assume that you already added it to the extraPlugins... can you make sure the icon.png for the pastefromword plugin is accessible in your site?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/liferay/alloy-editor/issues/384#issuecomment-272389854, or mute the thread https://github.com/notifications/unsubscribe-auth/AE0h0zJvCqJSrfP4jy-yPLc4k3C5ETJhks5rRziQgaJpZM4Gn2pN .

-- Ofer Gal

לפני הפצת שרשרת, נא מחקו את שמי וכתובתי מהדוא"ל, כדי שהפרטים לא יגיעו לחורשי מרעין בישין ברחבי האינטרנט

jbalsas commented 7 years ago

Hey @Ofer-Gal, I don't think you should need anything else... could you prepare an environment where we could check? jsfiddle, a zip file containing your setup...

Ofer-Gal commented 7 years ago

Here is a zip with my index.html and everything else. mostly out of the GIT alloy-editor.zip

Thank you very much for your help

jbalsas commented 7 years ago

Hey @Ofer-Gal, looks like you replaced the plugins/icons-hidpi.png file, and so, CKEditor is failing to give us the right coordinates for the plugin icon. If you use the one provided in the AlloyEditor release, everything seems to be working fine.

Ofer-Gal commented 7 years ago

Thanks for checking. I replaced with the file at https://raw.githubusercontent.com/liferay/alloy-editor/master/lib/ckeditor/plugins/icons_hidpi.png

in folder /AlloyEdit/alloy-editor/plugins but I still get the X instead

See the screen shot

On Fri, Jan 20, 2017 at 11:51 AM, Chema Balsas notifications@github.com wrote:

Hey @Ofer-Gal https://github.com/Ofer-Gal, looks like you replaced the plugins/icons-hidpi.png file, and so, CKEditor is failing to give us the right coordinates for the plugin icon. If you use the one provided in the AlloyEditor release, everything seems to be working fine.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/liferay/alloy-editor/issues/384#issuecomment-274135294, or mute the thread https://github.com/notifications/unsubscribe-auth/AE0h05qBjWdvgltE6TC96KPrlwBLnuXlks5rUPQugaJpZM4Gn2pN .

-- Ofer Gal

לפני הפצת שרשרת, נא מחקו את שמי וכתובתי מהדוא"ל, כדי שהפרטים לא יגיעו לחורשי מרעין בישין ברחבי האינטרנט

ileniazedda commented 7 years ago

Hi, I'm trying to add the media embed button in alloy editor.

I've tried adding to extraPlugins the value 'ae_embed' or 'mediaembed' and in the toolbars/add/buttons the value 'embed' and 'MediaEmbed'

A new button shows in the toolbar (the icon is just a line with the text 'link) however when clicking the save button to save the url, nothing gets saved in the editor.

Other buttons like audio or camera work fine.

Can you please clarify how to add the embed media button?

Thanks, Ilenia

jbalsas commented 7 years ago

Hey @ileniazedda, I guess this is in relation to https://web.liferay.com/es/community/forums/-/message_boards/message/92174127. I've answered you there, since this is related to the Liferay Portal integration, and not AlloyEditor itself.

ileniazedda commented 7 years ago

ah thank you very much!

jbalsas commented 6 years ago

Closing since I think we've answered most of the questions and docs were improved around this.

duracell80 commented 6 years ago

This original link to documentation 404 errors and does not redirect to any updated documentation. https://alloyeditor.com/guides/how_to_use_ckeditor_plugins/

liferay / alloy-editor

Improve "how to use ckeditor plugins" documentation #384

Could you help please?