Proposal for UX improvements to the link dialog

[tkrieck]

Hey everyone, in an effort to standardize various aspects of XWiki, I would like to propose some improvements to the link dialog used in the CK editor.

Some problems with the current implementation:

• Non-standard UI elements.

  • Specially visible on button styles and rounded corners
  • This might be a CK limitation, but if possible it would be good to standardize on Theme variables
  • Example:
    

• Some important controls are hidden by default

  • The selection of the link type is on a drop-down
  • Sometimes the icon type is clickable, sometimes it is not.
  • Example:
    
    

• The flow for uploading a new file makes the user go backwards in the natural flow of reading.

To remedy some of these problems, I would like to propose the following layout to the dialog:

Below you can see the proposed layout applied to each type of link:

And here two example user flows with the changes.

Flow for selecting / creating page

It is important to note that here the user could create new pages. These pages would be created as a child of the current one, of the type configured as default (usually a blank page) and its title is informed on the “Display Text” field:

Flow for selecting / uploading file

Remarks:

1. It would be nice to have an alternative and more modern way of uploading files, via drag and drop.
2. Uploading via click or touch interaction would still be possible.
3. Uploading itself would be automatic on link save

The other two types of links I didn’t create a flow as they are very simple.

Now I would like to know from you, what do you think of this proposal, if it is technically feasible, any improvements that could be made?

Thank you all for reading

[amilica]

Hello Thiago! Thanks a lot for your proposal!

Pros of current version

What I (surprisingly) liked about the current UI of the link dialog is how compact it is. Once you use it 1-3 times you get used to the fact that you have to click on an arrow to select different types of data.

Cons of current version

The things that I don’t like about the current one are:

1. the arrow can seem like it doesn’t let the user choose through the types, but through something else
2. there is no search icon and this makes the input feel not typeable in a way (for a long time I never typed in that input, I’ve only used the tree)
3. pasting a link to a wiki page doesn’t get transformed into an internal page reference
4. there are no types for images, videos that could enable the user to find info easier
5. nothing informs the user that they can paste the page reference in the input field

Improving the UI

I feel we should still aim to have it pretty compact, letting us use it in other places where it should be, but it isn’t.

An example of a place like this is macro configurations.

Many times in these configurations, referencing one or multiple pages/attachments is needed, but ATM this can only be done by knowing the address/reference of that page/attachment. The UI of the link dialog could be repurposed in these configurations.

This is how I’d see the revamp. Ignore the fake tree icon, it should be something else, but I couldn’t find it (right now I’m using the branch icon):

I agree that this UI is less transparent to the user than what your proposed, but I also think that once the user would do it a few times it would seem very straight forward. This UI is also easier to integrate visually in a possible revamp of macro configurations:

What do you think about this? It is possible I’m mistaken or maybe biased because of how familiar the UI has become to me.

[MichaelHamann]

Hi, first thank you very much for your proposals!

First, let me state what I don’t like about the current dialog, and then I’ll try to explain how I like that your proposals improve that (apart from improving consistency):

1. Most of the time when I open this dialog I want to link to a URL (as links to other pages are usually handled through the quick actions). It takes me two clicks and I need to carefully target this tiny button to change the link type to a URL.
2. It took me more than two years to find out that you can click on that “page” icon to open a page tree. I always thought that was just to show me the currently selected link type.
3. It is quite hard to create a link to a new page using this dialog as you cannot select a parent page and a title like in the new page dialog.

For point 1, I really like the tabs @tkrieck is proposing. They are immediately visible and require just a single click on a click target that is comfortable to reach. For the macro dialog use case, I think in most cases you only have a single type of reference and thus the tabs won’t be relevant.

For point 2, this is the one point that’s not great yet in the proposal by @tkrieck: it’s totally not obvious to me that the search icon would open the tree. I like the idea of @amilica to introduce a dedicated icon for that. This icon could also be next to the input as it is not really connected to that input.

