[Proposal] Document picker in include and display macros

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposal] Document picker in include and display macros

Adel Atallah
Hi devs,

After discussing with Marius and Thomas, we thought it might be a good
idea to do the following to have a document picker in the include and
display maros:
* Remove the deprecation of the document parameter (only for the include macro).
* Introduce a new annotation to macro parameters to specify / override
its type (different from its actual java type).

The new annotation will mostly be useful for the WYSIWYG side. In our
case we want to use the document parameter which is a String. The
annotation will allow us to work with a DocumentReference instead
which can be used to display the document picker when editing the
macro in WYSIWYG mode.

To be clear, here is how we would use it:
  @PropertyType(DocumentReference.class)
   public void setDocument(String document)

WDYT?

Thanks,
Adel
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Thomas Mortagne
Administrator
On Thu, Jan 17, 2019 at 11:05 AM Adel Atallah <[hidden email]> wrote:

>
> Hi devs,
>
> After discussing with Marius and Thomas, we thought it might be a good
> idea to do the following to have a document picker in the include and
> display maros:
> * Remove the deprecation of the document parameter (only for the include macro).
> * Introduce a new annotation to macro parameters to specify / override
> its type (different from its actual java type).
>
> The new annotation will mostly be useful for the WYSIWYG side. In our
> case we want to use the document parameter which is a String. The
> annotation will allow us to work with a DocumentReference instead
> which can be used to display the document picker when editing the
> macro in WYSIWYG mode.
>
> To be clear, here is how we would use it:
>   @PropertyType(DocumentReference.class)
>    public void setDocument(String document)
>
> WDYT?
>
> Thanks,
> Adel

+1
--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

vmassol
Administrator
In reply to this post by Adel Atallah
Hi Adel,

> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]> wrote:
>
> Hi devs,
>
> After discussing with Marius and Thomas, we thought it might be a good
> idea to do the following to have a document picker in the include and
> display maros:
> * Remove the deprecation of the document parameter (only for the include macro).

I don’t understand this part. Sounds counter-intuitive to me since we want users to use the “reference” one. Could you explain?

Thanks
-Vincent

> * Introduce a new annotation to macro parameters to specify / override
> its type (different from its actual java type).
>
> The new annotation will mostly be useful for the WYSIWYG side. In our
> case we want to use the document parameter which is a String. The
> annotation will allow us to work with a DocumentReference instead
> which can be used to display the document picker when editing the
> macro in WYSIWYG mode.
>
> To be clear, here is how we would use it:
>  @PropertyType(DocumentReference.class)
>   public void setDocument(String document)
>
> WDYT?
>
> Thanks,
> Adel

Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Adel Atallah
On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]> wrote:

>
> Hi Adel,
>
> > On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]> wrote:
> >
> > Hi devs,
> >
> > After discussing with Marius and Thomas, we thought it might be a good
> > idea to do the following to have a document picker in the include and
> > display maros:
> > * Remove the deprecation of the document parameter (only for the include macro).
>
> I don’t understand this part. Sounds counter-intuitive to me since we want users to use the “reference” one. Could you explain?

We currently only have a document picker that we can use for
DocumentReferences. To have auto-suggestion on the "reference"
parameter, we would need to make another picker for all type of
references, not just document.

>
> Thanks
> -Vincent
>
> > * Introduce a new annotation to macro parameters to specify / override
> > its type (different from its actual java type).
> >
> > The new annotation will mostly be useful for the WYSIWYG side. In our
> > case we want to use the document parameter which is a String. The
> > annotation will allow us to work with a DocumentReference instead
> > which can be used to display the document picker when editing the
> > macro in WYSIWYG mode.
> >
> > To be clear, here is how we would use it:
> >  @PropertyType(DocumentReference.class)
> >   public void setDocument(String document)
> >
> > WDYT?
> >
> > Thanks,
> > Adel
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

vmassol
Administrator
Hi Adel,

> On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]> wrote:
>
> On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]> wrote:
>>
>> Hi Adel,
>>
>>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]> wrote:
>>>
>>> Hi devs,
>>>
>>> After discussing with Marius and Thomas, we thought it might be a good
>>> idea to do the following to have a document picker in the include and
>>> display maros:
>>> * Remove the deprecation of the document parameter (only for the include macro).
>>
>> I don’t understand this part. Sounds counter-intuitive to me since we want users to use the “reference” one. Could you explain?
>
> We currently only have a document picker that we can use for
> DocumentReferences. To have auto-suggestion on the "reference"
> parameter, we would need to make another picker for all type of
> references, not just document.

Ok I understand.

But I don’t think it’s a good idea to remove the deprecation on “document”. This is deprecated for a good reason. And if we undeprecate it then we’ll need to redeprecate it soon enough and it also means “deprecating" “reference” so that it’s moved to the advanced section. It’s also bad for users who’ve been told to not use the “document” parameter. Without mentioning that the document parameter is only available in the legacy module and thus without legacy modules it wouldn’t work. Raises plenty of problems.

