Hi everyone,
I just edited the design page of the proposal after the meeting we had
yesterday with Vincent, Thomas and Marius:
https://design.xwiki.org/xwiki/bin/view/Main/MacroInlineEditingContent/
To quickly sum up the main parts are:
- we allow to specify a type in the ContentDescriptor of the macro
- we define a new MetaDataBlock for Java macro to specify which part
of the content is editable
- we document a new attribute for GroupBlock/FormatBlock to specify
which part of the content is editable in WikiMacro
Thanks again for your feedbacks!
Simon
On 9/12/18 6:46 PM, Thomas Mortagne wrote:
On Wed, Sep 12, 2018 at 5:56 PM Simon Urli <simon.u...@xwiki.com> wrote:
On 9/12/18 5:45 PM, Thomas Mortagne wrote:
Yeah I know, too many answer mails...
On Wed, Sep 12, 2018 at 5:28 PM Thomas Mortagne
<thomas.morta...@xwiki.com> wrote:
On Wed, Sep 12, 2018 at 5:07 PM Simon Urli <simon.u...@xwiki.com> wrote:
On 9/12/18 5:02 PM, Marius Dumitru Florea wrote:
On Wed, Sep 12, 2018 at 5:18 PM, Simon Urli <simon.u...@xwiki.com> wrote:
Hello everyone,
as a follow up of this proposal and the discussion we had, I just created
the following design proposal:
https://design.xwiki.org/xwiki/bin/view/Main/MacroInlineEditingContent/
Let me know what you think about it.
Regarding the Content Descriptor, which Syntax(es) will activate the inline
editing of the macro content? I'm asking because the Syntax of the content
is not the most important part. The most important part for the WYSIWYG
editor is to know if the macro code outputs the macro content without
transforming it. Without this it cannot enable inline editing. If the macro
output is rendered without modifications then the WYSIWYG editor can enable
inline editing but it needs to know in which Syntax to convert the HTML
produced while editing inline. So to summarize:
* First the WYSIWYG editor needs to know if the macro content is rendered
without modifications
* then the WYSIWYG editor needs to know the target Syntax to which to
convert the HTML
The WYSIWYG editor will know if it's editable if it exists a parser and
a renderer for this syntax.
You are mixing different things here:
* a macro which can be edited with A WYSIWYG for example in the model macro form
* a macro content which IS NOT TRANSFORMED BY THE MACRO and so can be
edited inline
So the target syntax is the given macro syntax.
There is several things I don't like about Syntax:
* You assume that the macro content is a XWiki Rendering content
(since that's what Syntax is for) with potential parser/renderer but
that's not the case for many (if not most) macros
No, the idea is to have something extensible: a macro can add a syntax,
and on the future, specify its own custom code to be used as an editor.
Without specifying any parser/renderer then.
The org.xwiki.rendering.syntax.Syntax class "Represents a wiki syntax
that the user can use to enter wiki content" according to its
definition. If what you want is not related to a content that can be
represented as XDOM then you should introduce a new type, it will also
avoid conflicting with existing Syntax which may define something very
different that what a Macro would like to express.
* Type is more consistent with parameters and there is no reason to
have two systems for the same need: describe what kind of data and
have a reusable set of displayers for each type of data. Also it's not
just about macro parameters we use the same system in other places
(Filter input/output parameters for example).
Could you elaborate how do you see things with type? Should we create a
different type for each macro content then? And we would have to create
the proper types for plain/html/wiki content?
Here are the types you need right now:
* plain/undefined content: java.lang.String (the default since that's
the current behavior)
* wiki content for which the syntax depends on the location of the
macro: as I said in a previous mail we have existing types for this
already, Block, List<XDOM> or CompositeBlock (possibly XDOM for macros
which can only be used in a standalone context if we want to express
in the type even if it duplicates Macro#supportsInlineMode()) express
it well already. But since we also need "not transformed wiki content"
for inline editing in the WYSIWYG we could introduce a new type to
express that, something like "FinalCompositeBlock extends
CompositeBlock" or some other name (we could arbitrary decide that
CompositeBlock means final but I don't think it would be clear enough)
Here are a few example for the future:
* template (as defined by
https://extensions.xwiki.org/xwiki/bin/view/Extension/Template+Module#HContent):
org.xwiki.template.TemplateContent
* html: I can't think of anything clean enough so probably a new type yes
* velocity, groovy, python, etc.: new types but we can still make
generic code life a bit easier (at least on Java side) with something
like a new "VelocityContent" type annotated with
@ScriptContent("velocity") for example
* specific wiki content (I don't think we have the use case right now
but never knows): same logic as for script contents I guess
* <many other types used in the parameters already>
All that could be expressed with names instead of Java types but the
point of using Types is that:
* well that's made to define type of stuff after all :)
* more importantly we can use the same system for macro parameters,
filter properties and content (and other stuff in the future) to find
out a suitable displayer/editor. For example some macro have the need
to take wiki content as parameter too.
* Even if macro content was only about rendering content syntax is not
very well suited to differentiate between content transformed by the
macro (takes wiki content as input data but produce something which
may have nothing to do with it) and content not transformed by the
macro (just parse/render the content with stuff around it) since it
has nothing to do with the actual content syntax.
As I said, the idea is to allow user to be able to specify their own
editor.
Thanks,
Simon
On 9/10/18 6:46 PM, Thomas Mortagne wrote:
On Mon, Sep 10, 2018 at 3:47 PM Simon Urli <simon.u...@xwiki.com> wrote:
On 9/10/18 3:24 PM, Marius Dumitru Florea wrote:
On Mon, Sep 10, 2018 at 4:07 PM, Thomas Mortagne <
thomas.morta...@xwiki.com>
wrote:
On Mon, Sep 10, 2018 at 2:56 PM Marius Dumitru Florea
<mariusdumitru.flo...@xwiki.com> wrote:
On Mon, Sep 10, 2018 at 3:42 PM, Thomas Mortagne <
thomas.morta...@xwiki.com>
wrote:
On Mon, Sep 10, 2018 at 2:13 PM Simon Urli <simon.u...@xwiki.com>
wrote:
On 9/10/18 1:35 PM, Vincent Massol wrote:
Hi Simon,
On 10 Sep 2018, at 13:05, Simon Urli <simon.u...@xwiki.com>
wrote:
Hi everyone,
I'm working on the roadmap issues related to the inline edition
with
WYSIWYG editor for macro content and macro parameters.
Cool :) We've been waiting for a long time about this feature! See
below.
The first step is to add a flag to allow user specify that a
content
or a parameter can be edited inline with the WYSIWYG editor.
The second step is to allow the CKEditor to detect where the
content
and/or parameters should be edited.
Let's take the exampe of a simple macro without any parameter,
which
currently produces this code:
<div class="box infomessage">
<div class="title">
<span class="icon info"></span>
some title
</div>
Some content
</div>
We propose (me & Marius) to ask users to add a wrapper with a
specific class around the content to tell the editor it should only
allow
editing this content, e.g.:
<div class="box infomessage">
<div class="title">
<span class="icon info"></span>
some title
</div>
<span class="editable-content">Some content</span>
</div>
By “users”, I guess you mean macro developers?
Here yes it's the macro developer. I'll try to be more specific in
my
answers.
So if I understand you well, you’re not planning to add a
getter/setters to the Macro descriptor, to tell that the macro
content
contains wiki markup and that it should be editable in the WYSIWYG
editor?
Actually we're planning to add the getter/setter **and** the
specific
markup for the editor. The getter/setter (which I called the flag
above), is here to specify that the macro will contain inline
editable
content in WYSIWYG. The markup will specify *where* exactly is this
content, and what shouldn't be changed.
About that "flag", you seems to plan a boolean but I feel something
more generic that we want to introduce since a long time would be
better: make the content descriptor return a type like parameters
descriptors do. The kind of inline editing you have in mind right now
would then be associated to the type List<Block> for example (or
CompositeBlock
or some another type if we want to differentiate
between wiki content modified by the macro and wiki content not
modified by the macro
We need this differentiation.
Sure but as I said you can differentiate using types too and we need
content types for other use cases so it's a good occasion. Also when
you use the type you can differentiate between wiki content and HTML
content and support inline editing of HTML macro in the same system
for example.
I'm not against your proposal. It's a bit more work though, to define
the
types, but I suppose it's worth the effort.
It's not much more work, just need to define one type for the current
use case ("final" wiki content). Other types can come later when
implementing support for them.
So if I follow the idea would be to use this type defined for the
content descriptor to specify the behaviour of the editor: e.g. if the
content descriptor is defined as an html content, then the html editor
would be used, if it's defined as an inline content, then it would be an
editor with limitation to clean html and line returns, etc.
Still it does not change the need to specify which elements of the
content are editable, right?
Sure but that's the "second step". I only talked about replacing the
flag you defined as the first step by a more generic type :)
Moreover I've the feeling that the parameters are already not supporting
the different types for edition (e.g. a boolean parameter only shows a
text input). So wouldn't it be a priority before putting a type on the
content descriptor itself?
The WYSIWYG does miss a lot of displayers and we need work on that for
sure but:
* you get a checkbox for boolean properties so the type is taken into
account
* having more specific displayers is not a requirement for working on
inline wiki editing
). The other types would be used in other use
cases (syntax coloring for scripts, json editor, etc.). The idea of
using Java type is to be consistent with parameters and reuse
existing
the displayers in the macro modal window for example but it can cover
this need too.
I guess that if the flag is set and the markup is not present, then
the
entire content is considered as editable.
Is that because you want to be finer-grained and have macro content
which can have parts editable with the WYSIWYG while having other
parts of
the content not editable (for example)?
It's exactly why yes. On my example, the macro user won't be able to
change the content of the title.
Technically Macros don’t generate HTML, only XDOM. So in order to
make
it easier for java macro developers, I’d suggest to introduce some new
wrapping Block to indicate this information. We might need something
similar for wiki macros too, to make it more reusable and typed.
I'd need to look more on wrapping block but after a quick overlook
it
seems to make sense indeed.
About parameters, our idea was to define a new metadata attribute
and
to ask users to use it for specifying the content is editable, such as
for
a parameter named foo:
<span class="editable-content" data-parameter="foo">my foo
parameter
value</span>
What’s your idea for editing parameters requiring WYSIWYG? How do
you
present them in the UI? Do you have any mockup?
I don't have any mockup right now. FTM I see it like this:
- when creating the macro, the current text input are improved
with
the CKEditor for the editable content/parameters
- when editing the macro, you stay in the main editor UI, but
the
content is now editable instead of opening back the macro UI
However I don't know right now how the editor would manage cases
such
as:
<span class="editable-content">Some content with <span
class="editable-content" data-parameter="myparameter">a
parameter</span></span>
So:
1. Do you agree on the usage of a class named
"editable-content"
which would be used as a tag to allow inline edition?
Small details, there’s already the “contenteditable” notion that
exists (see https://developer.mozilla.org/
fr/docs/Web/HTML/Attributs_
universels/contenteditable) so “editable-content” is quite close.
Maybe
we should have something more xwiki-specific? or more
WYSIWYG-specific?
Like “editable-wysiwyg” or “wysiwyg-editable”.
I'm open to suggestion on this one. "wysiwyg-editable" could be
nice.
My main comment is what I put above: how do we make it easy for
macro
developers to specify this information.
2. WDYT about using a data-parameter and this class for inline
editing of parameters?
Before answering that part, I would need to understand what’s the
proposal in term of UI.
Note that the main use case is for content but it’s nice if you can
also support parameters. Now, accepting markup in parameters is not
really
a great use case IMO and is usually a design issue so I’m not sure we
should spend that much time in supporting that. WDYT?
We just discuss about macro parameters with Ludovic and apparently
they
cannot support line returns, so we might have to use a custom editor
for
those.
The only macro parameter I know ATM that supports markup is the
“title” param of the {{box}} macro and I think it’s badly designed.
Note:
if you check the recent {{figure}} macro, I implemented this need by
having
a {{figureCaption}} nested macro.
BTW this raises a question, will you support WYSIWYG editing of
nested
macros?
Not for the moment.
Simon
Thanks
-Vincent
Thanks,
Simon
[snip]
--
Simon Urli
Software Engineer at XWiki SAS
simon.u...@xwiki.com
More about us at http://www.xwiki.com
--
Thomas Mortagne
--
Thomas Mortagne
--
Simon Urli
Software Engineer at XWiki SAS
simon.u...@xwiki.com
More about us at http://www.xwiki.com
--
Simon Urli
Software Engineer at XWiki SAS
simon.u...@xwiki.com
More about us at http://www.xwiki.com
--
Simon Urli
Software Engineer at XWiki SAS
simon.u...@xwiki.com
More about us at http://www.xwiki.com
--
Thomas Mortagne
--
Simon Urli
Software Engineer at XWiki SAS
simon.u...@xwiki.com
More about us at http://www.xwiki.com
--
Simon Urli
Software Engineer at XWiki SAS
simon.u...@xwiki.com
More about us at http://www.xwiki.com
