Serialize state of the platform as URL
breezykermo opened this issue · 11 comments
In order to be able to cite the platform, the state at any given moment needs to be serialized and made to dynamically modify the URL. As a first step towards this, the selection of any event or set of events should be possible. Ultimately, it would be great to be able to cite certain moments in certain narratives as well.
@francamps are you still working on this by any chance?
The first pass at this was made some 2 years ago now, but it might still be useful.
We're not working on this directly internally, but it's possible that it could become a priority in the next few months.
@breezykermo is this still relevant?
Yes, very much so. It's one of the more desirable mid-sized features for Bellingcat's instance as well, I would suggest.
Starting with events seems like a good idea. What other parts of the platform do you have in mind - filters, timeline, narratives?
Ultimately, it would be great to be able to cite certain moments in certain narratives as well.
A collection of data sheets that use some of the optional features in the project would be helpful. Does sth. like that exist? Are there real world data sheets (besides ukraine) that I can pull into my local datasheet server?
edit: opened a draft PR.
Yes, events and their selection are the most robust abstraction to begin with. Note that an arbitrary number of events can be selected in the platform; and so the query parameter syntax should accommodate this. Something like ?events=1,2,3 is what I am imagining, but I'm not attached to any particular format.
The way that probably makes sense to specify events is by way of their IDs, as these are now (I am fairly sure) static and thus consistent between data updates. (Originally they were dynamic, meaning that an event ID might change when new data was added to a timemap instance.)
The other robust abstraction in the platform is associations, which become filters, categories, and/or narratives when visualized. A serialized state of associations could rely on the type associated with it in the platform data (see the 'export_associations' tab in data/timemap_data.xls for a more visual representation of this). A more flexible implementation of the URL serialization could allow visualizing associations in ways that are not specified by default, in which case the mode could be specified in addition to the association ID. Let me know if this is not clear or could use further explication; I am happy to explain the structure of associations in more depth, as they are not well documented.
?events=1,2,3
In #245, I implemented ?id=1&id=2&id=3 as this is what the standard UrlSeachParams API supports by default. Open to change the naming to event, just mention a pref in the review. Otherwise, I think the draft matches your suggestion.
as these are now (I am fairly sure) static.
I hope this is the case, otherwise the functionality does not make sense. How can we verify this?
The other robust abstraction in the platform is associations, which become filters, categories, and/or narratives when visualized
I'll take a look at associations, thanks. Do you think timeline.range would add value as part of the url as well or not?
Yes, timeline.range is a third good thing to be able to specify as part of the URL, as otherwise only events that fall within the original viewpoint will actually be URL-able. It would also be reasonable from my point of view to default to 'centering' the selected events in the timeline in the state rehydration from URL, which might shortcut / make it more user-friendly needing to specify the right timeframe for a set of events in addition to their IDs.
In terms of the IDs being static; I've just had a look, and I think that we can consider IDs static, and indeed should firm up that requirement in documentation. Technically, as it currently stands, there are not well defined requirements in terms of the data that is served to a timemap instance beyond certain fields being required/optional, and/or typed in Javascript's loose way (number, string, etc).
To provide some context for this: there is some logic as part of the data fetching workflow in timemap that validates certain fields, dropping some events if they are not well-formatted. Additionally, in practice, all of our timemap instances share data validation responsibility with datasheet-server, which is the means by which data from a sheet-like source (ie. an ODS or XLS file, or a Google Sheet) is turned into data of the format that timemap expects.
To summarise, though the requirement that event IDs are static (and indeed also even that they are unique) is currently not strictly enforced anywhere in timemap in code or in documentation, in all practical timemap instances that we maintain that condition is upheld. I will create an issue to make this clearer in the README, which outlines the structure of the data that timemap expects. (The README is likely out of date with respect to other aspects of timemap also.)
to default to 'centering' the selected events in the timeline in the state rehydration from URL
good idea, added a TODO in the code for now.
The other robust abstraction in the platform is associations
if we serialize these, would we have to serialize coloringSet as well? afaict, it's not possible to reconstruct it just by looking at selected associations.