Global Contexts

[bszyman]

📋 Description

Revised Global Contexts section for clarity and added best practices guidance.

📎 Related Issues (if applicable)

#7430

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

• Code blocks are correctly formatted.
• Sentences are short and clear (preferably under 25 words).
• Passive voice and first-person language (“we”, “I”) are avoided.
• Relevant pages are linked.
• All links work and point to the correct resources.
• Screenshots or diagrams are included if useful.
• Any code examples or instructions have been tested.
• Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

v16

Deadline (if relevant)

N/A

📚 Helpful Resources

• 🧾 Umbraco Contribution Guidelines
• ✍️ Umbraco Documentation Style Guide

[bszyman]

getHostElement() is required by UmbContextMinimal, but I'm not sure what the intent of this is? To return a DOM element? The DOM element that the context is attached to? That's kind of how it seems to be getting used in the Umbraco backoffice samples I've found, but it seems odd.

https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_context-api.UmbContextMinimal.html#gethostelement-1

[iOvergaard]

Agreed, it seems odd. We need @nielslyngsoe's perspective on this. We could provide any value as a context, including simple types such as string, number, and array, I thought.

[bszyman]

In my Umbraco project I'm using for testing all of this docs code, I just did return new Element(); inside of there to keep the project compiling, but I feel dirty publishing that without further comment or without understanding what might blow up.

[nielslyngsoe]

Hi everyone :-)

The UmbContextMinimal abstraction/interface might confuse matters, so for understanding, I would say ignore that one. It only exists to avoid circular dependencies and separation of concerns.

So the particular need for the getHostElement is that this is the only part of a UmbControllerHost that the Context implementation must have.
But it could have been simpler if the example interface extended UmbControllerHost. But for someone not basing their class on UmbContextBase(Which is an extension of UmbControllerBase) will then have a more complex interface to adhere to — so that could be the downside to it, but maybe only relevant for complex use cases, like someone implementing a different framework, so maybe an aspect to ignore.

So you could avoid declaring the getHostElement by making the interface extend UmbControllerHost — this is all handled, from an implementation perspective, as your class extends UmbContextBase.

[nielslyngsoe]

... and I may add that the getHostElement is supposed to return the element that hosts the controllers. For a Context Consumer or Provider, this is the element used to fire or listen for DOM Events. So this cannot be a virtual node, it needs to be the Element that the code belongs to. But @bszyman maybe in your case it was not needed, so it worked from a compiler perspective. But it would eventually result in things not working. :-)