Other Ideas instead:
1) Use the DocumentReference picker when the Type is Document and when the type is changed to something else, let the user type the reference.
2) Improve the picker to support picking any type of references: documents, spaces, wiki, attachments, objects, properties.
3) Now in practice the include macro only supports including Documents so we could also simply do an override as you suggested (but on the “reference” field), that would be used only for the WYSIWYG (when in wiki mode you’d be able to enter only Document references). However if the user has used the macro in wiki mode, we’ll need to only display the DocumentReference picker if the type is Document.

<side note>
I don’t think there are really good user use-cases for using something else than the Document type since it’ll always translate into a Document in the end so the user can always pick that doc instead of letting the macro resolve it for him.
</side note>

Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too late already since we’re releasing RC Monday!) then we could push that one for later for the include/display macros and instead support other and simpler well known macros in 11.0, from https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros, like DocumentTree macro.

What I’d like is to have at least one macro that can use the picker in 11.0, mostly to prove that it works and to have something to report for users in the release notes and to show progress.

Thanks
-Vincent

>
>>
>> Thanks
>> -Vincent
>>
>>> * Introduce a new annotation to macro parameters to specify / override
>>> its type (different from its actual java type).
>>>
>>> The new annotation will mostly be useful for the WYSIWYG side. In our
>>> case we want to use the document parameter which is a String. The
>>> annotation will allow us to work with a DocumentReference instead
>>> which can be used to display the document picker when editing the
>>> macro in WYSIWYG mode.
>>>
>>> To be clear, here is how we would use it:
>>> @PropertyType(DocumentReference.class)
>>>  public void setDocument(String document)
>>>
>>> WDYT?
>>>
>>> Thanks,
>>> Adel

Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Adel Atallah
On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol <[hidden email]> wrote:

>
> Hi Adel,
>
> > On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]> wrote:
> >
> > On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]> wrote:
> >>
> >> Hi Adel,
> >>
> >>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]> wrote:
> >>>
> >>> Hi devs,
> >>>
> >>> After discussing with Marius and Thomas, we thought it might be a good
> >>> idea to do the following to have a document picker in the include and
> >>> display maros:
> >>> * Remove the deprecation of the document parameter (only for the include macro).
> >>
> >> I don’t understand this part. Sounds counter-intuitive to me since we want users to use the “reference” one. Could you explain?
> >
> > We currently only have a document picker that we can use for
> > DocumentReferences. To have auto-suggestion on the "reference"
> > parameter, we would need to make another picker for all type of
> > references, not just document.
>
> Ok I understand.
>
> But I don’t think it’s a good idea to remove the deprecation on “document”. This is deprecated for a good reason. And if we undeprecate it then we’ll need to redeprecate it soon enough and it also means “deprecating" “reference” so that it’s moved to the advanced section. It’s also bad for users who’ve been told to not use the “document” parameter. Without mentioning that the document parameter is only available in the legacy module and thus without legacy modules it wouldn’t work. Raises plenty of problems.
>
> Other Ideas instead:
> 1) Use the DocumentReference picker when the Type is Document and when the type is changed to something else, let the user type the reference.
> 2) Improve the picker to support picking any type of references: documents, spaces, wiki, attachments, objects, properties.
> 3) Now in practice the include macro only supports including Documents so we could also simply do an override as you suggested (but on the “reference” field), that would be used only for the WYSIWYG (when in wiki mode you’d be able to enter only Document references). However if the user has used the macro in wiki mode, we’ll need to only display the DocumentReference picker if the type is Document.

I think 3) is the simplest solution for now. We could always show the
document picker on the "reference" field but allow free text so that
other references can be manually entered.

>
> <side note>
> I don’t think there are really good user use-cases for using something else than the Document type since it’ll always translate into a Document in the end so the user can always pick that doc instead of letting the macro resolve it for him.
> </side note>
>
> Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too late already since we’re releasing RC Monday!) then we could push that one for later for the include/display macros and instead support other and simpler well known macros in 11.0, from https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros, like DocumentTree macro.
>
> What I’d like is to have at least one macro that can use the picker in 11.0, mostly to prove that it works and to have something to report for users in the release notes and to show progress.
>
> Thanks
> -Vincent
>
> >
> >>
> >> Thanks
> >> -Vincent
> >>
> >>> * Introduce a new annotation to macro parameters to specify / override
> >>> its type (different from its actual java type).
> >>>
> >>> The new annotation will mostly be useful for the WYSIWYG side. In our
> >>> case we want to use the document parameter which is a String. The
> >>> annotation will allow us to work with a DocumentReference instead
> >>> which can be used to display the document picker when editing the
> >>> macro in WYSIWYG mode.
> >>>
> >>> To be clear, here is how we would use it:
> >>> @PropertyType(DocumentReference.class)
> >>>  public void setDocument(String document)
> >>>
> >>> WDYT?
> >>>
> >>> Thanks,
> >>> Adel
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Adel Atallah
To sum up, here is what I can do:

On XWiki Commons:
* Introduce a PropertyDisplayType annotation that we can use to
specify with which type the macro parameter should be rendered.
* Add the *display type* in the property descriptor (use the existing
*property type* as default)

