API app: add a way to manage the achievement display order number

[meleu]

This issue is just a RAWeb-related entry for this request: RetroAchievements/RAIntegration#771

I plan to do it soon (add a new request in dorequest.php).

[Jamiras]

Please don't rush this. The corresponding UI changes won't be ready for some time.

First step is to get the display order values to the client. It would probably be easiest to include that in the existing payload for r=patch. Then the client could use that information when displaying the achievements in the achievement list and the achievements overlay.

The next step would be to get the updated order back to the client. Should that be part of r=uploadachievement, where each achievement would have to be updated separately and would generate a modification comment? If not, what does the payload look like? Is it just a list of the IDs in the desired order, or is it a map of IDs to their new display order values?

This API could need to be expanded in the future to support folders. How would that affect the design?

The existing UI allows for gaps and duplicates. Is that desirable? If the user is allowed to enter display order values, what sort of validation is required?

[meleu]

I may have sounded a bit jumpy, but I'm going to do some research before actually implementing this. 😇

First step is to get the display order values to the client...

The client already displays the achievements in the right order (in the Achievement Sets dialog and in the overlay) because data is passed to r=patch after an ORDER BY DisplayOrder in this SQL query.

Making the DisplayOrder data be returned together with the other fields would be pretty simple, but I wonder if it could break something in the toolkit or the extra data would just be ignored. Do you (@Jamiras) have an answer for this?

The next step would be to get the updated order back to the client.

Making r=uploadachievement able to handle the DisplayOrder would be simple too. And, yeah, it would generate a bunch of modification comments, but as that is a temporary workaround for a (pseudo) audit log, I'm OK with it.

Creating a new request to get a list of IDs and the desired order would be cleaner (just one request and no modification comments), but would require more work. Maybe something for v2?

This API could need to be expanded in the future to support folders. How would that affect the design?

Sorry, I didn't get what exactly is your concern here. Anyways, the DisplayOrder field is already used currently, then we wouldn't change anything in the DB.

The existing UI allows for gaps and duplicates. Is that desirable? If the user is allowed to enter display order values, what sort of validation is required?

What I envisage after a first thought:

• do NOT allow the user to explicitly type an arbitrary DisplayOrder number.

• when promoting a cheevo to the core, set its DisplayOrder to the value of the biggest DisplayOrder plus 1.

• add something like up/down arrows in the "Achievement Sets" dialog box.

  • if up-arrow, set the selected cheevo's DisplayOrder to the value of the DisplayOrder of the cheevo above, and this one gets its previous value plus 1.
  • if down-arrow, set the selected cheevo's DisplayOrder to the value of the DisplayOrder of the cheevo below, and this one gets its previous value minus 1.
  • after moving the cheevos up/down the characters become red (just like what happens when you edit something else for that cheevo) and the user needs to "Commit Selected" each "moved" cheevo to save the changes in the server.

By the way, I've just tested on the website: if I enter a negative value it defaults to 0, and if I enter a value greater than 10000 it defaults to 10000.

[luchaos]

there are standard ways to do such tasks in a clean way with a suitable, standardized json api. which we do not have yet.
i'd suggest to rather add that with a new api than to add that to the current dorequest.php "API" as we have to migrate everything at some point.