Page Naming Strategy and wanted links

Hi devs (and everyone),

This is a discussion about what design choice to make to try to solve Loading....

In short, when there’s a wanted link that doesn’t follow the page naming strategy, clicking on the ? link to create the page fails (rightly so) since the reference doesn’t validate.

Let me list a few options I can think of, to kickstart the discussion about how we should handle this. Some of the options below are orthogonal (and thus not mutually exclusive).

Option 1: Just improve the message

We consider that the current behavior is valid, because:

  • The Admin has configured the wiki to not allow some page names
  • Someone is trying to create a link with a forbidden name through a wanted link
  • Thus, when someone clicks the ? link to create the wanted page, a dialog box opens and explains that the target reference doesn’t validate and that the page needs to be edited to modify the link reference to match the strategy in place.


  • We should improve the error message to indicate the rules that page names must conform with since right now, a user might not know them and would need to know them in order to change the wanted link reference.
  • If the user creating the wanted page doesn’t have edit rights on the source page, he/she will need to ask someone with edit rights to perform the reference change.

Option 2: Refactoring operation

Add an optional refactoring operation when the validation fails (whether it’s called in the context of a wanted link or not, both use cases exist). The refactoring operation would modify the link reference in the source page.

There are 3 cons with this strategy IMO:

  • The current user needs to have edit rights on the source page
  • It’s costly
  • If the page naming strategy is for example a UUID strategy (references are replaced by a UUID), then the user creating the original link reference would need to generate UUIDs to create valid references to avoid future refactoring operations and that’s not great, or put some random reference since it’ll get replaced (which is also not great)

Option 3: Display invalid wanted links differently

The idea is to modify the rendering of wanted links when they point to a reference that doesn’t pass validation, i.e. instead of displaying a question mark link (?), display the broken link differently, with some red ? for example, that is not clickable and with a text explaining why it’s not clickable.

One cons is that it could make page rendering slower, although I don’t think that would be the case if the page strategy implementation is fast. There could also be caches to work around the performance issue if any.

Option 4: Modify the WYSIWYG link dialog

The idea is to modify the WYSIWYG link dialog so that any link reference entered goes through the page name strategy to normalize it (as we do when creating a new page in the Create Page dialog).

Note that there’s one con but we could maybe live with it:

  • We wouldn’t be able to create 2 wanted links pointing to the same reference (the issue is only when using page naming strategy that has randomness in it, like the UUID one).

Option 5: Add the concept of validation to the wiki editor

I’m listing it to be complete but I don’t feel it’s a good option. The idea is that upon clicking “Save” in the wiki editor, validate the content so that if there’s some link reference not matching the page naming strategy, the page is not saved.


  • Hard to parse since generating the XDOM would mean executing macros to be fully correct
  • Not great to fail to save a page when in the wiki editor, as user would expect to be able to enter anything they want in text mode.

An alternative to this one is the wiki editor would recognize when typing a link reference and perform validation but that’s too hard to implement IMO since it would need to work with any markup.

My opinion

+1 for option 1 (for the improved message part)

-1 for option 2
+1 for option 3 (IMO we need it to solve the issue with the wiki editor use case - that a user can enter any link reference they want using the wiki editor)
+1 for option 4
-1 for option 5
And we don’t support the ability to create 2 wanted links pointing to the same reference when using a page naming strategy with randomness in it.

IMO the best would be to implement the following options: 3, 4
The second best is to implement 1 and 3.

WDYT? Do you see any other option that I have missed?


My opinion here: keep it simple. But error message should be very explicit about the rules and tell them.

+1 for option 1

+1 for 1. Making sure the user knows how to correct the reference looks like the best solution to me.

It’s an interesting situation to point out, but I doubt it happens often. It would already happen in the current state of things, so IMO if we don’t have user reports of this behavior already, there’s no need to address it.

-1 for 2. In addition to what you already pointed out, it might be difficult for users to point out when / why / what was done in this refactoring and I think it’d probably end up being seen and acting like a bug.

+0 for option 3, it looks like it could help along other options, but I don’t think it’s enough to address the issue at hand by itself. Moreover I think it’d be better to give it the warning color (yellow) instead of an error color (red).

-0 for option 4. It’s easier to understand when and why the refactoring happens than option 2. We should however consider what we would do with previously created invalid wanted links, and wanted links added via other editors: migrate them, leave them as is,…

