Best practices for customizing XWiki (skins, macros, scripts, applications) - without breaking future upgrades

Help / Discuss
, , , ,
1

Hello,

I’m currently learning how to customize XWiki to adapt it to my company’s needs, and I’d like to make sure that I’m following the recommended best practices, especially so that my modifications remain easy to maintain and compatible with future upgrades.

I’ve already tried searching on the forum and in the documentation, but some aspects are still not very clear to me.

Here is what I think I understood, along with the questions I still have.

1. UI modifications (skins, .vm, themes)

I understood that when we want to modify existing elements of the XWiki interface (for example removing a button, adding a button in the header, etc.), we should modify or override the corresponding .vm files of the skin.

And for changing colors or some styles, this should be done in the theme configuration.

Is this the correct approach?

Also, is there a list or documentation of the .vm files and their roles in the XWiki interface, so it’s easier to know which ones should be modified depending on the need?

2. Creating custom components (HTML / JS / CSS)

If I want to create custom components using HTML, JavaScript and CSS, what would be the best approach in XWiki?

For example, is it better to:

  • create scripts directly inside a page

  • create a custom macro

  • or create a full extension?

3. CSS management

If I create a component (for example using a macro or a script) and define specific CSS classes:

  • is it better to include the CSS directly inside the macro/script

  • or add it to the global site theme?

For example, I would like to create something like cards (div elements containing an image, a title and an icon) that act as buttons to navigate between different wiki pages.
What would be the recommended way to implement this type of component in XWiki?

4. Modifying existing interface elements

If I want to modify some existing UI elements, for example:

  • change the style or display of the left panel

  • modify some navigation elements

What would be the recommended approach?

5. XWiki applications

I’ve also seen that it is possible to create applications in XWiki.

In which cases is it better to create an application rather than a simple script or macro?

And if I create an application, can I easily reuse its components in different pages of the wiki?

Sorry for the number of questions, but I would really like to understand the recommended best practices in the XWiki ecosystem in order to build something clean and easy to maintain in the long term.

Thank you very much for your help!

2

And for example, I’d also like to add tags to the attachments so I can access them from different places as a list. What’s the best way to do that?

3

No, it’s not the best approach for skins, since you’ll need to merge changes between the default content of these VMs and your changes, at each upgrade.

It’s better to look for UI Extension Points. You could also use JSX to inject some stuff in the UI (using insertion points that match client-side APIs as otherwise you’ll be broken in the future).

Now, changing the skin is ok if you really need the change (you should ask yourself if you really need it though) but it has a cost (the one I’ve mentioned above).

4

Hello,
Thank you for your reply, it really helped me better understand the implications of modifying the skin and the potential risks involved.

It seems that the better approach would be to rely on UI extension points instead. However, I’m still a bit confused about how to actually use and customize them. In many parts of the XWiki documentation, UI extensions are described using objects, but the interface seems to have changed, and it doesn’t look as straightforward as it used to be to modify a UIXP.

For example, in my XWiki instance, the two UI Extension macros only allow me to set an “id” field—there don’t seem to be any other options available. Am I missing something, or is there a different way to configure them now?

Also, regarding this part: “You could also use JSX to inject some stuff in the UI (using insertion points that match client-side APIs as otherwise you’ll be broken in the future).”—could you clarify how this works in practice? How should I go about using JSX in this context?

Thanks in advance for your help and your time!