22 Oct
2008
22 Oct
'08
10:30 a.m.
Hi Marius,
On Oct 21, 2008, at 4:37 PM, Marius Dumitru Florea wrote:
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.
I agree too (at least for now in a first version).
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.
yes
Guillaume Lerouge wrote:
Right he shouldn't be allowed to do that.
Re,
looks like unexpected use of unpredictable keyboard shortcuts made
my reply
go out a bit too quickly :-)
So the user cannot edit the rendered content of the macro. Here's an idea of a specification for macro
handling in the new
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 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
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.
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.
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)
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.
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
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