Rework tour DB schema

[lentinj]

There currently exists a DB schema and controllers using it, these should be considered dead.

There should be a minimal getter / setter for tour JSON documents, as illustrated by the example:

https://github.com/OneZoom/OZtree/blob/edcd6408065d5e2ba3bb25b1b735032c4844806b/OZprivate/rawJS/OZTreeModule/src/tour/Tour.js#L25-L154

The internal structure should allow for:

• Finding of intersecting tours; i.e. tourstop OTTs should be searchable
• Free-text search of Tours / TourStops for finding Tours via. search
• Localised tours, i.e. storing many languages for strings and resolving according to the currently-set language.

[lentinj]

Do we want to replace "update_class" with a server side templating engine, and return HTML chunks for tourstops? Lots of advantages:

• Don't have to drag in another templating engine
• Get to keep using web2py localisation
• Strip out complexity from TourStop.js
• Much more flexibility for our own tours, can output ~anything as a TourStop.
• Full-text searching of tours could be done by pre-rendering to HTML and flattening to plain text

...but OTOH means that the getter / setter API won't deal in identical documents; the output will have additional HTML you won't get to set.

EDIT: Server-side templating at least worth trying and seeing if it's got legs. Having templates stored on filesystem is a good way of gatekeeping the HTML that ends up on our site (anyone who wants to customise could just run their own docker image)

[lentinj]

What's a better way of handling translations?

1. Tours have a native language, separate tours for each language. Use existing web2py translation engine to try and translate.
2. Embedded translations in the tours, our own translation engine
3. Make any phrases in user-generated tours available in the future Volunteer page for translations

I'm tempted to assume (1) for now, then hook into the volunteer translation engine when available to translate tours. When available we'd still need a native language for the tour anyway, so the data structures don't change.

EDIT: Me & James agree with the above. (2) is silly.

[lentinj]

What visibility controls do we need for a tour?

• Shows up for only native language
• Shows up in searches for constituent species / text
• Shows up in ribbon when nearby constituent species

Are there more/less?

• [x] EDIT: This is just "available in search" or not. Anything else is just available by name and that's it.

[lentinj]

Do we need to have provision for a thumbnail for a tour? Either of a species or custom image?

(if we did, where would we show it?)

[lentinj]

• [ ] We also need to store a list of OTT highlights to apply when at the tourstop

[lentinj]

• [x] Are Tour <-> TourStops Many:Many or 1:1? Might want to re-use tourstops for e.g. animal sounds or dangerous animals and re-mix them.

• [x] Stick with TourStops having transition settings, a tour/tourstop/ord mapping table and Tour. Having it is more flexible than not. It also enforces a tourstop to keep branding along with videos, rather than making it too easy to edit slides and remove branding. Edits for accuracy can also be done once.

• [x] A TourStop will also want some kind of author, CC-BY/PD, and search visibility for whether it's available for remixing---if it's not findable, then you can't include that in your remixed tour anyway.

[lentinj]

Image & A/V asset ownership / rights information:

• TourStops should have ownership to display, and we assume this applies to the image too
• Right information would be field in template data
• Remixing will enforce the rights will still be displayed because we don't allow editing of TourStop in mixing
• What do we do to validate TourStop links?

Do we want to offer upload of images, at risk of moderation woes? Probably worth the risk, but a separate tool to upload and include a URL.

[lentinj]

What if a tour requires particular visulisation shape / colour scheme / etc settings?

Is it restricting (you only see that tour if that mode is set), or do you switch and switch back?

• [ ] Extinct species will be a different "/life", not part of the URL We restrict, not switch here.
• [ ] We need to keep "_CBF" regardless of colour scheme. NB: The tutorial tour assumes extinction risk colour scheme, we can switch for this.

[lentinj]

We need a slot for highlighting colours, a la common ancestor highlighting.

We also need to show the highlights at start of transition as well as the start of a tourstop

• [x] A tourstop should be able to specify 2 OTTs as a common-ancestor highlight.
• [x] Use URL parser to help decide position, rather than inventing our own specification scheme (corollary, can you specify the common ancestor in a URL?) https://github.com/OneZoom/OZtree/issues/548

[lentinj]

• [x] Highlights, Narration and e.g. mouse symbols appearing are all part of a similar problem, that we need to specify if something happens at flight or at tourstop show. Generalise concept to cover everything? https://github.com/OneZoom/OZtree/issues/539

We already have "transition_in_visibility": "show_self" and other values, specifying at what point we show the TourStop

[lentinj]

pos: {xp:, yp:, zp:} doesn't seem to be used. As a result we'd like to ditch it.

• [x] It then becomes into_node true/false, instead of the slightly ambiguously named "pos".

We later on will want more flexible into_node-ness: #541

[lentinj]

Tours should have an image, whether it displays in search results or not, it will at least need to display something when a tour is used in popular places.

This should be a URL field, not just a pic_src/id, since there's no OTT image for a dinosaur, e.g.

See: https://github.com/OneZoom/OZtree/issues/545

[jrosindell]

Do we need to have provision for a thumbnail for a tour? Either of a species or custom image?

(if we did, where would we show it?)

I think we do need this yes and it would be used in the ribbon and (later) in the search results if we end up revamping the search to put icons for search results - we'll see what UX say about that. In any case I think it's good for the schema to allow for such a thumbnail as we may also use it to promote a tour through other channels.

I see @lentinj allows for a URL which is fine because the URL could be to an asset on our own server if we're doing it like that.

[jrosindell]

Do we want to offer upload of images, at risk of moderation woes? Probably worth the risk, but a separate tool to upload and include a URL.

I think yes and have commented on this in #601 - at present there are no third party tours and it's not part of the present project so moderation not yet a concern. What is a concern is knowing the tours we create ourselves can be reliably offered into the future because we have our own copies of all the necessary assets.

[jrosindell]

Probably I just have a poor memory but are the JSON instructions being dismantled and injected into the database then re-built when needed? If this is the case then should there be some simple script to validate a JSON before it gets put in the DB?

[lentinj]

are the JSON instructions being dismantled and injected into the database then re-built when needed?

Ish. All tour and tourstop fields are represented in the DB schema (and hence validated by it), however template_data is stored/restored as-is. Nothing will validate that these are structured as the template expects.

If this is the case then should there be some simple script to validate a JSON before it gets put in the DB?

I had been wondering about a JSON schema for the tours, both for validation and documentation of the format. However, this isn't something web2py includes support for.

We'd have to code it in python within controllers/tour, which wouldn't be the end of the world, but won't be as readily accessible as documentation.

[lentinj]

This ticket has grown unwieldy, so breaking out the remaining problems:

• https://github.com/OneZoom/OZtree/issues/602
• https://github.com/OneZoom/OZtree/issues/603