Description

• • Goal
  • Front end components
  • DOM API
    • What should we support?
  • CSS API
  • Javascript API
  • Resources

Goal

Define for all non java resources:

• How do we mark an element public or internal?
• How do we deprecate them?
• How we do introduce a new element?
• How do we keep backward compatibility?
• What elements are public or internal

All non java resources:

• vms
• javascript API
• velocity macros
• CSS / LESS elements

Front end components

On Front End resources, we already have a list of components. The features, style  and architecture  of these components would be part of the API as they are meant to be exposed publicly, reused and augmented.

There's velocity macros bundled in the default flavor, some of them match the resources above.

DOM API

Any style attribute should never be considered as API: it's been a long time that we indicate in our documentation to not use inline style, so scripts should never rely on it, and it should always be ok to remove them in old code. Example of such change: https://github.com/xwiki/xwiki-platform/pull/2812/files/95f349912c19b66f00b684153dcf8be6ec526db1#r1504545037

The changes on this basic layout should be documented and backward compatible (CSS or DOM or both ?): https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Skins/CSSLayout/

Discussed on https://forum.xwiki.org/t/front-end-api-html-ids/16947/4 :

Seems like using the `xwiki-` prefix on class and id names would make it clear classes and ids we consider as APIs (and also mean that all the others are not API and subject to changes )) )

Here is the search I went with to find all of those classes and ids. It should be a bit too wide, finding a few things that are not of interest to us, but not miss any of the items we're looking for:
https://github.com/search?q=repo%3Axwiki%2Fxwiki-platform+%28language%3ACSS+OR+language%3ALess+OR+language%3Avelocity%29+%2F%5B%5C.%23%22%27%5Dxwiki-%2F&type=code 

Good news, in XS, there's almost only classes starting with `xwiki-` and no useful IDs starting with `xwiki-`.

I (CharpentierLucas) used four types of annotations when commenting my idea of whether we should keep those in the API:

• Yes: Keep it in the API, the class is common and nicely named, I expect it to be used in a lot of customizations. The class has a clear meaning for an existing concept.
• Yes? : Can keep it in the API, not strongly against removing it. The class is clear, but usually it's not really useful for much, selectors can already rely on another class.
• No? Should probably remove from the API (renaming the class), but not strongly opposed to keeping it. The class is never useful for customization IMO, poorly worded or very specific with easy selectors on the parent. Often those classes are used in XS only for a couple styles.
• No: Should remove from the API, keeping good support and backward compatibility for those will have a relatively high timecost for relatively low usefulness. The class is either very poorly worded, its scope is very very specific and it's purely cosmetic. In order to apply styles, XS developers should instead use 1. a standard styling class. 2. a non API custom class.

IMO it'd make sense we only support classes as API for now, most of XS interface element IDs do not have any naming rules.

What should we support?

For every single class starting with xwiki- in XS, we ensure that we keep backward compatibility on:

• the node architecture under it (node nature + how they are nested/ordered)
• the styles associated to this class
• the styles associated to the expected children of this class

I don't think it's a good idea to engage ourselves to respect backward compatibility on:

• the content of this element and its children
• the attributes of this element and its children

The first one is very often contained in a translation, which AFAIK are not API (i.e. we can edit them without making an announcement and waiting for feedback). The second one should be something only XS relies on IMO. Customizations don't need it much, and it's very difficult to make any change to the UI if we block ourselves on this. Customizations shouldn't need to rely on those, either they have enough with the class and node structure, or they use their own component. E.g. if I want to style livetable, I can make CSS selectors with the API classes and the way their children are arranged. If I want to have a custom script run when a livetable filter is selected, what I'm doing is an extension of the livetable behaviour, and the XS devs can't assure full backward compatibility for this one (if for one reason or another, we need to remove the `selected` attribute, it won't go through the API breakage process).

CSS API

Elements to include in the API:

1. Bootstrap 3 classes: used everywhere, for a long time. When moving to a new design system, we want to consider how to keep support for those classes. E.g. `.btn`, `.btn-default`, ...

2. Special CSS classes defined in https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/SpecialCSSClasses/

Javascript API

Already pretty well defined in https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/JavaScriptAPI/

Resources

Previous research about defining a CSS API: https://design.xwiki.org/xwiki/bin/view/Standards/CSSAPI