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/wy…)
> * 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