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/wysiwyg2.pdf) >> >> >>> * 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 _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