On XWiki Rendering:
* Add the *display type* in the parameter descriptor (use the existing
*property type* as default)

On XWiki Platform:
* Use the PropertyDisplayType annotation, on reference macro
parameters, with the EntityReference type (for the include and display
macro)
* Display a document picker for the EntityReference type and make sure
free text is enabled (so that we can enter a reference manually)

On the CKeditor application:
* Use the *display type* instead of the *property type* when using the
html displayer.

I'll create the Jira issues and make the related PRs if we agree on this.

On Mon, Jan 21, 2019 at 9:30 AM Adel Atallah <[hidden email]> wrote:

>
> On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol <[hidden email]> wrote:
> >
> > Hi Adel,
> >
> > > On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]> wrote:
> > >
> > > On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]> wrote:
> > >>
> > >> Hi Adel,
> > >>
> > >>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]> wrote:
> > >>>
> > >>> Hi devs,
> > >>>
> > >>> After discussing with Marius and Thomas, we thought it might be a good
> > >>> idea to do the following to have a document picker in the include and
> > >>> display maros:
> > >>> * Remove the deprecation of the document parameter (only for the include macro).
> > >>
> > >> I don’t understand this part. Sounds counter-intuitive to me since we want users to use the “reference” one. Could you explain?
> > >
> > > We currently only have a document picker that we can use for
> > > DocumentReferences. To have auto-suggestion on the "reference"
> > > parameter, we would need to make another picker for all type of
> > > references, not just document.
> >
> > Ok I understand.
> >
> > But I don’t think it’s a good idea to remove the deprecation on “document”. This is deprecated for a good reason. And if we undeprecate it then we’ll need to redeprecate it soon enough and it also means “deprecating" “reference” so that it’s moved to the advanced section. It’s also bad for users who’ve been told to not use the “document” parameter. Without mentioning that the document parameter is only available in the legacy module and thus without legacy modules it wouldn’t work. Raises plenty of problems.
> >
> > Other Ideas instead:
> > 1) Use the DocumentReference picker when the Type is Document and when the type is changed to something else, let the user type the reference.
> > 2) Improve the picker to support picking any type of references: documents, spaces, wiki, attachments, objects, properties.
> > 3) Now in practice the include macro only supports including Documents so we could also simply do an override as you suggested (but on the “reference” field), that would be used only for the WYSIWYG (when in wiki mode you’d be able to enter only Document references). However if the user has used the macro in wiki mode, we’ll need to only display the DocumentReference picker if the type is Document.
>
> I think 3) is the simplest solution for now. We could always show the
> document picker on the "reference" field but allow free text so that
> other references can be manually entered.
>
> >
> > <side note>
> > I don’t think there are really good user use-cases for using something else than the Document type since it’ll always translate into a Document in the end so the user can always pick that doc instead of letting the macro resolve it for him.
> > </side note>
> >
> > Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too late already since we’re releasing RC Monday!) then we could push that one for later for the include/display macros and instead support other and simpler well known macros in 11.0, from https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros, like DocumentTree macro.
> >
> > What I’d like is to have at least one macro that can use the picker in 11.0, mostly to prove that it works and to have something to report for users in the release notes and to show progress.
> >
> > Thanks
> > -Vincent
> >
> > >
> > >>
> > >> Thanks
> > >> -Vincent
> > >>
> > >>> * Introduce a new annotation to macro parameters to specify / override
> > >>> its type (different from its actual java type).
> > >>>
> > >>> The new annotation will mostly be useful for the WYSIWYG side. In our
> > >>> case we want to use the document parameter which is a String. The
> > >>> annotation will allow us to work with a DocumentReference instead
> > >>> which can be used to display the document picker when editing the
> > >>> macro in WYSIWYG mode.
> > >>>
> > >>> To be clear, here is how we would use it:
> > >>> @PropertyType(DocumentReference.class)
> > >>>  public void setDocument(String document)
> > >>>
> > >>> WDYT?
> > >>>
> > >>> Thanks,
> > >>> Adel
> >
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Thomas Mortagne
Administrator
Sounds good. +1 for me

I would also add:

* Use the PropertyDisplayType annotation, on page macro
parameters, with the PageReference type (for the include and display
macro). Does not cost anything and won't have any effect yet but it
prepare for the future since that's what we'll want to do.

On Mon, Jan 21, 2019 at 3:10 PM Adel Atallah <[hidden email]> wrote:

