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

On 23 Jan 2019, at 11:30, Marius Dumitru Florea <mariusdumitru.florea(a)xwiki.com> wrote: On Mon, Jan 21, 2019 at 4:10 PM Adel Atallah <adel.atallah(a)xwiki.com> 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="Path.To.Page(a)file.txt" 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 &lt;adel.atallah(a)xwiki.com&gt; > wrote: >> >> On Sat, Jan 19, 2019 at 11:33 AM Vincent Massol &lt;vincent(a)massol.net&gt; > wrote: >>> >>> Hi Adel, >>> >>>> On 18 Jan 2019, at 11:59, Adel Atallah &lt;adel.atallah(a)xwiki.com&gt; > wrote: >>>> >>>> On Fri, Jan 18, 2019 at 11:27 AM Vincent Massol &lt;vincent(a)massol.net&gt; > wrote: >>>>> >>>>> Hi Adel, >>>>> >>>>>> On 17 Jan 2019, at 11:05, Adel Atallah &lt;adel.atallah(a)xwiki.com&gt; > 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#HW…, > 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