[xwiki-devs] [Proposal] GWT WYSIWYG - Macro handling behavior
Hi Marius and everyone, Here's an idea of a specification for macro handling in the new wysiwyg editor: * Macros are rendered when displayed in the editor * There's an outline so that the user can see what content corresponds to a macro * When the cursor is inside a macro the background color is changed * Clicking on Edit Macro to edit the selected macro * There's a background thread running that re-renders the page (and thus the macro) every N seconds. We need this since the macro content depends on other content (for example the TOC macro will depend on sections, the velocity macro will depend on values set in other velocity macros, etc). We should also have a way to let the user refresh the rendering manually. ** Note that since there are both inline and block macros we also need to refresh the rendering for that reason. For ex, if you put a velocity macro inside a list item and then you remove the list item the renderer result of the macro will be different (in the second case an extra paragraph will be added). * We should also have a button to switch between rendering macros and not rendering macros. For example when a page is including another page with some large content the user might want to disable macro rendering to focus only on the content of the current page. The default should be to render macros. WDYT? Thanks -Vincent
Hi, here are my thoughts on the topic: Here's an idea of a specification for macro handling in the new
wysiwyg editor:
* Macros are rendered when displayed in the editor
I think it's a
* There's an outline so that the user can see what content corresponds to a macro * When the cursor is inside a macro the background color is changed * Clicking on Edit Macro to edit the selected macro * There's a background thread running that re-renders the page (and thus the macro) every N seconds. We need this since the macro content depends on other content (for example the TOC macro will depend on sections, the velocity macro will depend on values set in other velocity macros, etc). We should also have a way to let the user refresh the rendering manually. ** Note that since there are both inline and block macros we also need to refresh the rendering for that reason. For ex, if you put a velocity macro inside a list item and then you remove the list item the renderer result of the macro will be different (in the second case an extra paragraph will be added). * We should also have a button to switch between rendering macros and not rendering macros. For example when a page is including another page with some large content the user might want to disable macro rendering to focus only on the content of the current page. The default should be to render macros.
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Lerouge Product Manager - XWiki Skype ID : wikibc http://blog.xwiki.com/
Re, looks like unexpected use of unpredictable keyboard shortcuts made my reply go out a bit too quickly :-)
Here's an idea of a specification for macro handling in the new
wysiwyg editor:
* Macros are rendered when displayed in the editor
I think it's a good idea since users want
* There's an outline so that the user can see what content corresponds to a macro * When the cursor is inside a macro the background color is changed
There are different kinds of macros and we might want to handle them differently: - Display macros (such as the infobox): they can already be identified as macros and don't need a refresh - Processing macros (such as the ToC): their text result cannot be distinguished from common text and they need to be refreshed To me, it would be better if content that belongs to a macro of which result is common text was always highlighted in a different background color, with an icon stating that this content was generated by a macro. This would make easier for an user to see where in the page she inserted macros. * Clicking on Edit Macro to edit the selected macro
Following Laurent's latest proposal, this means that the user would have to click on the macro menu item, then "edit macro" (it's fine with me, it was just to let other people know about it: http://dev.xwiki.org/xwiki/bin/download/Design/NewWysiwygEditorInterface/wys...)
* There's a background thread running that re-renders the page (and
thus the macro) every N seconds. We need this since the macro content depends on other content (for example the TOC macro will depend on sections, the velocity macro will depend on values set in other velocity macros, etc). We should also have a way to let the user refresh the rendering manually.
Do we really need a background thread to refresh macros? Here's why I don't think so: - There aren't that many macros that require continuous refresh, so it might be overkill - Refreshing at an arbitrary interval means that sometimes the user will see the updated results as soon as he makes a change (a new line in the ToC as soon as he adds a title) and sometimes there will be lagging (and he might wonder what went wrong) - This could be avoided if the background thread runs often enough, however I'd like to know more about the potential performance issues of running the thread every second for instance - Letting users refresh the display of their macros is good enough since macro's content won't need to be refreshed that often - Another solution could be to refresh the display of the macro each time the user puts the cursor within the boundaries of that macro display (when I click on a ToC item, the ToC is automatically refreshed before I can edit it) To summarize my point: I think refreshing macros when users interact with them is better than having a background thread running. WDYT? ** Note that since there are both inline and block macros we also need
to refresh the rendering for that reason. For ex, if you put a velocity macro inside a list item and then you remove the list item the renderer result of the macro will be different (in the second case an extra paragraph will be added).
Is that specific to macros? Whatever the content of the list item, it would have had to be handled (the paragraph added) => how is this affecting the macro itself directly?
* We should also have a button to switch between rendering macros and
not rendering macros. For example when a page is including another page with some large content the user might want to disable macro rendering to focus only on the content of the current page. The default should be to render macros.
+1 for the default being to render macros. Letting users turn off macros sounds like a power user feature to me, something the common user won't bother doing often, where would it fit? In the macro drop-down menu? Guillaume -- Guillaume Lerouge Product Manager - XWiki Skype ID : wikibc http://blog.xwiki.com/
Guillaume Lerouge wrote:
Re,
looks like unexpected use of unpredictable keyboard shortcuts made my reply go out a bit too quickly :-)
Here's an idea of a specification for macro handling in the new
wysiwyg editor:
* Macros are rendered when displayed in the editor
I think it's a good idea since users want
* There's an outline so that the user can see what content corresponds to a macro * When the cursor is inside a macro the background color is changed
There are different kinds of macros and we might want to handle them differently:
- Display macros (such as the infobox): they can already be identified as macros and don't need a refresh - Processing macros (such as the ToC): their text result cannot be distinguished from common text and they need to be refreshed
To me, it would be better if content that belongs to a macro of which result is common text was always highlighted in a different background color, with an icon stating that this content was generated by a macro. This would make easier for an user to see where in the page she inserted macros.
* Clicking on Edit Macro to edit the selected macro
So the user cannot edit the rendered content of the macro. He can navigate using arrow keys, he can select text, but he cannot type inside the outline corresponding to a macro. To change the output of the macro the user has to click on the Edit Macro button/menu (or double click) and edit the parameters of that macro (so he doesn't really edit the macro). The user will see then a generic dialog for changing macro parameters. He edits and presses OK. What happens next? Do we refresh the entire content of the editor or just the macros in it? If we refresh the entire content, the question that arises is do we allow the user to edit the content before we get the response with the updated version of the content. If we do, then the lag could be high enough allowing him to do important changes, forcing us to do some kind of merge between the two versions. If we don't, then he might not have the patience to wait for the request. We can refresh only the macros by adding an id to the outer-most container of each macro. We then use this id's to lookup the macros in the DOM document, when the response arrives. If we don't find an id (cause that macro may have been deleted) then we ignore it. This way we can allow the user to edit the page while the macros wait for their update. To be more user friendly, we can use a spinner over each macro to indicate its update process. To avoid updating all the macros when the user edits one of them we should have a way to specify if a macro has side effects or if it's isolated. Most of the macros don't have side effects and are isolated. So ideally the user should see a spinner only on those macros that need to be refreshed.
Following Laurent's latest proposal, this means that the user would have to click on the macro menu item, then "edit macro" (it's fine with me, it was just to let other people know about it: http://dev.xwiki.org/xwiki/bin/download/Design/NewWysiwygEditorInterface/wys...)
* There's a background thread running that re-renders the page (and
thus the macro) every N seconds. We need this since the macro content depends on other content (for example the TOC macro will depend on sections, the velocity macro will depend on values set in other velocity macros, etc). We should also have a way to let the user refresh the rendering manually.
Do we really need a background thread to refresh macros? Here's why I don't think so:
- There aren't that many macros that require continuous refresh, so it might be overkill - Refreshing at an arbitrary interval means that sometimes the user will see the updated results as soon as he makes a change (a new line in the ToC as soon as he adds a title) and sometimes there will be lagging (and he might wonder what went wrong) - This could be avoided if the background thread runs often enough, however I'd like to know more about the potential performance issues of running the thread every second for instance - Letting users refresh the display of their macros is good enough since macro's content won't need to be refreshed that often - Another solution could be to refresh the display of the macro each time the user puts the cursor within the boundaries of that macro display (when I click on a ToC item, the ToC is automatically refreshed before I can edit it)
I'm also more into triggering the update than using an update thread. We can trigger the update when: * changing the parameters of one of the macros (as I suggested above) * special refresh button/menu * click inside the macro outline (as suggested by Guillaume) In all this cases useless updates could be avoided by knowing what macro s are isolated from the host page.
To summarize my point: I think refreshing macros when users interact with them is better than having a background thread running. WDYT?
** Note that since there are both inline and block macros we also need
to refresh the rendering for that reason. For ex, if you put a velocity macro inside a list item and then you remove the list item the renderer result of the macro will be different (in the second case an extra paragraph will be added).
I don't think the output of the macro should depend on the place you insert it. I'd rather force the user to insert it in the right place by enabling/disabling that macro in the list of available macros depending on the current cursor position.
Is that specific to macros? Whatever the content of the list item, it would have had to be handled (the paragraph added) => how is this affecting the macro itself directly?
* We should also have a button to switch between rendering macros and
not rendering macros. For example when a page is including another page with some large content the user might want to disable macro rendering to focus only on the content of the current page. The default should be to render macros.
+1 for the default being to render macros. Letting users turn off macros sounds like a power user feature to me, something the common user won't bother doing often, where would it fit? In the macro drop-down menu?
+1 too, provided we use a place holder.
Guillaume
Btw, is there an API to get informations about macros, like: * the list of available macros * the number of parameters for a specific macro * parameter types (do we display an input box, a text area or a date picker?) * documentation for each parameter and for the macro its self? Thanks, Marius
Hi Marius, On Oct 21, 2008, at 4:37 PM, Marius Dumitru Florea wrote:
Guillaume Lerouge wrote:
Re,
looks like unexpected use of unpredictable keyboard shortcuts made my reply go out a bit too quickly :-)
Here's an idea of a specification for macro handling in the new
wysiwyg editor:
* Macros are rendered when displayed in the editor
I think it's a good idea since users want
* There's an outline so that the user can see what content corresponds to a macro * When the cursor is inside a macro the background color is changed
There are different kinds of macros and we might want to handle them differently:
- Display macros (such as the infobox): they can already be identified as macros and don't need a refresh - Processing macros (such as the ToC): their text result cannot be distinguished from common text and they need to be refreshed
To me, it would be better if content that belongs to a macro of which result is common text was always highlighted in a different background color, with an icon stating that this content was generated by a macro. This would make easier for an user to see where in the page she inserted macros.
* Clicking on Edit Macro to edit the selected macro
So the user cannot edit the rendered content of the macro.
Right he shouldn't be allowed to do that.
He can navigate using arrow keys, he can select text, but he cannot type inside the outline corresponding to a macro. To change the output of the macro the user has to click on the Edit Macro button/menu (or double click) and edit the parameters of that macro (so he doesn't really edit the macro). The user will see then a generic dialog for changing macro parameters. He edits and presses OK. What happens next? Do we refresh the entire content of the editor or just the macros in it?
The whole content is rendered again (i.e. HTML parser + XHTML renderer)
If we refresh the entire content, the question that arises is do we allow the user to edit the content before we get the response with the updated version of the content. If we do, then the lag could be high enough allowing him to do important changes, forcing us to do some kind of merge between the two versions. If we don't, then he might not have the patience to wait for the request.
We should wait. The rendering is supposed to be fast (same time as when you view a page). That shouldn't be more than a few ms on the rendering side.
We can refresh only the macros by adding an id to the outer-most container of each macro. We then use this id's to lookup the macros in the DOM document, when the response arrives. If we don't find an id (cause that macro may have been deleted) then we ignore it. This way we can allow the user to edit the page while the macros wait for their update. To be more user friendly, we can use a spinner over each macro to indicate its update process.
I'm not sure since macros have effects on other content and other macros. So IMO the whole content needs to be refreshed.
To avoid updating all the macros when the user edits one of them we should have a way to specify if a macro has side effects or if it's isolated. Most of the macros don't have side effects and are isolated. So ideally the user should see a spinner only on those macros that need to be refreshed.
I don't think that's required. It would also be too complex. In addition most macros have side effects (velocity, groovy, toc, html/ xhtml, id, etc). But that's not the problem. A page is indivisible and should be rendered all at once.
Following Laurent's latest proposal, this means that the user would have to click on the macro menu item, then "edit macro" (it's fine with me, it was just to let other people know about it: http://dev.xwiki.org/xwiki/bin/download/Design/NewWysiwygEditorInterface/wys...)
* There's a background thread running that re-renders the page (and
thus the macro) every N seconds. We need this since the macro content depends on other content (for example the TOC macro will depend on sections, the velocity macro will depend on values set in other velocity macros, etc). We should also have a way to let the user refresh the rendering manually.
Do we really need a background thread to refresh macros? Here's why I don't think so:
- There aren't that many macros that require continuous refresh, so it might be overkill - Refreshing at an arbitrary interval means that sometimes the user will see the updated results as soon as he makes a change (a new line in the ToC as soon as he adds a title) and sometimes there will be lagging (and he might wonder what went wrong) - This could be avoided if the background thread runs often enough, however I'd like to know more about the potential performance issues of running the thread every second for instance - Letting users refresh the display of their macros is good enough since macro's content won't need to be refreshed that often - Another solution could be to refresh the display of the macro each time the user puts the cursor within the boundaries of that macro display (when I click on a ToC item, the ToC is automatically refreshed before I can edit it)
I'm also more into triggering the update than using an update thread.
I agree too (at least for now in a first version).
We can trigger the update when:
* changing the parameters of one of the macros (as I suggested above)
+1
* special refresh button/menu
+1
* click inside the macro outline (as suggested by Guillaume)
-0 for now
In all this cases useless updates could be avoided by knowing what macro s are isolated from the host page.
To summarize my point: I think refreshing macros when users interact with them is better than having a background thread running. WDYT?
** Note that since there are both inline and block macros we also need
to refresh the rendering for that reason. For ex, if you put a velocity macro inside a list item and then you remove the list item the renderer result of the macro will be different (in the second case an extra paragraph will be added).
I don't think the output of the macro should depend on the place you insert it. I'd rather force the user to insert it in the right place by enabling/disabling that macro in the list of available macros depending on the current cursor position.
No that's not always possible. Of course, ideally, non-inline macros should not be offered when the user is inside a block element (list, paragraph, table, verbatim block, etc). But there are several macros that are both inline and standalone: velocity, groovy, html/xhtml, etc. Example: == {{velocity}}hello{{/velocity}} has a different output than: {{velocity}}hello{{/velocity}} (in the second case it generates a surrounding paragraph)
Is that specific to macros? Whatever the content of the list item, it would have had to be handled (the paragraph added) => how is this affecting the macro itself directly?
* We should also have a button to switch between rendering macros and
not rendering macros. For example when a page is including another page with some large content the user might want to disable macro rendering to focus only on the content of the current page. The default should be to render macros.
+1 for the default being to render macros. Letting users turn off macros sounds like a power user feature to me, something the common user won't bother doing often, where would it fit? In the macro drop-down menu?
+1 too, provided we use a place holder.
Agreed, the user would always need to see there's a macro at a given location.
Guillaume
Btw, is there an API to get informations about macros, like:
* the list of available macros
yes
* the number of parameters for a specific macro
yes
* parameter types (do we display an input box, a text area or a date picker?)
yes
* documentation for each parameter and for the macro its self?
yes Thanks -Vincent
participants (3)
-
Guillaume Lerouge -
Marius Dumitru Florea -
Vincent Massol