>
> To sum up, here is what I can do:
>
> On XWiki Commons:
> * Introduce a PropertyDisplayType annotation that we can use to
> specify with which type the macro parameter should be rendered.
> * Add the *display type* in the property descriptor (use the existing
> *property type* as default)
>
> On XWiki Rendering:
> * Add the *display type* in the parameter descriptor (use the existing
> *property type* as default)
>
> On XWiki Platform:
> * Use the PropertyDisplayType annotation, on reference macro
> parameters, with the EntityReference type (for the include and display
> macro)
> * Display a document picker for the EntityReference type and make sure
> free text is enabled (so that we can enter a reference manually)
>
> On the CKeditor application:
> * Use the *display type* instead of the *property type* when using the
> html displayer.
>
> I'll create the Jira issues and make the related PRs if we agree on this.
>
> On Mon, Jan 21, 2019 at 9:30 AM Adel Atallah <[hidden email]> wrote:
> >
> > On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol <[hidden email]> wrote:
> > >
> > > Hi Adel,
> > >
> > > > On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]> wrote:
> > > >
> > > > On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]> wrote:
> > > >>
> > > >> Hi Adel,
> > > >>
> > > >>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]> wrote:
> > > >>>
> > > >>> Hi devs,
> > > >>>
> > > >>> After discussing with Marius and Thomas, we thought it might be a good
> > > >>> idea to do the following to have a document picker in the include and
> > > >>> display maros:
> > > >>> * Remove the deprecation of the document parameter (only for the include macro).
> > > >>
> > > >> I don’t understand this part. Sounds counter-intuitive to me since we want users to use the “reference” one. Could you explain?
> > > >
> > > > We currently only have a document picker that we can use for
> > > > DocumentReferences. To have auto-suggestion on the "reference"
> > > > parameter, we would need to make another picker for all type of
> > > > references, not just document.
> > >
> > > Ok I understand.
> > >
> > > But I don’t think it’s a good idea to remove the deprecation on “document”. This is deprecated for a good reason. And if we undeprecate it then we’ll need to redeprecate it soon enough and it also means “deprecating" “reference” so that it’s moved to the advanced section. It’s also bad for users who’ve been told to not use the “document” parameter. Without mentioning that the document parameter is only available in the legacy module and thus without legacy modules it wouldn’t work. Raises plenty of problems.
> > >
> > > Other Ideas instead:
> > > 1) Use the DocumentReference picker when the Type is Document and when the type is changed to something else, let the user type the reference.
> > > 2) Improve the picker to support picking any type of references: documents, spaces, wiki, attachments, objects, properties.
> > > 3) Now in practice the include macro only supports including Documents so we could also simply do an override as you suggested (but on the “reference” field), that would be used only for the WYSIWYG (when in wiki mode you’d be able to enter only Document references). However if the user has used the macro in wiki mode, we’ll need to only display the DocumentReference picker if the type is Document.
> >
> > I think 3) is the simplest solution for now. We could always show the
> > document picker on the "reference" field but allow free text so that
> > other references can be manually entered.
> >
> > >
> > > <side note>
> > > I don’t think there are really good user use-cases for using something else than the Document type since it’ll always translate into a Document in the end so the user can always pick that doc instead of letting the macro resolve it for him.
> > > </side note>
> > >
> > > Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too late already since we’re releasing RC Monday!) then we could push that one for later for the include/display macros and instead support other and simpler well known macros in 11.0, from https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros, like DocumentTree macro.
> > >
> > > What I’d like is to have at least one macro that can use the picker in 11.0, mostly to prove that it works and to have something to report for users in the release notes and to show progress.
> > >
> > > Thanks
> > > -Vincent
> > >
> > > >
> > > >>
> > > >> Thanks
> > > >> -Vincent
> > > >>
> > > >>> * Introduce a new annotation to macro parameters to specify / override
> > > >>> its type (different from its actual java type).
> > > >>>
> > > >>> The new annotation will mostly be useful for the WYSIWYG side. In our
> > > >>> case we want to use the document parameter which is a String. The
> > > >>> annotation will allow us to work with a DocumentReference instead
> > > >>> which can be used to display the document picker when editing the
> > > >>> macro in WYSIWYG mode.
> > > >>>
> > > >>> To be clear, here is how we would use it:
> > > >>> @PropertyType(DocumentReference.class)
> > > >>>  public void setDocument(String document)
> > > >>>
> > > >>> WDYT?
> > > >>>
> > > >>> Thanks,
> > > >>> Adel
> > >



--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Marius Dumitru Florea
In reply to this post by Adel Atallah
On Mon, Jan 21, 2019 at 4:10 PM Adel Atallah <[hidden email]> wrote:

> To sum up, here is what I can do:
>
> On XWiki Commons:
> * Introduce a PropertyDisplayType annotation that we can use to
> specify with which type the macro parameter should be rendered.
> * Add the *display type* in the property descriptor (use the existing
> *property type* as default)
>
> On XWiki Rendering:
> * Add the *display type* in the parameter descriptor (use the existing
> *property type* as default)
>
> On XWiki Platform:
> * Use the PropertyDisplayType annotation, on reference macro
> parameters, with the EntityReference type (for the include and display
> macro)
>


> * Display a document picker for the EntityReference type and make sure
> free text is enabled (so that we can enter a reference manually)
>

It's not that simple.. If the reference parameter already has a value that
is not a document reference then by showing the document picker that value
will be parsed / resolved as a document reference and thus displayed as if
a document has been selected. This can confuse the users. For instance, if
someone writes in wiki syntax:

{{include reference="[hidden email]" type="ATTACHMENT"/}}

and then edit the page with the WYSIWYG editor, he will see "txt" as
selected value when editing the macro...