-1 for 5, not efficient enough and will probably be difficult to maintain. The only pro is that this could be made to validate other elements, but setting validation on the whole content just for wanted links looks like overkill.

IMO option 1 is a must if we leave any situation where a user could actually see this message (that would happen even with options 3 and 4 picked).
I’m not really convinced on the usefulness of option 3, but given that it should be easy to implement and maintain I agree that it’s a pretty good option to complement any other.

Lucas C.

  1. Whatever the long term solution, it looks like we should do 1 anyway as it’s always possible for someone to end up with this /created/ URL (even if XWiki Standard does not produce them anymore it could still be produced by some extension for example)

  2. -1

  3. to me, this is pretty much the same general logic as 1 and could be grouped under the same “solution” : don’t really “fix” anything and just inform about the problem

  4. +1, helping the user avoid mistake is basically the point of the WYSIWYG, and we do this kind of things in various other case in the WYSIWYG. Sure, it does not help for the wiki editor, but it’s not exclusive, it’s just a good thing to have this helper in the WYSIWYG (maybe still allow creating invalid link for advanced users for example just in case) whatever else we do.

  5. -1 to block the save. That being said, a variation of this which could be interesting would be to have a live validation of the content on the client side (which in practice would probably send the content to a validation service running on the server side since it’s a lot easier to do). You would get various warnings/errors (and maybe information if we think it’s interesting) displayed somewhere (between the content and the save button for example) about this content, so you know there are some problems, but you can still save anyway if you really want to.

To devs who answered only option 1 as a good solution (e.g. @CharpentierLucas or @Simpel), please make sure you have considered the use case of the UUID page name strategy since I don’t see how you can make it work just with option 1.

I don’t understand your -0 here as it seems good that the WYSIWYG editor should try to prevent users from creating invalid references. Could you explain why -0? Again this option is not meant to replace other options. It’s not enough for sure (hence why I proposed options 1, 3, 4) but not doing it seems like a bug to me.

No problem re the color. I mostly meant something visible to show something broken. Yellow seems better indeed.

Yeah, this is what I meant with:


Everyone ok with this too?

Actually with option 3 you wouldn’t see the create dialog for wanted links since you wouldn’t be able to click on the ? symbol. But anyway we need option 1 for other use cases :wink:

Sure, but It’s much easier to implement when you just ask the server to validate the content.

Isn’t this page name strategy behavior to generate a new UUID every time you try to create a page (even a page name which looks like a UUID already) ? If that’s the case, you cannot really pre-validate anything, as the link will always be different from the UUID that will eventually be generated in the /action/.

hmm good point, I hadn’t considered that it could be implemented like this. I had assumed that if the link was already a UUID it would be used but you’re probably right that it’s going to be regenerated.

EDIT: Actually I think it could work, see api-random-page-names/src/main/java/org/xwiki/contrib/validation/uuidpages/ at master · xwiki-contrib/api-random-page-names · GitHub (the page naming strategy has 2 apis: transform & validate). So validate() should work if you provide a UUID-matching pattern.

It’s still an inconsistency between WYSIWYG and other edition modes. IMO we should aim at behaviors aligning for each editors when possible. Inconsistencies like this will make edition more difficult of a task overall for users (given they know about the different edit modes). Ofc we can’t always be consistent but here I think other options would solve the issue so I’d rather go with the other options and not follow n.4 . Moreover it creates an issue with the UUID naming strategy (double references for the same name) and it looks like a complex addition that would take work to maintain. That’s why I initially put -0.

In regards to that, it seems like the option 4 is still needed though. Do we have documentation on what kind of UUID naming strategy we support? I couldn’t find it myself :confused: <EDIT> Just saw the links you posted in Page Naming Strategy and wanted links - #11 by vmassol , checking them out </EDIT> I understand the validation of such a naming strategy, but from what I understand there are a lot of ways we could implement the transform strategy, and some of them should be simple enough that users could figure out a correct solution by themselves with the indication from options 1. and 3. .
I retract my -0 from earlier, my opinion was based on insufficient understanding.

Oh yup, I forgot about this part of option 3 :+1:

Yes, should be fine. Also I just tested it in an instance where it’s installed and indeed it seems fine when the link already looks like a UUID.

