Managing vault(s)

[tomcrane]

What's the right way?

<canvas-panel id="cp"></canvas-panel>

<script>
  const vault = window.__hyperionVault__; // The global vault.
  // am I using the same vault that cp is using?
</script>

or

<canvas-panel id="cp"></canvas-panel>

<script>
  const vault = document.getElementById("cp").vault;
  // .. do stuff with cp's vault that it made itself?
</script>

or

<canvas-panel id="cp"></canvas-panel>

<script>
  const vault = new Vault();
  cp.vault = vault;

  // load stuff...
</script>

And if so, can you do this? Would you ever do this? Is this nonsense?

<canvas-panel id="cp1"></canvas-panel>
<canvas-panel id="cp2"></canvas-panel>

<script>
  const vault1 = new Vault();
  cp1.vault = vault1;
  const vault2 = new Vault();
  cp2.vault = vault2;
</script>

[stephenwf]

All very good questions. Hyperion has a global vault as a default that will end up covering 99% of use-cases. When creating a new Vault() instance, you can override some of the internals - such as how IIIF is fetched. Madoc uses this to add authentication for example, and do some transformations after fetching.

When using the web components though, it's unlikely that you would need to set the vault manually. The global is also available at:

HyperionVault.globalVault();

Which would be preferred over: window.__hyperionVault__

[tomcrane]

Does the presence of any web component on the page establish the global?

So just by having

<canvas-panel...>

... I can later call

const vault = HyperionVault.globalVault();
vault.load...

without doing anything else?
So this is the preferred mechanism (make sure you always get the global vault unless you really need something else for some reason). I'll update examples to use this approach.

Is it also permitted to access cp.vault to get the vault that a particular cp instance is actually using? In rare occasions where it's not the global? Or should the developer keep track of that?

<canvas-panel id="cp"/>

<script>
const cp = document.getElementById("cp");
const globalVault = HyperionVault.globalVault();
assert(cp.vault === globalVault);
cp.vault = new Vault();
assert(cp.vault !== globalVault);
const cpVault = cp.vault;
cpVault.load(..); // do something that global vault doesn't know about
</script>

[stephenwf]

So this is the preferred mechanism

Yes that's right, should just be transparent for the most part. One vault for everything.

Is it also permitted to access cp.vault to get the vault that a particular cp instance is actually using? In rare occasions where it's not the global? Or should the developer keep track of that?

Yes that's right, but it should only be different if the same user has changed the vault or if you're developing some extension and don't know.

Setting the vault directly would likely cause some undefined behaviour. If you created a <canvas-panel iiif-content="" /> expected it to load that content and then swap the vault out, it wouldn't re-run an initialisation step to load into the newly set vault, that would be down to the user. However, if the attributes changed the new vault would be used and data loaded in. All speculative, as I say - manually setting the vault while also relying on the iiif-content="" or partof="" attributes would be undefined.

[stephenwf]

This also needs similar consideration for frameworks. For example, in React, in your top level:

<VaultContext>
  <App />
</VaultContext>

And then you can get access to the vault at any time, in any component using:

const vault = useVault();

and then some React-specific abstractions.

useVaultEffect(vault => {
  doThisThing();
}, [whenThisChanges])

[stephenwf]

An experiment for Vue could use their "inject".

Similar to React, a global "wrapper" around the app template.

<Vault>
  <app /> .... 
</Vault>

And then any custom component, you can access the vault using the inject.

<script>
export default {
  inject: ['vault'],
  data () {
    this.vault // do something with vault.
    return { ... };
  },
}
</script>

This model could be extended for the current "manifest" or "canvas" conceptually. Explored more in this demo