>
> On the CKeditor application:
> * Use the *display type* instead of the *property type* when using the
> html displayer.
>
> I'll create the Jira issues and make the related PRs if we agree on this.
>
> On Mon, Jan 21, 2019 at 9:30 AM Adel Atallah <[hidden email]>
> wrote:
> >
> > On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol <[hidden email]>
> wrote:
> > >
> > > Hi Adel,
> > >
> > > > On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]>
> wrote:
> > > >
> > > > On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]>
> wrote:
> > > >>
> > > >> Hi Adel,
> > > >>
> > > >>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]>
> wrote:
> > > >>>
> > > >>> Hi devs,
> > > >>>
> > > >>> After discussing with Marius and Thomas, we thought it might be a
> good
> > > >>> idea to do the following to have a document picker in the include
> and
> > > >>> display maros:
> > > >>> * Remove the deprecation of the document parameter (only for the
> include macro).
> > > >>
> > > >> I don’t understand this part. Sounds counter-intuitive to me since
> we want users to use the “reference” one. Could you explain?
> > > >
> > > > We currently only have a document picker that we can use for
> > > > DocumentReferences. To have auto-suggestion on the "reference"
> > > > parameter, we would need to make another picker for all type of
> > > > references, not just document.
> > >
> > > Ok I understand.
> > >
> > > But I don’t think it’s a good idea to remove the deprecation on
> “document”. This is deprecated for a good reason. And if we undeprecate it
> then we’ll need to redeprecate it soon enough and it also means
> “deprecating" “reference” so that it’s moved to the advanced section. It’s
> also bad for users who’ve been told to not use the “document” parameter.
> Without mentioning that the document parameter is only available in the
> legacy module and thus without legacy modules it wouldn’t work. Raises
> plenty of problems.
> > >
> > > Other Ideas instead:
> > > 1) Use the DocumentReference picker when the Type is Document and when
> the type is changed to something else, let the user type the reference.
> > > 2) Improve the picker to support picking any type of references:
> documents, spaces, wiki, attachments, objects, properties.
> > > 3) Now in practice the include macro only supports including Documents
> so we could also simply do an override as you suggested (but on the
> “reference” field), that would be used only for the WYSIWYG (when in wiki
> mode you’d be able to enter only Document references). However if the user
> has used the macro in wiki mode, we’ll need to only display the
> DocumentReference picker if the type is Document.
> >
> > I think 3) is the simplest solution for now. We could always show the
> > document picker on the "reference" field but allow free text so that
> > other references can be manually entered.
> >
> > >
> > > <side note>
> > > I don’t think there are really good user use-cases for using something
> else than the Document type since it’ll always translate into a Document in
> the end so the user can always pick that doc instead of letting the macro
> resolve it for him.
> > > </side note>
> > >
> > > Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too
> late already since we’re releasing RC Monday!) then we could push that one
> for later for the include/display macros and instead support other and
> simpler well known macros in 11.0, from
> https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros,
> like DocumentTree macro.
> > >
> > > What I’d like is to have at least one macro that can use the picker in
> 11.0, mostly to prove that it works and to have something to report for
> users in the release notes and to show progress.
> > >
> > > Thanks
> > > -Vincent
> > >
> > > >
> > > >>
> > > >> Thanks
> > > >> -Vincent
> > > >>
> > > >>> * Introduce a new annotation to macro parameters to specify /
> override
> > > >>> its type (different from its actual java type).
> > > >>>
> > > >>> The new annotation will mostly be useful for the WYSIWYG side. In
> our
> > > >>> case we want to use the document parameter which is a String. The
> > > >>> annotation will allow us to work with a DocumentReference instead
> > > >>> which can be used to display the document picker when editing the
> > > >>> macro in WYSIWYG mode.
> > > >>>
> > > >>> To be clear, here is how we would use it:
> > > >>> @PropertyType(DocumentReference.class)
> > > >>>  public void setDocument(String document)
> > > >>>
> > > >>> WDYT?
> > > >>>
> > > >>> Thanks,
> > > >>> Adel
> > >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

vmassol
Administrator


> On 23 Jan 2019, at 11:30, Marius Dumitru Florea <[hidden email]> wrote:
>
> On Mon, Jan 21, 2019 at 4:10 PM Adel Atallah <[hidden email]> wrote:
>
>> To sum up, here is what I can do:
>>
>> On XWiki Commons:
>> * Introduce a PropertyDisplayType annotation that we can use to
>> specify with which type the macro parameter should be rendered.
>> * Add the *display type* in the property descriptor (use the existing
>> *property type* as default)
>>
>> On XWiki Rendering:
>> * Add the *display type* in the parameter descriptor (use the existing
>> *property type* as default)
>>
>> On XWiki Platform:
>> * Use the PropertyDisplayType annotation, on reference macro
>> parameters, with the EntityReference type (for the include and display
>> macro)
>>
>
>
>> * Display a document picker for the EntityReference type and make sure
>> free text is enabled (so that we can enter a reference manually)
>>
>
> It's not that simple.. If the reference parameter already has a value that
> is not a document reference then by showing the document picker that value
> will be parsed / resolved as a document reference and thus displayed as if
> a document has been selected. This can confuse the users. For instance, if
> someone writes in wiki syntax:
>
> {{include reference="[hidden email]" type="ATTACHMENT"/}}
>
> and then edit the page with the WYSIWYG editor, he will see "txt" as
> selected value when editing the macro…