For point 3, @tkrieck has a “Create page” button, but it is not clear where this page “Procedures” in your screenshot would be created. Could we open a dialog similar to the left part of the “create page” dialog when selecting that option? Or just include these controls in the link dialog after clicking a “Create page” button similar to the “Upload” button for files?

A comment regarding the attachment use case, it would be great if the following two features could be considered:

1. copy & paste files (into the input?)
2. rename the file before (or after) the upload. This is particularly important for drag & drop and copy & paste as there the user frequently doesn’t control the filename.

I think the idea of integrating the possibility to transform a full URL into a page reference is also nice, it still happens from time to time for me that I first copy a URL and then notice, ah, no, I need to copy the reference (in particular as in other cases like this forum I indeed need the URL). But I guess that could also simply be integrated into the search form, that when you paste a full URL it automatically suggests the page (and maybe even parses the anchor?).

[tkrieck]

@amilica

I feel we should still aim to have it pretty compact, letting us use it in other places where it should be, but it isn’t.

I like that, but what if we could make this more automatic, based on what the user types in the box. And make the “type” the first button on the input group. For example:

Similar to what we have now with quick search. Now, I don’t know the technical feasibility of this. But if possible, it would be more reactive to what the user actually wants instead of relying on the user selecting everything by hand.

@MichaelHamann

Could we open a dialog similar to the left part of the “create page” dialog when selecting that option?

We could, but it would be a dialog on top of another dialog, and one that takes the user away from its primary objective (creating a link). That’s why in my mockups I mention that the page should be created on save automatically, as a child of the current page. Maybe I should add a brief explanation to the interface on this.

[toothspaces]

Hi,
first thank you very much for your proposals!
Like @MichaelHamann …

I toadly agree with all that have been proposed and discussed.

Thank you again.

What I don’t agree on : the compact thing.
What the advantage of compact ?
If it make you click each time on two tiny things, to reach what can be reached with one click in a large zone (tab header…) ?

IMHO, the link dialog is made for people that know very well the tool, and work hard to write a page.
Your proposal is… refreshing.

@MichaelHamann

• It took me more than two years to find out that you can click on that “page” icon to open a page tree. I always thought that was just to show me the currently selected link type.
• It is quite hard to create a link to a new page using this dialog as you cannot select a parent page and a title like in the new page dialog.

Yes… same experience for me.
And a feeling of WTF each time I have to use it…

---

What most important, IMHO, is not only the interface, but the features.

=> I wish a link box that is modular and customizable, with some hooks that allow to plug in some usual features.
(for Christmas ? … seems time to write the letter… )

Something that would need some programming and technical customization, but with some plugs that make things more easy. (modular architecture).
“plugs” : I mean “des points d’entrées”. Some hook mechanism… and architecture that allow to provide another piece of code to make the job, for the custom feature.

Kind of feature :
The selection and typing of the link : to be able to change the plugin, and put our one.
With special feature, custom : provide some proposals, filter on some custom criteria, etc…

The addition of a tab,… that could be :
“link to pages about security” (on a dedicated other web site of the company),
or “link to FAQ items”, etc…
For custom needs.

Very important : being able to build the “title” attribute, or the “target” attribute, with some proposal that is built by programming. To provide a proposal that is “home made built”.
Example : the title is built with : the space name + the title of the page + a short summary of the first line of text. Or whatever custom way to build it.

Very important : being able to build the link with some additional feature, prebuilt for the user. The idea : make some links like the one you can have in Wikipedia : with the mouse over show a nice tooltip, with sumary of the article linked to.
So powerfull, for reading the content of a page… and have a peep on the linked page without going to this page …
Being able to provide the user with some tool to build these kind of links.
A tool that provides “the most easy way to build them”.

For pages of the wiki, as well as other external source of information (other website).
Usual use case : a company provide to the users of the XWiki platform and tool, … some dedicated link dialog, that aim directly and easily to another platform of the company (security procedures, internal product description tools, etc…)

By the way, if some custom compact link dialog is available, then the platform admin, or may be even each user, could choose for the compact link dialog, or regular link dialog.