I think the main solution is Option 4: We should properly support creating links to not-yet existing pages in the WYSIWYG editor. From the (original) wiki philosophy, this should be the main way to create pages. My point here being to offer a nice way to create a link to a not-yet-existing page that offers selecting a parent from a tree and a title from which we derive a name using the naming strategy. So +1 for 4.

The wiki editor is for advanced users only and is lacking many features like no quick actions, lists aren’t continued when you press enter, no way to select an existing page or image to link to, etc. - all of this could also be available in the wiki editor. So I don’t see why this one change now needs to be in the wiki editor, too. So -1 to 5.

Also, +1 for 1, as this is important and simple. What I think could also be a nice improvement is to allow creating a different page with a button/link in this case. This won’t create the wanted page, but would offer a way out in case the user really wants to create a page and wants to fix the link later.

Instead of option 3, I would favor option 2 as it’s just nicer from a user’s point of view. Regarding edit rights, I don’t think we require edit right for refactoring operations, e.g., when moving a page or an attachment. I don’t think we really need option 2 if we implement option 4, it would just be a nice bonus.

It would be a big bug to me if we were not checking rights when using the refactoring API. I think it’s xwiki-platform/xwiki-platform-core/xwiki-platform-refactoring/xwiki-platform-refactoring-api/src/main/java/org/xwiki/refactoring/internal/listener/ at 47ba5bd5d9c73f5ad74b9b929b24fc30c63276ad · xwiki/xwiki-platform · GitHub which is then tested at xwiki-platform/xwiki-platform-core/xwiki-platform-refactoring/xwiki-platform-refactoring-api/src/main/java/org/xwiki/refactoring/internal/listener/ at 47ba5bd5d9c73f5ad74b9b929b24fc30c63276ad · xwiki/xwiki-platform · GitHub

Option 2 is complex to implement (and it cannot be perfect too), and thus we should avoid it IMO. Option 4 is better in that regards (as you say).

Even with option 4, I still think that we need option 3 (for the wiki editor use case).


Okay, that’s surprising to me, because it means that when somebody with limited rights renames a page, a lot of links will be broken even though the user assumed that all links would be fixed automatically.

I’m not against option 3, I’m just saying that from a usability point of view, option 2 would be nicer.

We need to clarify this indeed and find out what happens. I’ve checked and couldn’t see any mention of rights there.

Hi, thanks for bringing this up there.

+1 for 1, 3 and 4.
-0 for 2, I’m still not entirely convinced it couldn’t be an option if we reuse authors for transforming the links. Now it’s still not enough for UUID UC with several links in same page.

-0 also for 5: maybe we could have some middle way mechanism, e.g. by default it’s always saved when calling the URL to save, but the UI would provide some parameter to perform extra checks in which case it could ask a confirmation to the user if there’s some links badly written. Now I don’t think it’s a priority to go there: 1/3/4 are more important IMO.

Note that there’s discussion to be had about the precise mechanism for option 4.

Imagine you’re a user and select some text and click “add link”. The link dialog opens.

There are now 2 cases:

  • The user enters some link. In this case, the validation happens on the spot and the page naming strategy gets applied, potentially transforming the reference. We’ll need some message explaining that the strategy has been applied.
  • The user doesn’t enter anything. Note that this is valid in XWiki and means a link to the same page. The validation (and transformation) happens upon pressing Insert link.

We need to check what the UUID page naming strategy does when an empty reference is passed, ie whether it converts it to a UUID or if it’s kept, to point to the current page. If the former happens, it means that with the UUID page naming strategy as it is, you cannot link to the same page. If the later happens, it means we need some way to trigger the transformation (for example by having the user enters some dummy link, or by having an explicit option in the Link Dialog to link to the current page, or …).

I think what we need is a feature in the document picker that allows selecting a reference to a new document using the same UI as the create document screen (with title + tree for simple users and optional direct text inputs for advanced users). Similar to how the [ syntax in the document offers to upload a new attachment it could also offer to create a new page (I understand that these are different UIs, I’m referring to the general idea of having an item “Upload Attachment” or “Create Page” in a UI where you can select a link target). This could be an option for the standard document picker. Now I think the link dialog doesn’t use a standard document picker, but maybe this would be an opportunity to migrate it to a more standard picker?