Issue 1193: Document display hints #1222
Conversation
docs/user-documentation/objects.md
Outdated
|
|
||
| Finally, save your Context. From that point on, whenever the media for a node has the configured Mime type, Drupal will render the media using the corresponding view mode. | ||
|
|
||
| The node-level and global approaches are not exclusive to one another. You can configure the view mode globally and override it at the node level if you want. |
There was a problem hiding this comment.
This isn't entirely correct as one Context can override the other depending the order of execution. Whichever condition is checked last between the "node-level" condition (has-term-based) the "global" (mime-type-based) will override the other.
There was a problem hiding this comment.
Yes, I avoided the ordering topic intentionally so as not to get too far into the weeds. But, if we think it's important to document that here, I will do so.
There was a problem hiding this comment.
I do think it is important to bring up if you have multiple contexts that impact the same display view mode. (Related comment.)
docs/user-documentation/objects.md
Outdated
|
|
||
| The selected view mode will then be used when the node is viewed. | ||
|
|
||
| At a global level, you can create a [Context](context.md) that will detect the media's Mime type and use the configured view mode automatically. To do this, go to Drupal's "Structure" menu, then "Context" and create a new Context. Then, add a "Media has Mime type" condition and specify the Mime type, and add a "Change View mode" Reaction that selects the desired view mode: |
There was a problem hiding this comment.
I think the most appropriate way to do this is to modify the existing Context condition that already exists for the display view mode. E.g. if we want use the PDF mimetype to trigger the PDFjs view mode they should edit the existing one (/admin/structure/context/pdfjs) and add the mimetype condition. As long as "Require all conditions" is not selected, either the mimetype or display mode radio button will trigger the display mode update.
There was a problem hiding this comment.
This makes it more clear to an admin that we already have a condition to do this but we are adding an additional capability that alleviates us from needing to select the view mode explicitly.
Perhaps the more common example would be openseadragon where we want to use the mimetype for JP2 but we can manually select it for regular JPEGs if desired.
There was a problem hiding this comment.
I agree that there are benefits to modifying the existing context, but I think whether or not an admin decides on doing that or creating a new context is probably a matter of personal preference. Your suggested example of an override is good.
There was a problem hiding this comment.
I'm happy to document modifying the existing context but I'd like to mention that there are two ways of doing it. But, that might be too far into the weeds.
There was a problem hiding this comment.
That is fine. I just didn't want new admins to create a new context without realizing that a similar one already exists, especially because creating a separate one could lead to the context ordering issue mentioned in the other thread.
Perhaps you could lead with the modification example and then follow-up with the "you can add an additional, separate, condition; but keep in mind that the order of context processing may cause one to override the other" (or something to that effect).
There was a problem hiding this comment.
Both approaches are described now.
GitHub Issue: (#1193)
What does this Pull Request do?
Updates the user docs to explain how display hints work and how to configure them.
What's new?
Updated
objects.md, plus two additional screenshots.How should this be tested?
Interested parties
@manez, @Islandora-CLAW/committers