All this complexity of the additionnal feature is left to the customization and programming, on the customer side…
XWiki provide the modular architecture, and others do their customization.
Providing some nice link dialog features, as extension, is part of this global schema.

---

For the Connexion and Authentification feature of XWiki, there is some modular and pluggable feature, to offer the customization of how to make the identification and authentification of a user.
With LDAP, with SSO with Google, etc…
Both interface and process are customizable.

The same for the link dialog ?
Open the door to add some custom feature ?
with full programming (Velocity, Groovy, Java, Javascript,… ) use, … if needed.

---

XWiki is about organizing the information.
Making a link is a master, center feature of the platform/tools.
(2 years “to find out that you can click on that “page” icon to” ?
By one experimented user. … seems there something to do, there…).

---

And… documentation of all this customization ability.
The only thing I could find is :
Add a new Link Type

And this extension documentation :
CKEditor Integration (XWiki.org)
extensions.xwiki.org › xwiki › bin › view › Extension

The way to customize the link dialog, now, is to rewrite the extension and make our own ?

Hope it helps…

[Wardenburg]

Hey everyone,

great suggestions @tkrieck , I agree that users struggle with links, whilst it is a crucial part of a wiki (internet? ) environment!

Some suggestions/notes from my side;

• The link options are hidden for most users
  IMO The anchor functionality is very powerful when linking to xwiki pages but it is hidden and it is relatively advanced to have users copy paste the correct Anchor string (i.e. HCasesensitiveheader). Perhaps something can be done to have users easily / more readily select from the table of content items from the selected page when creating a page type link?

• The target window of the link is something that can be defaulted now (which will help most users) but it’s probably worth taking this part of the UI in consideration when creating the new theme. Personally I could live with ‘same window, new window’ being with more readily available radio buttons/checkmarks and the rest of the options staying in the dropdown - but perhaps that’s more about my preference/use case. (Forgive the dutch mumbo jumbo of the image )

• Finally theres the Mailing tab, it’s worth noting there are other types of links that can be linked to (i.e. think link types as SIP: for skype/teams and/r callto: urls for linking to phone numbers), perhaps a way can be found to support these types of links from the interface

[tkrieck]

Hi everyone,

I’d like to close this proposal soon, so I’ll compile here a list of the points that were discussed:

#1 Non-standard UI elements

This seems to be generally accepted; most concerns are about consistency anyway.

#2 Page tree icon

Most of you agree that the current icon is not very visible, but the proposed “search” icon is also not ideal. I’m putting here two options that could be used, both from FontAwesome, but are not part of the icon theme, so they should be added to it first.

Option 1:

Option 2:

Both could fallback to this Silk icon if we still want to support it somehow.

#3 Use tabs instead of an icon

Opinions diverged a bit on this point. Proposed solutions include:

• Using tabs (original proposal)
• Continuing to use icons
• Using an icon in front of the field, with additional logic that observes what the user types and selects a link type accordingly

#4 Extra feature – provide a link target option

It would be useful for users to be able to define that a link should open in a new page (unchecked by default).

#5 Extra feature – get anchor-type links inside pages

While it is already possible to point to specific anchors inside a page, discovering them can be tricky. It would be a significant improvement if these links could be exposed beforehand by the link dialog.

I’m not sure how feasible this is, though.

#6 Extra features for the overall link functionality (not just the dialog)

• Rich tooltips
• Programmatic definition of attributes
• Additional customized link types
• Extension/customization of the link creation logic

While I agree that most of these would be very helpful, I’m concerned they fall outside the scope of this proposal. For now, I suggest leaving them out, while adding a note in the proposal itself to address them in separate, dedicated proposals.

I’ll keep this open until January 30th in case more people want to participate and share their opinions.

Thank you all.

[vmassol]

Hello, I’d just like to add that I think that the reason it’s currently done with a compact picker is because it’s a standard/reusable picker that can be used anywhere (for example in the object editor, or in a macro dialog UI), and that it’s done to represent a link reference (following the specification defined at https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/?syntax=2.1&section=Links).

