New API for Ratings

[surli]

@vmassol

For me what’s important is:

• Keep backward compatibility for the old API, i.e. don’t break devs who have used the old API in their wikis for custom development.
• Have the same name for the api and the app (they’ll be under the same directory anyway so they need a common name).
• Have the same name in the UI than in the code.

So we just have a discussion about that with Vincent, mainly on the first point: we both agree on 2nd and 3rd point.
So now I see two options:

1. We agree that it’s ok to lose backward compatibility of the old API: in that case, we can reuse “ratings” naming everywhere. It would mean that any developer who would have used the old API and who would want to keep using it, could do so by manually installing the old API (we would provide it with a new name, and we could still have bug fixes on it). Now the old API wouldn’t be compatible with the new one, so he wouldn’t have both API on same wiki. Pros: we keep the old name, for most user the change will be transparent. Cons: we break the backward compatibility and users of the old API won’t have any other choice on the long term than updating to the new API.

2. We agree that we don’t want to break the backward compatibility and developers using the old API should be able to keep using it, along with the new API in the same wiki. In that case we don’t have any other choice than chosing a new name for this new API. And we come back on the previous debate about which name to use.

I had not taken into account the first option when starting this proposal to respect our backward compatibility, now maybe in that specific case it could make sense to break it in order to keep the old name. Taking into account, that it’s also unlikely that many people uses the old API directly. So all in all, I’d be now in favor of solution 1.
I’m going to open a limited time vote for those options in a new thread so that we can move on on this topic.
[Edit: the vote is opened here: https://forum.xwiki.org/t/drop-backward-compatibility-on-old-ratings-api/7470]

[surli]

The new API has been released as part of XWiki 12.9RC1, the documentation is available on https://extensions.xwiki.org/xwiki/bin/view/Extension/Ratings%20API since the API is breaking the compatibility I started a small migration guide on this page to help users of the old API to use the new one.

[nishikige]

Hi Surli,

Is ratingconfiguration object meant to work the same as the old rating application per the documentation? I don’t seem to be able to disable or enable specific pages nor spaces with the object config.

[surli]

Hi,

so in theory the Ratings Application should have same capabilities than the old one (except regarding the user reputation as documented in Ratings API (XWiki.org)).

Now the way Ratings works deeply changed and so the way to configure it probably have changed a lot too. So to allow a fine grained selection where the ratings should be available right now there’s only one option: to enable ratings and to exclude some spaces from it.
It’s done through the RatingsConfigurationClass xobject in XWiki/RatingsConfiguration page: when editing it with object editor you should see something like this:

you can fill the list of excluded references so that those references are not using ratings. Note that you can select a parent page to automatically exclude all nested pages from ratings.

We should probably improve that configuration in the future, at the very least to make it enabled from the administration, so don’t hesitate to open a ticket in https://jira.xwiki.org/browse/XWIKI for requesting improvments.