Handle canvases that have one or more resources with Choice

[tomcrane]

Extension of #9

As explained in #9, I don't necessarily need to know in advance that the Canvas has resources with Choice for something to render. In simple scenarios, I might not want to know, because there's nothing I can do about it anyway. Let the component make a sensible default choice, because anything more means I need to provide more user interface to deal with the user making one of more choices... which can extend into blending of layers, etc.

The thing to flesh out here is how do I react to the presence of one or more Choice?

First I need to know what choices are available (when? how? listen for content-loaded event on the component and then inspect it? Receive a specific choice-detected event?)

Then I need to know what the choices are (the component should probably just give me the IIIF model back here) - I need their labels, ids and in the supplied order from the original IIIF Canvas.

It's up to me to render some UI for presenting those choices to the user (but as with other examples in these discussions, we could provide a sample reference implementation that can be reused).

As the user makes their Choice, the API of the component is called and it updates the rendered scene.

"Show the choice with id xxx" - simple approach
and/or
The canvas rendering component is bound to my choice UI and is reacting to my actions in it

I can also blend:

"Show the choice with id xxx at 80% opacity AND show the choice with id yyy at 50% opacity, all the others are at 0%"

[stephenwf]

The canvas rendering component is bound to my choice UI and is reacting to my actions in it

This will likely be the tough part. I've thought about it before. If we did raise an event, or had some callback somewhere, you could image a develop experience like this:

function handleChoiceDetected(data) {
  data.choices // the choices in the IIIF form.

  data.renderChoice(data.choices[0]); // render a single choice (hiding any others)
  
  data.renderChoice([data.choices[0], data.choices[1]]); // Or render multiple
  
  data.setOptions(data.choices[0], { opacity: 20 }); // Something to pass directly to the rendering
  data.setOptions(data.choices[1], { opacity: 80 });

  return function() {
    // An unsubscribe callback for when the UI can be removed.
  };
}

So you could bind this to an external UI, but everything you need is here and not part of some library you need to pull in.

[tomcrane]

Need to think how far we want to take this for the product site placeholder.

In a viewer:
user navigates to a canvas
viewer sets CP source to the new canvas
CP renders default view
cp fires "choiceDetected" event (?)
viewer renders choice UI
user makes a choice in choice UI
viewer tells CP to show choice (as above)

[stephenwf]

That's right, we can do this synchronously, so if there no callback or no instructions after we fire the event, then we just render the first / default choice and move on.

[tomcrane]

Demo of Hyperion handling choice: #25

To be explored in pseudocode -

my code waits for CP general purpose ready event; in that handle it checks to see whether cp.choices > 0
or
my code waits for a specific CP choicesDetected event

How does it access the choices on the canvas?

cp.choices -> one or more sets of painting annos with Choice bodies. Or helper wrapper object for these that are easier to drive.

my code renders a choosing UI - or, actually, one per set of choices (uncommon but possible)

Is data.choices in the code sample above the same resource as cp.choices? Rather than only being able to change choice visibility in the choiceDetected handler, I should be able to walk up to CP any time, see if it has choices and manipulate their visibility if it does have them.

I should also be able to interrogate their current visibility. E.g., I didn't record the fact that I set a particular "layer" to 50% opacity 5 minutes ago, but I can see what everything is set to now.

(luckily, anno painting order is same as CSS stacking order...)
then

[stephenwf]

From the point of view of a developer using these web components, a choice could happen either before loading or after.

Web component

If I know which choice should be chosen, I can use the web component to make that choice.

<canvas-panel canvas-id="http://example.org/canvas-1.json" choice-id="http://example.org/choice-1" />

Before loading

Before I put the <canvas-panel /> web component on my page I can first load the manifest into the vault, find out if there is a choice and render a UI.

vault.loadManifest('http://example.org/manifest.json').then(manifestRef => {
   // At this point I know the canvas is loaded - could also 
   const canvas = vault.fromRef({ id: 'http://example.org/manifest/canvas-1.json', type: 'Canvas' });

  // These are "invented" helpers.
  if (vault.containsChoice(canvas)) {
    const choiceSets = vault.extractChoiceSets(canvas); // Array<{ annotation: {}, choices: Choice[] }>
    // Render UI for choices.
    // When I'm ready, I can insert a web component onto the page:
    // <canvas-panel canvas-id=" ... " choice-id=" ... " />
  } else {
    // Render normal component
    // <canvas-panel canvas-id=" ... " ... />
  }
});

This gives complete flexibility over choices at the data level, and can happen before anything is rendered to the user.

After loading

In most cases, you won't want to handle a choice until you come across one. So the canvas panel component itself could dispatch events for you to respond to.

<canvas-panel id="viewer" canvas-id="http://example.org/canvas-1.json" [ ... ] />

<script>
  const viewer = document.getElementById('viewer');

  viewer.addEventListener('canvas-choice', (helper) => {
    helper.choices // the choices in the IIIF form.

    helper.renderChoice(helper.choices[0]); // render a single choice (hiding any others)
  
    helper.renderChoice([helper.choices[0], data.choices[1]]); // Or render multiple
  
    helper.setOptions(helper.choices[0], { opacity: 20 }); // Something to pass directly to the rendering
    helper.setOptions(helper.choices[1], { opacity: 80 });

    return function() {
      // An unsubscribe callback for when the UI can be removed.
    };
  })
</script>

When that event fires, as a developer I can render my own UI from that data and bind renderChoice to buttons to control the viewer. This UI could appear only when a canvas has a choice and the user could use the UI created to switch between them. With the returned function, that UI could be cleaned up if the canvas is switched.

Since the choice-id attribute also drives this, I could do the following to manually set the choice ID.

element.setAttribute('choice-id', 'http://example.org/choice-1')

[tomcrane]

This is rare, but the canvas might have two or more painting annos that each have a Choice body, so two (or more) sets of independent images that would each have their own independent choosing UI. I think this is just an extra layer in the model above though. I confuse myself with this because the word "choices" could be either of these levels. so:

const choiceSets = vault.extractChoiceSets(canvas);
const choiceItems = choiceSets[0].items; // only the first set's items
// or maybe choiceSets is a dictionary by id, but whatever...

Real world fake example:

https://en.wikipedia.org/wiki/Ghent_Altarpiece

Each individual painting has been individually photographed in multiple wavelengths. We've got a canvas for the whole altarpiece and you can individually mix what multispectral layer is visible.

[stephenwf]

Right - that's a good point. I think using the model above you would get 2 events fired for the canvas. So you could write your code to handle multiple coming through and have a different event that will aggregate them into a choice set. The first example, manual extraction could work as you describe there.

[stephenwf]

For multiple choices there, we could accept comma-separated values for choice-id:

<canvas-panel choice-id="http://..choice-1, http://...choice-2"/>

[tomcrane]

A thought on

viewer.addEventListener('canvas-choice' ...

The developer showing UI is going to need to react to an event to decide what UI controls to show, but what's that event?

In the example above there's a specific CP event "I've found a choice or choices in the canvas" and the developer reacts to it by building the choice UI.

An alternative approach would be a CP event "I've loaded everything I'm going to know about this canvas, for now" - kind of like $(document).ready ;) - then the developer interrogates: "Do you have any choices?" (if they are able to do anything about that).

Do we support both?