That doesn’t mean we couldn’t have a custom UI for the Insert Link dialog of the WYSIWYG editor. But if we were to implement @tkrieck 's proposal (i.e. point #3) it wouldn’t solve the generic case (for the object editor or the macro editor).

Also, regarding point #1, the reason AFAIK (is that we’ve been reusing the default CK4 dialog box in some case and sometimes, we’ve implemented our own dialog or added to an existing dialog). To improve consistency we would need to redevelop the default CK4 dialog box we’re using. OTOH we need to prepare for the move to BlockNote so we should develop new dialogs that will be common between CK4 and BlockNote, using cristal technologies (if possible).

Would be good to have @mflorea and @mleduc 's feedback on this proposal too.

Thx!

[vmassol]

@tkrieck

#2 Page tree icon

Most of you agree that the current icon is not very visible, but the proposed “search” icon is also not ideal. I’m putting here two options that could be used, both from FontAwesome, but are not part of the icon theme, so they should be added to it first.

Option 1:

Option 2:

The first one should be in the icon theme already as it’s used when creating a new page:

[vmassol]

@tkrieck

Flow for selecting / creating page

[…]These pages would be created as a child of the current one, of the type configured as default (usually a blank page) […]

Actually you can specify a parent page (i.e. a space) when creating a new page, see:

[vmassol]

@tkrieck

#5 Extra feature – get anchor-type links inside pages

While it is already possible to point to specific anchors inside a page, discovering them can be tricky. It would be a significant improvement if these links could be exposed beforehand by the link dialog.

I’m not sure how feasible this is, though.

I agree that it would help a lot. It’s doable, just a bit more costly re performance (but not a problem) as it means parsing the target page to extract the anchors. The possibly tricky part is that the page would probably need to be rendered to HTML (computing the anchors based on the source syntax wouldn’t work since the HTML renderer automatically adds anchors for headings for ex), and thus if the page contains scripts or macros, they’d be executed (OTOH that would happen too if the user were to view the page so probably not a problem). Of course, we should do that only if the current user has permissions to view the page.

[tkrieck]

Thank you for the remarks @vmassol.

@vmassol

The first one should be in the icon theme already as it’s used when creating a new page

I think, that settles the question then, because in both applications this icon would be used for selecting pages.

@vmassol

I agree that it would help a lot. It’s doable, just a bit more costly re performance (but not a problem) as it means parsing the target page to extract the anchors.

Perhaps we would need to execute this part only after the user activates it. So, instead of doing automatically every time the linked page is selected, we would probably only show a button called “Link to Title” or “Link Anchor” and only then, after activation, we show the box for selecting anchor. WDYT?

[vmassol]

@tkrieck

So, instead of doing automatically every time the linked page is selected, we would probably only show a button called “Link to Title” or “Link Anchor” and only then, after activation, we show the box for selecting anchor. WDYT?

Yes, sounds better.

[mleduc]

@tkrieck

Flow for selecting / creating page

It is important to note that here the user could create new pages. These pages would be created as a child of the current one, of the type configured as default (usually a blank page) and its title is informed on the “Display Text” field:

