Links should be ordered again, but only when the name of the link type communicates that they're ordered.
The publishing API allows us to represent links between content items by posting a links hash containing arrays of content ids.
In our current model, a link stores 3 pieces of information about the relationship between two items:
We have many link types, which are used in different ways by the frontend applications.
Links can be updated as part of the publishing workflow, or they can updated separately (for example through content tagger). When we change the links originating from a content item, we make a PATCH request to its links URL, with a JSON object describing link sets. For example:
The ordering of items within the arrays is arbitrary in these requests: the publishing API deliberately ignores the ordering.
As we've migrated more things to the new publishing platform, we've come across use cases where ordering of links matters, and have had to implement error-prone workarounds.
- [ link type. There is a natural ordering around age of the child, which helps the user identify the section they need more quickly.
Without the manual override, the sections would be sorted alphabetically, which is generally not very useful unless the user knows the exact name of the section they need. In the absence of more content-specific metadata to order by, manual ordering gets the job done.
2.
3. _ ** the links are manually ordered by relevance rather than A-Z.
- It should be possible to define, for each link type, whether the links are ordered or unordered. No change is required to the patch links payload.
- Unordered link sets will be handled in the same way we handle all link sets now.
- When a patch links request operates on ordered links, the publishing API must retain the ordering of the array when persisting the links to its database and loading them, and the expanded links passed to the content store should retain this ordering.
- Whether the link type is ordered or unordered should be conveyed to the frontend applications. We suggest that the ordered/unordered distinction is conveyed by a naming convention: link types are unordered by default unless they start with the string "ordered_". For example, to introduce ordering on related links, we would introduce a new link type, "ordered_related_links".
-
Ordered links are intended to be used as a curation mechanism when there is a natural ordering to a link set that is not possible to infer from metadata of the target content items.
-
Ordered links should not be used if the ordering can be inferred from the content itself by comparing attributes of the expanded links hash; for example, A-Z ordering by title.
-
Frontend applications shouldn't make any assumptions about what ordered links are ordered by; publishers should be free to choose an appropriate ordering for their content; for example, "early years comes before schools".
-
Using an ordered link type shouldn't place any restrictions on frontend rendering. A rendering app could sort the links differently; for example, by providing alternate views that show recently updated pages first.
-
The PATCH semantics of publishing API will be unchanged: it is not possible to change part of a link set without sending the entire thing to the publishing API.
-
Frontend applications should use ordered_foo over foo if both are available.
-
Setting a link_set of type ordered_foo should automatically clear links with type foo.
-
Setting a link_set of type foo when a link set of type ordered_foo exists is allowed, so that publishing apps have the option to capture the ordering in a separate step.
-
Ordered link types should not contain unordered link sets. Instead, use two link types, one ordered and one unordered. It should be obvious from the user interface what is being captured; for example, collections publisher presents ordering as an extra step:
Essentially reverting
- This has fuzzy semantics - it becomes unclear if the ordering is something the user intended or just the order they happened to enter it
Previously rejected in
This is more flexiblebut also more work to implement.
- Difficult to make backwards compatible
- Lots of publishing apps would need to change
- Lots of frontend apps would need to change
For example, adding a links_metadata hash to the content store representation, while supporting the existing links hash as a fallback.
Apps are forced to handle both cases separately, so there is more room for error
Doesn't provide any additional benefit over RFC 38