Introduce new single-page sample and toolbar configurators

[Piotrek Koszuliński]

The goal is to replace all the samples that we are currently shipping with the packages with short one that condenses the most important informations for someone who has just downloaded CKEditor package.

Additionally, we'll introduce new tools for toolbar configuration.

For now we decided to keep the old samples in the samples/old/* directory, what:

• will break links, but we can do redirects on our sites (ckeditor.com/latest, nightly, etc.),
• will allow to find them if someone reads on forum/SO that "check out the xxx.html sample in your package".

This issue will close: #10628, #10228.

Progress tracking

​http://trello.com/b/ilfdRj3p/12875-introduce-new-single-page-sample-and-toolbar-configurators

[Piotrek Koszuliński]

Toolbar editor

1. The toolbar editors version in the incubator repo should be abandoned. I had to make many changes (code style) when copying code to the ckeditor-dev repo. To avoid mistake we can actually remove the toolbar tool from the incubator now.
2. The name. In ​https://github.com/cksource/incubator/issues/6 we chose "toolbar configurator", but today I started using "toolbar editor" somehow automatically. I leave the final choice to you guys, but please remember that the name should be reflected in the directory name (currently it is toolbareditor/).
3. Config output format should be improved. As mentioned in ​https://github.com/cksource/incubator/issues/8 the format is ugly. Perfect solution would be as Ania mentioned - single quotes, nicely aligned and spaced. Acceptable result is that at least it will be nicely spaced and no double quotes. You can check the old toolbar tool because it was printing the config pretty well.
4. DONE The basic sample should link to the basic toolbar editor (the graphical one) which should link to the advanced one. (all is on one page)
5. Both editors need short description how to use them. There should be a link that points to a documentation available @ ​http://docs.ckeditor.com/.
6. Use tooltips (simple HTML title attribute) to provide meaningful contextual help (remove separator, move group up etc.).
7. DONE Olek: Both editors' UX and UI must be polished.
8. Check whether the glyphs font used in the basic editor has the right license. We may also need to create a file in its directory with credits and its license.
9. The same as above about the CodeMirror and plugins used with it.
10. Update CodeMirror if it got any updates. Also, I would consider installing it and the plugins we use through npm.
11. DONE Both editors should by default load the toolbar layout that is actually set (which editor would use). Now they load all buttons in one row which is not true for normal editor. See the old toolbar sample to learn how to read toolbar layout.
12. DONE: There's some error thrown right now.
13. DONE: We don't need the "Toggle editable" button.
14. DONE Olek: It would be good if toolbar buttons were not clickable. I checked that setting pointer-events: none on the toolbar element seems to be enough.
15. DONE? It's useful that the tool's width is proportional to window size - thanks to that one can check how the toolbar will behave in different widths.
16. The "others" group could be displayed in the table (​https://github.com/cksource/incubator/issues/5).
17. DONE: In the basic toolbar editor change "Separator" to "Row separator" or something similarly meaningful.
18. DONE Olek: Reduce number of scrolls in the basic editor - there should be only one (I have two right now). (The floating toolbar makes sense.)
19. Artur: To be checked - how the toolbar editors read toolbar groups? What happens if one of loaded plugins defines its own group? What if it does and if config.toolbarGroups is set? This may be related - ​https://github.com/cksource/incubator/issues/4.
20. Toolbar editors should be checked on older IEs and if we have compatibility problems with something like IE10- we may just add there an alert that this browser is not supported.
21. DONE Introduce "headers" in Basic sample so that users were aware that there are groups and subgroups.
22. REVIEW Artur: The toolbar editor should not jump on every change. It can be fixed by setting a minimum height on an element that contains the toolbar.
23. DONE Artur The page with toolbar editor should not scroll up when changing the order of groups.
24. Artur There is no visual indication (outline) that up/down arrows are focused when using keyboard.
25. Highlighting toolbar groups on hover works only with small toolbars on big screens. With full toolbar (used by up to 50% of users) it is impossible to see the bottom groups highlighted on a toolbar after scrolling the page.
26. Artur Highlighting toolbar groups does not work on tablets or when one is using keyboard navigation only.
27. Olek Check the style of "Unused elements" in Advanced configurator.
28. DONE Bug: "Move up" button of a separator added without a context is enabled, though its the very first element of the list.
29. Artur Click "Get toolbar config", click "Advanced", click "Basic" - you see both - toolbar config and editor.

Basic sample

1. DONE We can actually link to the config.js file in the section about setting configuration. This will be nice because someone may notice there that it got cached if forgot to clear cache.
2. DONE I think that unfortunately the width of the page must be static, because entire full toolbar should fit there. This means that the font size should be pretty big, so it looks ok in lower res.
3. DONE I guess that look of the basic sample should be inspired by the SDK.
4. For the config section we chose uiColor and height which should cover 99.9% cases. We decided to place there entire code with CKEDITOR.editorConfig = functio() {};, so the text description must be updated accordingly.
5. Artur Some users may look into basic sample's source code to see how the editor is initialised. This code is pretty complex due the compatibility checks. Therefore we can leave in comments some explanation why so and how to replace a simple textarea (important - code of the textarea should also be included).
6. Artur Warning box below an editor should be displayed if the package doesn't include the wysiwygarea plugin. It should explain that without this plugin the classic mode will not work although inline editors and divarea-based ones will. <div class="tip"> from SDK should do the trick.

1. DONE The text content of the sample that I created is already outdated. See Ania's document for the most recent version.

Both

1. Create sprites, compress PNGs, compress CSS (there's a task for it, it works), compress fonts (AFAIR already compressed?).
2. We may decide whether to keep CSS in the repository. Since Less, CSS is useless in terms or diff and needs commiting each time something is changed in Lessfiles. It could be generated in some "init" grunt task, once the ckeditor-dev repository got cloned.

Old samples

1. DONE? Artur We need a very well visible box with info that this is old, deprecated sample (the same about the index).
2. Links to the basic sample and an appropriate sample in the SDK should be included.

Documentation review

1. We need to review and correct all places where we mention samples.
2. Toolbar configuration article should be updated.
3. Let's add a link to CDN in the download section of the quick start guide (in docs).
4. We must check the TOC which disappeared recently :|.

[Piotrek Koszuliński]

I pushed ​branch:t/12875 with the work started.

[Artur Delura]

1. Some users may look into basic sample's source code to see how the editor is initialised. This code is pretty complex due the compatibility checks. Therefore we can leave in comments some explanation why so and how to replace a simple textarea (important - code of the textarea should also be included).

Btw. For new samples we can use functionality from SDK which allow user to peek source code or download one. To do this we need include ​this file and tag properly code.

Update: Or maybe we should do more because this code was implemented with SDK in mind. Anyway, little research is needed.

[Artur Delura]

Both editors should by default load the toolbar layout that is actually set (which editor would use). Now they load all buttons in one row which is not true for normal editor. See the old toolbar sample to learn how to read toolbar layout.

The problem was because if we used editor with no toolbarGroups config option, then toolbar tools takes data from editor instance toolbar property and ommit separators. Now I changed the behaviour and it respect them.

[Artur Delura]

What if it does and if config.toolbarGroups is set?

I creates tool with such configuration otherwise it takes default configuration which is defined ​here.

[Artur Delura]

I also updated ​CKBuilder to work on proper samples directory. Changes in ​ckeditor/ckbuilder:/t/12875.

[Artur Delura]

Check whether the glyphs font used in the basic editor has the right license. We may also need to create a file in its directory with credits and its license.

​Here is a licence for font. Btw. we use it only for three icons.

How about creating subpage as we got in ​SDK?

[Olek Nowodziński]

Replying to Reinmar:

Toolbar editor

1. The toolbar editors version in the incubator repo should be abandoned. I had to make many changes (code style) when copying code to the ckeditor-dev repo. To avoid mistake we can actually remove the toolbar tool from the incubator now.
2. The name. In ​https://github.com/cksource/incubator/issues/6 we chose "toolbar configurator", but today I started using "toolbar editor" somehow automatically. I leave the final choice to you guys, but please remember that the name should be reflected in the directory name (currently it is toolbareditor/).
3. Config output format should be improved. As mentioned in ​https://github.com/cksource/incubator/issues/8 the format is ugly. Perfect solution would be as Ania mentioned - single quotes, nicely aligned and spaced. Acceptable result is that at least it will be nicely spaced and no double quotes. You can check the old toolbar tool because it was printing the config pretty well.
4. DONE The basic sample should link to the basic toolbar editor (the graphical one) which should link to the advanced one. (all is on one page)
5. Both editors need short description how to use them. There should be a link that points to a documentation available @ ​http://docs.ckeditor.com/.

I'd rather restrict it to advanced editor only. The basic one, with title attributes and column headers is pretty straightforward.

1. Use tooltips (simple HTML title attribute) to provide meaningful contextual help (remove separator, move group up etc.).

+1 (see above).

1. DONE Olek: Both editors' UX and UI must be polished.
2. Check whether the glyphs font used in the basic editor has the right license. We may also need to create a file in its directory with credits and its license.

The same applies to the fonts used in basic sample (Maven Pro, Indieflower). We use them on ckeditor.com but it does not mean that we can re-distribute them along with packages.

1. The same as above about the CodeMirror and plugins used with it.
2. Update CodeMirror if it got any updates. Also, I would consider installing it and the plugins we use through npm.
3. DONE Both editors should by default load the toolbar layout that is actually set (which editor would use). Now they load all buttons in one row which is not true for normal editor. See the old toolbar sample to learn how to read toolbar layout.
4. DONE: There's some error thrown right now.
5. DONE: We don't need the "Toggle editable" button.
6. DONE Olek: It would be good if toolbar buttons were not clickable. I checked that setting pointer-events: none on the toolbar element seems to be enough.
7. It's useful that the tool's width is proportional to window size - thanks to that one can check how the toolbar will behave in different widths.

As for making it wider than 960px, i.e. full window width – it's ugly. As for narrow viewports – it's done.

1. The "others" group could be displayed in the table (​https://github.com/cksource/incubator/issues/5).
2. DONE: In the basic toolbar editor change "Separator" to "Row separator" or something similarly meaningful.
3. DONE Olek: Reduce number of scrolls in the basic editor - there should be only one (I have two right now). (The floating toolbar makes sense.)
4. Artur: To be checked - how the toolbar editors read toolbar groups? What happens if one of loaded plugins defines its own group? What if it does and if config.toolbarGroups is set? This may be related - ​https://github.com/cksource/incubator/issues/4.
5. Toolbar editors should be checked on older IEs and if we have compatibility problems with something like IE10- we may just add there an alert that this browser is not supported.

The UI is IE8+ compatible. And it looks great in IE9+. I tested the UX and it was fine but there's nothing wrong with doing it again.

1. DONE Introduce "headers" in Basic sample so that users were aware that there are groups and subgroups.
2. REVIEW Artur: The toolbar editor should not jump on every change. It can be fixed by setting a minimum height on an element that contains the toolbar.
3. DONE Artur The page with toolbar editor should not scroll up when changing the order of groups.
4. There is no visual indication (outline) that up/down arrows are focused when using keyboard.

It's gonna be a task for Artur.

1. Highlighting toolbar groups on hover works only with small toolbars on big screens. With full toolbar (used by up to 50% of users) it is impossible to see the bottom groups highlighted on a toolbar after scrolling the page.

I didn't have much time to implement something with the floating toolbar. It may be the right solution.

1. Highlighting toolbar groups does not work on tablets or when one is using keyboard navigation only.

Hi, Artur :)

1. Olek Check the style of "Unused elements" in Advanced configurator.
2. DONE Bug: "Move up" button of a separator added without a context is enabled, though its the very first element of the list.

Basic sample

1. DONE We can actually link to the config.js file in the section about setting configuration. This will be nice because someone may notice there that it got cached if forgot to clear cache.
2. DONE I think that unfortunately the width of the page must be static, because entire full toolbar should fit there. This means that the font size should be pretty big, so it looks ok in lower res.
3. DONE I guess that look of the basic sample should be inspired by the SDK.
4. For the config section we chose uiColor and height which should cover 99.9% cases. We decided to place there entire code with CKEDITOR.editorConfig = functio() {};, so the text description must be updated accordingly.

I decided to put something more there. Just for fun. We may want to use hard-coded syntax highlighting there (copy-pasted HTML from a real highlighter) to match styles of CodeMirror. On the other hand, we don't use such thing in SDK, so it could be confusing.

I consider it a low-priority task at the moment.

1. Some users may look into basic sample's source code to see how the editor is initialised. This code is pretty complex due the compatibility checks. Therefore we can leave in comments some explanation why so and how to replace a simple textarea (important - code of the textarea should also be included).

Hi, Artur :)

1. Warning box below an editor should be displayed if the package doesn't include the wysiwygarea plugin. It should explain that without this plugin the classic mode will not work although inline editors and divarea-based ones will.

Hi, Artur :)

1. DONE The text content of the sample that I created is already outdated. See Ania's document for the most recent version.

Old samples

1. We need a very well visible box with info that this is old, deprecated sample (the same about the index). Links to the basic sample and an appropriate sample in the SDK should be included.

Documentation review

1. We need to review and correct all places where we mention samples.
2. Toolbar configuration article should be updated.
3. Let's add a link to CDN in the download section of the quick start guide (in docs).
4. We must check the TOC which disappeared recently :|.

[Piotrek Koszuliński]

We decided to track progress on ​http://trello.com/b/ilfdRj3p/12875-introduce-new-single-page-sample-and-toolbar-configurators

[Piotrek Koszuliński]

I closed #11168 as a DUP.

[Piotrek Koszuliński]

Great job guys! I've just merged this branch to major - ​git:681778d.

There will be few follow-up tickets for the stuff that we haven't yet addressed - ​https://trello.com/b/ilfdRj3p/12875-introduce-new-single-page-sample-and-toolbar-configurators