Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue 1193: Document display hints #1222

Merged
merged 5 commits into from
Jul 22, 2019
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/assets/display_hints.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/view_mode_context.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 18 additions & 0 deletions docs/user-documentation/objects.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,21 @@ All nodes can contain any number of media. The media for any node can be manage
the "Members" tab, Actions can be performed in bulk using the check boxes and Actions drop down.

![Media tab](../assets/islandora_8_derivatives_sample.png)

## Display Hints

Media are displayed in Islandora 8 via "view modes". View modes are Drupal's name for alternative ways to present content to users. In Islandora, the view mode determines whether a media is displayed using the OpenSeadragon viewer or the PDFjs viewer, for example. View modes can be set explicitly in the node edit form, or you can configure Islandora to use a specific view mode for all media with a specific Mime type.
seth-shaw-unlv marked this conversation as resolved.
Show resolved Hide resolved

At the node level, in the "Display hints" field, simply check the display mode you want to use for that node:

![Display hints](../assets/display_hints.png)

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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both approaches are described now.


![Display hints](../assets/view_mode_context.png)

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do think it is important to bring up if you have multiple contexts that impact the same display view mode. (Related comment.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, addressed.