Yes, I agree, this is what I was mentioning by "However if the user has used the macro in wiki mode, we’ll need to only display the DocumentReference picker if the type is Document.”.

Thanks
-Vincent

>
>>
>> On the CKeditor application:
>> * Use the *display type* instead of the *property type* when using the
>> html displayer.
>>
>> I'll create the Jira issues and make the related PRs if we agree on this.
>>
>> On Mon, Jan 21, 2019 at 9:30 AM Adel Atallah <[hidden email]>
>> wrote:
>>>
>>> On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol <[hidden email]>
>> wrote:
>>>>
>>>> Hi Adel,
>>>>
>>>>> On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]>
>> wrote:
>>>>>
>>>>> On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]>
>> wrote:
>>>>>>
>>>>>> Hi Adel,
>>>>>>
>>>>>>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]>
>> wrote:
>>>>>>>
>>>>>>> Hi devs,
>>>>>>>
>>>>>>> After discussing with Marius and Thomas, we thought it might be a
>> good
>>>>>>> idea to do the following to have a document picker in the include
>> and
>>>>>>> display maros:
>>>>>>> * Remove the deprecation of the document parameter (only for the
>> include macro).
>>>>>>
>>>>>> I don’t understand this part. Sounds counter-intuitive to me since
>> we want users to use the “reference” one. Could you explain?
>>>>>
>>>>> We currently only have a document picker that we can use for
>>>>> DocumentReferences. To have auto-suggestion on the "reference"
>>>>> parameter, we would need to make another picker for all type of
>>>>> references, not just document.
>>>>
>>>> Ok I understand.
>>>>
>>>> But I don’t think it’s a good idea to remove the deprecation on
>> “document”. This is deprecated for a good reason. And if we undeprecate it
>> then we’ll need to redeprecate it soon enough and it also means
>> “deprecating" “reference” so that it’s moved to the advanced section. It’s
>> also bad for users who’ve been told to not use the “document” parameter.
>> Without mentioning that the document parameter is only available in the
>> legacy module and thus without legacy modules it wouldn’t work. Raises
>> plenty of problems.
>>>>
>>>> Other Ideas instead:
>>>> 1) Use the DocumentReference picker when the Type is Document and when
>> the type is changed to something else, let the user type the reference.
>>>> 2) Improve the picker to support picking any type of references:
>> documents, spaces, wiki, attachments, objects, properties.
>>>> 3) Now in practice the include macro only supports including Documents
>> so we could also simply do an override as you suggested (but on the
>> “reference” field), that would be used only for the WYSIWYG (when in wiki
>> mode you’d be able to enter only Document references). However if the user
>> has used the macro in wiki mode, we’ll need to only display the
>> DocumentReference picker if the type is Document.
>>>
>>> I think 3) is the simplest solution for now. We could always show the
>>> document picker on the "reference" field but allow free text so that
>>> other references can be manually entered.
>>>
>>>>
>>>> <side note>
>>>> I don’t think there are really good user use-cases for using something
>> else than the Document type since it’ll always translate into a Document in
>> the end so the user can always pick that doc instead of letting the macro
>> resolve it for him.
>>>> </side note>
>>>>
>>>> Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too
>> late already since we’re releasing RC Monday!) then we could push that one
>> for later for the include/display macros and instead support other and
>> simpler well known macros in 11.0, from
>> https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros,
>> like DocumentTree macro.
>>>>
>>>> What I’d like is to have at least one macro that can use the picker in
>> 11.0, mostly to prove that it works and to have something to report for
>> users in the release notes and to show progress.
>>>>
>>>> Thanks
>>>> -Vincent
>>>>
>>>>>
>>>>>>
>>>>>> Thanks
>>>>>> -Vincent
>>>>>>
>>>>>>> * Introduce a new annotation to macro parameters to specify /
>> override
>>>>>>> its type (different from its actual java type).
>>>>>>>
>>>>>>> The new annotation will mostly be useful for the WYSIWYG side. In
>> our
>>>>>>> case we want to use the document parameter which is a String. The
>>>>>>> annotation will allow us to work with a DocumentReference instead
>>>>>>> which can be used to display the document picker when editing the
>>>>>>> macro in WYSIWYG mode.
>>>>>>>
>>>>>>> To be clear, here is how we would use it:
>>>>>>> @PropertyType(DocumentReference.class)
>>>>>>> public void setDocument(String document)
>>>>>>>
>>>>>>> WDYT?
>>>>>>>
>>>>>>> Thanks,
>>>>>>> Adel

Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Marius Dumitru Florea
On Wed, Jan 23, 2019 at 12:36 PM Vincent Massol <[hidden email]> wrote:

>
>
> > On 23 Jan 2019, at 11:30, Marius Dumitru Florea <
> [hidden email]> wrote:
> >
> > On Mon, Jan 21, 2019 at 4:10 PM Adel Atallah <[hidden email]>
> wrote:
> >
> >> To sum up, here is what I can do:
> >>
> >> On XWiki Commons:
> >> * Introduce a PropertyDisplayType annotation that we can use to
> >> specify with which type the macro parameter should be rendered.
> >> * Add the *display type* in the property descriptor (use the existing
> >> *property type* as default)
> >>
> >> On XWiki Rendering:
> >> * Add the *display type* in the parameter descriptor (use the existing
> >> *property type* as default)
> >>
> >> On XWiki Platform:
> >> * Use the PropertyDisplayType annotation, on reference macro
> >> parameters, with the EntityReference type (for the include and display
> >> macro)
> >>
> >
> >
> >> * Display a document picker for the EntityReference type and make sure
> >> free text is enabled (so that we can enter a reference manually)
> >>
> >
> > It's not that simple.. If the reference parameter already has a value
> that
> > is not a document reference then by showing the document picker that
> value
> > will be parsed / resolved as a document reference and thus displayed as
> if
> > a document has been selected. This can confuse the users. For instance,
> if
> > someone writes in wiki syntax:
> >
> > {{include reference="[hidden email]" type="ATTACHMENT"/}}
> >
> > and then edit the page with the WYSIWYG editor, he will see "txt" as
> > selected value when editing the macro…
>
>

> Yes, I agree, this is what I was mentioning by "However if the user has
> used the macro in wiki mode, we’ll need to only display the
> DocumentReference picker if the type is Document.”.
>

The issue is that this part "*display the DocumentReference picker if the
type is Document*" is not easy to express through the macro descriptor.
That is: display the picker P for parameter X if another parameter Y has
the value V. Plus, the picker would need to change if the value of the
other parameter changes. The WYSIWYG editor doesn't have custom code for a
specific macro. It just looks at the macro descriptor and does whatever is
specified there, for any macro. ATM it sees two separate parameters,
reference and type, each with its own "picker" (a plain text input field
for now). It doesn't know it needs to reload the picker for reference when
the value of type changes. A possible solution is to be able to associate a
picker to a parameter group (reference+type).

Thanks,
Marius


>
> Thanks
> -Vincent
>
> >
> >>
> >> On the CKeditor application:
> >> * Use the *display type* instead of the *property type* when using the
> >> html displayer.
> >>
> >> I'll create the Jira issues and make the related PRs if we agree on
> this.
> >>
> >> On Mon, Jan 21, 2019 at 9:30 AM Adel Atallah <[hidden email]>
> >> wrote:
> >>>
> >>> On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol <[hidden email]>
> >> wrote:
> >>>>
> >>>> Hi Adel,
> >>>>
> >>>>> On 18 Jan 2019, at 11:59, Adel Atallah <[hidden email]>
> >> wrote:
> >>>>>
> >>>>> On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol <[hidden email]>
> >> wrote:
> >>>>>>
> >>>>>> Hi Adel,
> >>>>>>
> >>>>>>> On 17 Jan 2019, at 11:05, Adel Atallah <[hidden email]>
> >> wrote:
> >>>>>>>
> >>>>>>> Hi devs,
> >>>>>>>
> >>>>>>> After discussing with Marius and Thomas, we thought it might be a
> >> good
> >>>>>>> idea to do the following to have a document picker in the include
> >> and
> >>>>>>> display maros:
> >>>>>>> * Remove the deprecation of the document parameter (only for the
> >> include macro).
> >>>>>>
> >>>>>> I don’t understand this part. Sounds counter-intuitive to me since
> >> we want users to use the “reference” one. Could you explain?
> >>>>>
> >>>>> We currently only have a document picker that we can use for
> >>>>> DocumentReferences. To have auto-suggestion on the "reference"
> >>>>> parameter, we would need to make another picker for all type of
> >>>>> references, not just document.
> >>>>
> >>>> Ok I understand.
> >>>>
> >>>> But I don’t think it’s a good idea to remove the deprecation on
> >> “document”. This is deprecated for a good reason. And if we undeprecate
> it
> >> then we’ll need to redeprecate it soon enough and it also means
> >> “deprecating" “reference” so that it’s moved to the advanced section.
> It’s
> >> also bad for users who’ve been told to not use the “document” parameter.
> >> Without mentioning that the document parameter is only available in the
> >> legacy module and thus without legacy modules it wouldn’t work. Raises
> >> plenty of problems.
> >>>>
> >>>> Other Ideas instead:
> >>>> 1) Use the DocumentReference picker when the Type is Document and when
> >> the type is changed to something else, let the user type the reference.
> >>>> 2) Improve the picker to support picking any type of references:
> >> documents, spaces, wiki, attachments, objects, properties.
> >>>> 3) Now in practice the include macro only supports including Documents
> >> so we could also simply do an override as you suggested (but on the
> >> “reference” field), that would be used only for the WYSIWYG (when in
> wiki
> >> mode you’d be able to enter only Document references). However if the
> user
> >> has used the macro in wiki mode, we’ll need to only display the
> >> DocumentReference picker if the type is Document.
> >>>
> >>> I think 3) is the simplest solution for now. We could always show the
> >>> document picker on the "reference" field but allow free text so that
> >>> other references can be manually entered.
> >>>
> >>>>
> >>>> <side note>
> >>>> I don’t think there are really good user use-cases for using something
> >> else than the Document type since it’ll always translate into a
> Document in
> >> the end so the user can always pick that doc instead of letting the
> macro
> >> resolve it for him.
> >>>> </side note>
> >>>>
> >>>> Note: If 1) or 2) or 3) are too hard for 11.0 (and it seems we’re too
> >> late already since we’re releasing RC Monday!) then we could push that
> one
> >> for later for the include/display macros and instead support other and
> >> simpler well known macros in 11.0, from
> >>
> https://design.xwiki.org/xwiki/bin/view/Proposal/AutocompleteOnReference#HWYIWYGMacros
> ,
> >> like DocumentTree macro.
> >>>>
> >>>> What I’d like is to have at least one macro that can use the picker in
> >> 11.0, mostly to prove that it works and to have something to report for
> >> users in the release notes and to show progress.
> >>>>
> >>>> Thanks
> >>>> -Vincent
> >>>>
> >>>>>
> >>>>>>
> >>>>>> Thanks
> >>>>>> -Vincent
> >>>>>>
> >>>>>>> * Introduce a new annotation to macro parameters to specify /
> >> override
> >>>>>>> its type (different from its actual java type).
> >>>>>>>
> >>>>>>> The new annotation will mostly be useful for the WYSIWYG side. In
> >> our
> >>>>>>> case we want to use the document parameter which is a String. The
> >>>>>>> annotation will allow us to work with a DocumentReference instead
> >>>>>>> which can be used to display the document picker when editing the
> >>>>>>> macro in WYSIWYG mode.
> >>>>>>>
> >>>>>>> To be clear, here is how we would use it:
> >>>>>>> @PropertyType(DocumentReference.class)
> >>>>>>> public void setDocument(String document)
> >>>>>>>
> >>>>>>> WDYT?
> >>>>>>>
> >>>>>>> Thanks,
> >>>>>>> Adel
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Adel Atallah
In reply to this post by Marius Dumitru Florea
On Wed, Jan 23, 2019 at 11:31 AM Marius Dumitru Florea
<[hidden email]> wrote:

