On Fri, Nov 9, 2018 at 5:35 PM Marius Dumitru Florea
<mariusdumitru.florea(a)xwiki.com> wrote:
On Fri, Nov 9, 2018 at 4:58 PM Adel Atallah <adel.atallah(a)xwiki.com> wrote:
On Fri, Nov 9, 2018 at 12:08 PM Marius Dumitru
Florea
<mariusdumitru.florea(a)xwiki.com> wrote:
Try to view the macro parameters listed as a boolean expression. For the
include macro we would have:
(page XOR (reference AND type) XOR document) OR section OR context
Wouldn't it be: (page XOR (reference AND
type) XOR document) *AND*
section *AND* context ?
No. AND means (logically) both sides are required. You can specify the
section parameter without specifying the context parameter. So it's
definitely a *logical / boolean* OR between them.
I put AND between reference and type just to show that there might be cases
when two (or more) parameters must be specified together (i.e. either you
specify both or you specify none of them). In our case the type parameter
has a default value so you can specify only the reference. This means it's
actually OR between reference and type in the case of the include macro.
I just feel like you can just have 2 types of
"operators": one to
exclude (XOR) and the other to include (AND) parameters.
I still think there can be 3 operators (if we want to cover everything). As
I said, you may want to express the fact that a parameter is mandatory only
if some other parameter is specified. We can't express this ATM so I guess
we can work only with XOR and OR.
* the parentheses define the parameter groups
* the boolean operators specify the relation between the members of a
group
We then need to express this using Java annotations. In any case, this
is a
**tree** structure (not a flat structure).
What you describe could probably be done with what we proposed but
maybe we can have something more explicit:
public void setReference(String reference)
@Depends("reference")
public void setType(EntityType type)
@Conflict("reference")
public void setPage(String page)
Could that work? We would need to write all the logic behind to build the
tree:
1. All parameters are joined by an 'AND' by default => page AND
reference AND type
2. Page and Reference are conflicting => (page XOR reference) AND type
3. Type depends on Reference => (page XOR (reference AND type))
WDYT?
I'm not sure how @Depends and @Conflict defines the tree structure in
general. I was rather thinking of something like:
@GroupPath("target[XOR]")
page
@GroupPath("target[XOR]/entityReference")
reference
@GroupPath("target[XOR]/entityReference")
type
@GroupPath("target[XOR]")
document
If we want subgroups then we need to specify a path. The complex part is to
specify the "operator" that should be used within a subgroup.
What we could do is use repeating annotations[1]:
@GroupPath(xor = "group1")
page
@GroupPath(xor = "group1")
@GroupPath(or = "group2", priority = 1)
reference
@GroupPath(xor = "group1")
@GroupPath(or = "group2", priority = 1)
type
@GroupPath(xor = "group1")
document
@GroupPath(and = "group3")
section
@GroupPath(and = "group3")
context
Everything in the "xor group" will be joined with a XOR. Fields will
be joined with an OR by default. The priority, which is by default 0,
defines the order of the "operations" (parenthesis). The previous
example would produce:
(page XOR (reference OR document) XOR document) OR (section AND context)
Maybe it's too complicated to use, WDYT?
Actually we could think of many cases where this would fail like:
@GroupPath(xor = "group")
field1
@GroupPath(and = "group")
field2
[1]:
https://docs.oracle.com/javase/tutorial/java/annotations/repeating.html
> >
> > On Fri, Nov 9, 2018 at 12:30 PM Adel Atallah <adel.atallah(a)xwiki.com>
> wrote:
> >
> > > On Fri, Nov 9, 2018 at 11:20 AM Marius Dumitru Florea
> > > <mariusdumitru.florea(a)xwiki.com> wrote:
> > > >
> > > > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah
<adel.atallah(a)xwiki.com>
> > > wrote:
> > > >
> > > > > Hello everyone,
> > > > >
> > > > > So what we thought about with Vincent for implementing the
> "concept of
> > > > > aliases or groups" would be to actually have two new
annotations
> that
> > > > > we would use on macro properties.
> > > > > The first one is a "Group" annotation which is meant
to indicate
> that
> > > > > some properties are part of the same group, obviously.
> > > > > The second is an "Alternative" annotation which is
meant to
> indicate
> > > > > that only one property / group of properties can be used (among
the
> > > > > ones that are part of the alternative).
> > > > > Here is an example:
> > > > > We want for the Include macro to be able to specify either:
> > > > > the "reference" and "type" parameters
> > > > > or
> > > > > the "page" parameter
> > > > > For that, we will change the IncludeMacroParameters java class
like
> > > this:
> > > > >
> > > > > @Alternative("reference")
> > > > > @Group("entityReference")
> > > > > public void setReference(String reference)
> > > > >
> > > > > @Alternative("reference")
> > > > > @Group("entityReference")
> > > > > public void setType(EntityType type)
> > > > >
> > > > > @Alternative("reference")
> > > > > public void setPage(String page)
> > > > >
> > > > > In the WYSIWYG side, we will only be able to specify either the
> > > > > "reference" and the "type" or the
"page" parameter.
> > > > >
> > > >
> > > > I think it would make more sense, at least in this case, to have the
> > > > alternative as an attribute of the group, because semantically the
> > > > "entityReference" group is an alternative to the page
parameter. You
> > > can't
> > > > say that the type parameter alone is an alternative to the page
> > > parameter.
> > > >
> > > > The @Group annotation is clear. No doubt about it. I'm not sure
about
> > > > the @Alternative annotation. I'm thinking that the
"alternative" is
> also
> > > a
> > > > group, where only one item from the group can be used, which could
be
> > > > expressed with an attribute of the @Group annotation.
> > >
> > > Thanks for the suggestion, but how can it be used? If I retake my
> previous
> > > example, will it be:
> > >
> > > @Group(name = "entityReference", alternative =
"reference")
> > > public void setReference(String reference)
> > >
> > > @Group(name = "entityReference", alternative =
"reference")
> > > public void setType(EntityType type)
> > >
> > > @Group(name = "page", alternative = "reference")
> > > public void setPage(String page)
> > >
> > > ?
> > > >
> > > >
> > > > >
> > > > > WDYT?
> > > > >
> > > > > Thanks,
> > > > > Adel
> > > > >
> > > > > On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> > > > > <mariusdumitru.florea(a)xwiki.com> wrote:
> > > > > >
> > > > > > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <
> vincent(a)massol.net>
> > > > > wrote:
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > > > On 19 Sep 2018, at 14:47, Adel Atallah <
> adel.atallah(a)xwiki.com>
> > > > > wrote:
> > > > > > > >
> > > > > > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol
<
> > > vincent(a)massol.net>
> > > > > > > wrote:
> > > > > > > >>
> > > > > > > >>
> > > > > > > >>
> > > > > > > >>> On 5 Jul 2018, at 12:06, Vincent Massol
<
> vincent(a)massol.net>
> > > > > wrote:
> > > > > > > >>>
> > > > > > > >>>
> > > > > > > >>>
> > > > > > > >>>> On 4 Jul 2018, at 12:07, Thomas
Mortagne <
> > > > > thomas.mortagne(a)xwiki.com>
> > > > > > > wrote:
> > > > > > > >>>>
> > > > > > > >>>> Here are more details on the actual
use case we need to
> > > support:
> > > > > > > >>>>
> > > > > > > >>>> In include/Display macro either you
set:
> > > > > > > >>>>
> > > > > > > >>>> * "reference" and
"type" (which default to DOCUMENT)
> > > > > > > >>>> * or you set “page"
> > > > > > > >>>
> > > > > > > >>> Globally I think we need to add 3
concepts to macro
> parameter
> > > > > > > descriptor:
> > > > > > > >>>
> > > > > > > >>> 1) The concept of “deprecated” parameter.
For example for
> > > > > “document”
> > > > > > > in the include macro.
> > > > > > > >>> 2) The concept of aliases or groups, i.e
the ability to
> list
> > > > > > > parameters that are mutually exclusive. Example:
reference +
> type
> > > vs
> > > > > page
> > > > > > > for display/include macros. This would mean that in
the Macro
> > > Dialog
> > > > > UI if
> > > > > > > you select one of those the other gets
unselected/cleared out
> (you
> > > > > cannot
> > > > > > > have mutually exclusive params have values).
> > > > > > > >>> 3) The concept of Advanced parameters.
For example, we
> should
> > > put
> > > > > > > reference + type as advanced parameters so that they
are not
> shown
> > > to
> > > > > the
> > > > > > > user by default (and so that the page parameter is
more
> > > highlighted).
> > > > > Users
> > > > > > > would need to click on Advanced to see advanced
parameters. I
> think
> > > > > we’re
> > > > > > > doing something automatic today (I don’t remember the
details)
> to
> > > try
> > > > > to
> > > > > > > hide some parameters but we should probably review
this.
> > > > > > > >>>
> > > > > > > >>> WDYT?
> > > > > > > >>
> > > > > > > >> Ping!
> > > > > > > >>
> > > > > > > >> Do we agree about this? If we do we can then
create jira
> issue
> > > > > about it
> > > > > > > and take it for implementation.
> > > > > > > >
> > > > > > > > +1, I can create the jira issue if it's ok.
> > > > > > >
> > > > > > > Please do :)
> > > > > > >
> > > > > > >
> > > > > >
> > > > > > > @Marius: Ok for you?
> > > > > > >
> > > > > >
> > > > > > Yes.
> > > > > >
> > > > > >
> > > > > > >
> > > > > > > thanks
> > > > > > > -Vincent
> > > > > > >
> > > > > > > [snip]
> > > > > > >
> > > > > > >
> > > > > > >
> > > > >
> > >
>