Maybe for another proposal but I think we should consider making the first tab something else than “page”.
Page are easily accessible with the [ quick action and I tend to only use the advanced dialog for other cases such as inserting external links.
The main con I can think of is that easing the insertion of external links might lead to users inserting more external links for pages that could be internal references.
We could also make this use case easier by allowing the auto-wrapping of selected text with a link when pasting a url when a piece of text is selected.
We could, of course, make this configurable (and it’s probably going to be if the list of tabs is based on an extension mechanism) but we still need a good default value.
PS: I now realize it’s been mentioned my Michael earlier.

@tkrieck

#3 Use tabs instead of an icon

Also +1 for the use of tabs.

@tkrieck

#2 Page tree icon

+1 with option 1 as discussed before.

@vmassol

OTOH we need to prepare for the move to BlockNote so we should develop new dialogs that will be common between CK4 and BlockNote, using cristal technologies (if possible).

The new dialog should conceptually be backportable to CK4 with some glue code.
I don’t know if we’ll actually make the effort to define a new link plugin for the CKEditor extension.

I did not comment on extra features. I generally agree with them, but we first need to have a first version of the link dialog that is iso-functional with the current CK4 dialog.

[vmassol]

@mleduc

@tkrieck

#3 Use tabs instead of an icon

Also +1 for the use of tabs.

What about my point re the reusable picker for link references (object editor and macro dialog)?

Or do you feel that the reusable picker should have tabs? That would feel weird, wouldn’t it?

WDYT?

Thx

[mleduc]

@vmassol

What about my point re the reusable picker for link references (object editor and macro dialog)?

Or do you feel that the reusable picker should have tabs? That would feel weird, wouldn’t it?

WDYT?

From what I understand, going for a reusable UI element is hurting usability and accessibility.
I tend to prioritize usability over reuse even if I agree that increasing maintenance costs by having more custom elements is not great.
Unless @tkrieck has an idea for a design that would keep a compact (and reusable) layout without hurting usability?

[vmassol]

@mleduc

The new dialog should conceptually be backportable to CK4 with some glue code.

Ok so you mean the new dialog should be coded for Blocknote (I agree) and then we backport it for CK4.

PS: I think @tkrieck was originally thinking more about XS with CK4 than XS with Cristal. @tkrieck from now on, we need to think first about cristal technologies in XS (and also include it in proposals).

@mleduc

I don’t know if we’ll actually make the effort to define a new link plugin for the CKEditor extension.

It’s an open question indeed. Note that we won’t have the Blocknote editor replace the CK4 editor at least before end of 2026 (and possibly even Q1 of 2027). Also, even when Blocknote will become the default, we’ll most likely keep the CK4 editor for quite a while and we’ll have users configure their wiki to continue using it. So we’ll likely need to continue supporting the CK4 editor in 2027 at least. I guess it depends how hard it is to backport to CK4. If it’s easy, we should do it IMO.

[mleduc]

@vmassol

I guess it depends how hard it is to backport to CK4. If it’s easy, we should do it IMO.

+1, I would go for making it great for Blocknote while keeping the CK4 use case in mind and proceed to the backport on CK4 once we consider the new dialog mature and stable enough.
I don’t expect the glue code to be that expensive (to be validated by @mflorea).

[vmassol]

@mleduc

I tend to prioritize usability over reuse even if I agree that increasing maintenance costs by having more custom elements is not great.

Me too but we also need to offer a solution for the object editor and macro dialog (could be a separate proposal but it’s a good time to think about it). TBH I don’t know if we already have other pieces of code using that picker but I can see the need for macros for example (and thus the object editor). See below.

@mleduc

Unless @tkrieck has an idea for a design that would keep a compact (and reusable) layout without hurting usability?

@amilica posted some ideas at Proposal for UX improvements to the link dialog - #2 by amilica

@amilica

An example of a place like this is macro configurations.

Many times in these configurations, referencing one or multiple pages/attachments is needed, but ATM this can only be done by knowing the address/reference of that page/attachment. The UI of the link dialog could be repurposed in these configurations.

Note that this is already covered by the suggest picker UI components:

• for pages: https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/AutoSuggestWidget/#HSuggestPages
• for attachments: https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/AutoSuggestWidget/#HSuggestAttachments

Here the use case is a bit more narrow as it’s about selecting a link reference. I’m pretty sure we have macros that require this already. For example if a macro wants to allow to link to either an external URL or a wiki page.

Since the picker used for the CK4 link dialog is not documented at https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/AutoSuggestWidget nor at https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/Pickers/ , it’s possible it’s not been made reusable yet. Is that the case @mflorea ?

In any case we need a solution too for introducing a property of type “link”.

EDIT: Found this jira I had created: Loading...