> It's not that simple.. If the reference parameter already has a value that
> is not a document reference then by showing the document picker that value
> will be parsed / resolved as a document reference and thus displayed as if
> a document has been selected. This can confuse the users. For instance, if
> someone writes in wiki syntax:
>
> {{include reference="[hidden email]" type="ATTACHMENT"/}}
>
> and then edit the page with the WYSIWYG editor, he will see "txt" as
> selected value when editing the macro...


I just tried with `{{display reference="[hidden email]"
type="ATTACHMENT"/}}` and the element was displayed as is in the
WYSIWYG editor.
I think this is because the picker uses the search REST API
(/wikis/{wikiName}/search) which doesn't seems to use a reference
resolver.
So one issue is that you won't have autocompletion if you use a prefix
on a document reference.

Also one think I don't currently like is that you cannot edit the
selected item in the picker, which means, for instance, that if you
made a typo in "[hidden email]" then you'll have to
delete this element and rewrite the whole reference.

I'll make a PR and show you some screenshots or videos so you can see
what we could currently have.
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Document picker in include and display macros

Marius Dumitru Florea
On Wed, Jan 23, 2019 at 3:08 PM Adel Atallah <[hidden email]> wrote:

> On Wed, Jan 23, 2019 at 11:31 AM Marius Dumitru Florea
> <[hidden email]> wrote:
> > It's not that simple.. If the reference parameter already has a value
> that
> > is not a document reference then by showing the document picker that
> value
> > will be parsed / resolved as a document reference and thus displayed as
> if
> > a document has been selected. This can confuse the users. For instance,
> if
> > someone writes in wiki syntax:
> >
> > {{include reference="[hidden email]" type="ATTACHMENT"/}}
> >
> > and then edit the page with the WYSIWYG editor, he will see "txt" as
> > selected value when editing the macro...
>
>
> I just tried with `{{display reference="[hidden email]"
> type="ATTACHMENT"/}}` and the element was displayed as is in the
> WYSIWYG editor.
> I think this is because the picker uses the search REST API
> (/wikis/{wikiName}/search) which doesn't seems to use a reference
> resolver.
> So one issue is that you won't have autocompletion if you use a prefix
> on a document reference.
>
>

> Also one think I don't currently like is that you cannot edit the
> selected item in the picker, which means, for instance, that if you
> made a typo in "[hidden email]" then you'll have to
> delete this element and rewrite the whole reference.
>

I think you can copy the text, delete the option and paste the copied text.
It's not a big issue for me.


>
> I'll make a PR and show you some screenshots or videos so you can see
> what we could currently have.
>