With recent changes to the page layout, a few styles have been updated. Those styles rely on the #rightPanels class to work. The #editPanels is, in most cases, styled exactly the same as #rightPanels. This means that most of the #rightPanels styles need to be duplicated (at least the selectors for the style blocks need to be duplicated).
In our documentation, we have information about standard classes but none about standard ids. The only piece of documentation that is somewhat related to this ID is this unfinished design page.
For this specific ID, it creates bugs. The wiki edit DOM is surprisingly very different from the view mode even though most of it looks very similar – as a dev, I created bugs because of this unexpected difference. This difference takes time to maintain. Since this is not even the main XWiki edit mode anymore, I believe we should try and make it as easy to maintain as possible, even if it means breaking compatibility with some extensions in the process.
Conclusion
What do you think should we go for?
Keep the #editPanels class and its own set of styles mostly duplicated from #rightPanels.
Remove the #editPanels class and break compatibility with extensions.
Is there an aspect of this issue that we missed? Is there another solution that would minimize cons?
Thank you for taking the time to read this, I’m looking forward to your opinion on this subject
It sounds like a strong assumption to me. On the contrary I always considered a bit the DOM ID as a part of the API that wouldn’t be breaking. I’m probably wrong on this, but specifically identifying an element in the DOM is giving it more importance for me, than just giving it an CSS class for example. So for me when you identify it, it means it should be stable.
I would probably do the contrary: always consider that changing an ID is breaking it, and documenting it. And then defining a naming rule for ID that are ok to be broken in the future (e.g. prefixing them with _).
So I guess you meant id and not class here.
I’m ok that we break it, providing we:
document properly the change
check a bit the extension we identified that uses it, and maybe provide a fix there (shouldn’t be too difficult, and honestly I’m not even sure the extension still works nowadays)
I have a third option in mind.
For me, ids and classes both deserve equally to be considered as public APIs.
What’s missing is a clear way to distinguish what is API and what is not (hence the recurrent endless discussions).
for existing code: too bad, we are going to need to discuss what is API and what is not when we change things.
for HTML produced by dependency, where we don’t control the generated HTML: also a case where, unless the library had also a clear way to define an API, we’ll need to discuss case by case
for new code: define a class/id prefix (e.g., xwiki, or xwiki-${moduleName}) to make explicit what is public
Regarding the third point,
we could also make everything public by default, and define a prefix to exclude what should not be API. But that would make things confusing for HTML produced by libraries we do not control.
with a prefix, it is easy to know when something in the selection is not API. e.g.,: .a .b → unsafe, but .xwiki-a .xwiki-b safe.
I understand this does not make the initial discussion progress. But I feel like without discussing these kind of rules we will be stuck with guessing if some attribute is possible used by some external code or not forever.
PS: web components could help at some point as they allow a better encapsulation of implementation details, and forces to make what is part of the API explicit
I agree we need a naming rule for IDs and class names to clearly mark what is public and what is internal, for new code of course (and slowly transitioning the existing code). I’m leaning towards marking explicitly the public API (i.e. have everything internal by default), as Manuel said, instead of marking the internal API. The ‘xwiki-’ prefix sounds good to me.
Going back to #editPanels, I’m OK to remove it and document the breakage.
Okay, thank you for your help on the question! Removing #editPanels with the appropriate documentation.
Note that there’s already a lot of existing IDs and class names with this xwiki- prefix. I think we need a bit of preparation before declaring them as API. I’ll start a couple tables in a design proposal to list them and what we want to do with them. E.g. I doubt we want to make .xwiki-flavor-picker-results-container or .xwiki-select-3-columns a part of our API (personally I don’t think we should, so I would like to at least discuss it together later).
