[UX] Layout contexts are hard to understand - Document things in a way that makes sense

[klonos]

As per our discussion during the dev meeting last week, I am starting this issue as a follow-up to #3750

The goal is to collect all the various very helpful explanations that people have provided around how contexts (and now the newly-introduced "custom" contexts) work, and then produce documentation to go to our user guide in backdropcms.org.

We should also produce a trimmed-down "summary" version of that documentation, and convert it to a short help text, which will be added in the "Contexts" section of the layout edit form. This needs to be short, use plain language and as less "lingo" as possible, with a link to the user guide for examples and more info/details. Having the documentation hosted externally reduces the maintenance burden for core, and will allow us to improve it "asynchronously" 😉

If you add a comment here to serve as the future documentation for layout contexts, please consider #3750 merged and an implemented feature. So do not use phrases like "with this PR" or "after this change is merged" or "before custom contexts were a thing" ...people interested to know what contexts are and how they work will not care about the history of this feature; no need to confuse them with before/after functionality.

---

NOTE: We have some documentation for contexts on backdropcms.org here:
https://backdropcms.org/user-guide/deep-dive-advanced-layout-options

[klonos]

Contexts added to the layout are information that the layout will be able to make available to the blocks on this layout. Certain blocks may actually require this data to be available, or they wont be presented as available options for placement in the layout. For example, you create a block that you want to show the picture of the user whose profile you are viewing. You can add a Visibility condition, but the block will still show up in the block list when you're configuring or creating any layout. Or you can add a required context in the block's definition in code, then that block will only show up in the block list for layouts that have the User Context applied.

Contexts would normally only be available on pages where the path has a placeholder (%) representing a user, like on a user/% page, or a path anypath/% where you selected User context from path on the layout configuration page. User blocks would then become available in the block list on such layouts. Any fields defined in the user entity would be available as blocks on that layout. The User object that the blocks receive would be whichever user ID whose page was being viewed. So a block on user/2 would only have info/fields from user with UID 2.

You can add specific contexts to any layout. So path "anypath/mypath" could have a context for User 5, or any other user. User blocks would show up in that layout, even though it's not a user path. A block on that layout would have info only on user 5. All the Field Blocks from User 5 would be available on that layout.

Context for any entity can be added to a layout in similar ways. A context for Node 26 added to a layout would make all the field blocks from node 26 become available on that layout.

[klonos]

Field blocks will normally only show up if your path is something like ENTITY_TYPE/% or node/%. If you add a field block for node body field, the body of node 2 will show up on the page. For example, if you add a node context for node 2 to a Layout, then field blocks become available on that Layout (because there is now an available node context), regardless of the path of your Layout.

Advanced documentation, for module developers etc:

This is currently not very extensible; any entity will be available to create a context, but there is no API to add other types of context apart from entity contexts. CTools had query string contexts, and node form context etc.

For now, if you create a new type of context, via hook_context_info() this will show in the select list, the CONTEXT::form() would show, and values would save, but the method of displaying the added context in the context table is now hardcoded to entities.

[klonos]

Possible for inclusion in the help text for the layout edit form:

The concept of a "context" in its simplest form means making blocks available on a layout. For example, if a layout has a node/3 context, all the fields on Node number 3 would become available to add to that layout. Multiple contexts can be added to each layout.

Possible for inclusion in the user guide, as an example use case (remove mentions of "node" and "entity" where possible):

1. Create a node, add some content in the body and/or image or any other field. Save. Say this ends up being node/3, after you save. This will be your source of field blocks.

2. Now create a layout with a random path (contexts/rule for example), then add a context for Node, and type in NID 3 (or whatever the NID of the content in step 1 is). Then go to the "Manage blocks" page of your new layout. You will notice that the field blocks are available, although this isn't a node/% page. Add the Body (and/or whatever other field) block to your layout. Save.

3. Go to path contexts/rule and see that the body (or image or whatever field) of Node 3 will be visible at that path.

You can do the same for other entity types. Add fields to user or term entities, create a user/term as a source for blocks, then add a context for that user/term to your new layout. You can use the same layout, and add multiple contexts. So blocks from Node 3, 4, 5 and blocks from User 2, 3, 4, etc all can be available to that layout.

[klonos]

Note: page titles of a context node CANNOT be available as a title block or a breadcrumb option, since page title isn't a field.

[klonos]

There are blocks that will only appear in the block list if their required context is available. Field blocks require a fieldable entity, so a node, user, or term context must be present for them to appear. The contexts we already have in core are node, user, and term.

Blocks are only one example of a thing that requires a context, and field information is only one example of a block that requires the context. A Visibility condition is another example of a thing that might require a specific context. The condition for node type, for example, is only available when a node context is present. In Panels-land, these things were called plugins.

[klonos]

When you create a layout with a node path like node/%, this tells the layout to create a context for nodes. When you go to node/5 layouts loads data from node NID 5 into that context, so that that node becomes available to every block in that layout. But if your layout path was notanode/anypath this wouldn't happen. Your blocks would have no access to node data. Blocks requiring node data would refuse to show up in this case. You can still make your layout path notanode/anypath, then manually add a context for nodes. When you visited that path, data from node NID 5 would be loaded into that context. Blocks requiring node data would show up.