Document file viewer logic. (#1722)

docs/user-documentation/file_viewers.md

@@ -0,0 +1,90 @@
+# File Viewers
+
+_last updated on 03-12-2020_
+
+
+## What are viewers?
+
+[Viewers](../glossary#viewer) allow site builders to display files in interactive javascript-based widgets, that provide functionality like zooming in/out, turning pages, playing/pausing, viewing in full screen, etc. 
+
+In Drupal, a common way to implement a viewer is through a [module](./glossary/#module) that provides the javascript library, and a field formatter that uses that library. The field formatter will work with specific types of Drupal fields (e.g. file fields or image fields, some may even provide their own fields).
+
+Viewers that are known to work with Islandora 8 include:
+
+* [OpenSeadragon](https://openseadragon.github.io/), via the Drupal module [OpenSeadragon](https://github.com/Islandora/openseadragon) (maintained by the Islandora Foundation).
+* [pdf.js](https://github.com/mozilla/pdf.js), via the Drupal contrib module [PDF](https://www.drupal.org/project/pdf)
+
+Both are included with Islandora Defaults.
+
+
+## How are viewers configured?
+
+In the generic Islandora 8 content modelling scenario, we often want the viewer to appear on a _"resource node"_ when the file itself is in a field on a Media that references that node. These layers of indirection make displaying viewers on nodes rather complex. 
+
+## Example - Open Seadragon (in Islandora Defaults)
+
+Here is how viewers are implemented in Islandora Defaults. This example uses OpenSeadragon, but pdf.js is configured with the same method. This method was chosen because it uses pure configuration and no extra code. It relies on users tagging nodes with appropriate "display hint" terms to trigger Contexts to switch the node's display mode to one that includes an EVA field, which renders the appropriate Media in a way that shows the desired file in the viewer.
+
+<!-- Display modes vs view modes - Here we prefer the term 'display mode' to refer to the modes listed under Structure > Display Modes > View modes. The reasoning is that for the audience of this page, this concept is likely most frequently encountered under "Manage Display" of an entity, and to distinguish it from concepts relating to Views, such as Views displays. --> 
+
+### Expected behaviour for this scenario:
+
+Create a Repository Item, and tag it with "Open Seadragon" (under Display Hints). Add a Media of type "File" to that node, upload a file such as a tiff or jpeg-2000, and tag it with "Original File" (under Media Use). Save and publish the Media. Go to the Repository Item's page, and you should see your file displayed in the viewer.
+
+<!-- There should be a link here, on the word "File", that points to a page explaining why large images need to be Files and not Images. That is out of scope here. -->
+
+<!-- "a file such as tiff or jpeg-2000" = "a file that works with Cantaloupe". OpenSeadragon relies on an IIIF image server, in our case, Cantaloupe, and that is what determines the kinds of files that this works with. This is also out of scope for this page. -->
+
+### Components of this scenario: 
+
+1. A viewer that includes a field formatter  (e.g. the module OpenSeadragon)
+1. A media display mode (e.g. the media display mode "Open Seadragon")
+1. A media type (File, though Image is configured similarly)
+1. A file field on that media type that can use that field formatter (e.g. field_media_file)
+1. A field on that media type that points to a parent node (e.g. field_media_of)
+1. Display Mode Configuration  (make that display mode, on that media type, show only the file field rendered through that viewer's field formatter. e.g. see Media Types > File > Manage Display > Open Seadragon)
+1. An EVA view (which shows a node's attached media as rendered by that Media display mode. e.g. the view "OpenSeadragon Media EVAs")
+1. A content display mode (e.g. the node display mode called "Open Seadragon")
+1. A content type (e.g. Repository Item)
+1. Display Mode Configuration (make that display mode, on that content type, display that EVA as well as whatever metadata is relevant - see Content Types > Repository Item > Manage Display > Open Seadragon )
+1. A taxonomy term with a URI (e.g. "Open Seadragon" (http://openseadragon.github.io) imported by a migration in Islandora Defaults)
+1. A field on that content type that can have that taxonomy term (e.g. the "Display Hints" field on Repository Item)
+1. A context (which says if a node has that term, then change to the display mode. See the context "Open Seadragon")
+
+### Logic:
+
+- If a node has the right term
+- then a context is triggered
+- so the node gets shown in a custom display mode
+- which you configured for that content type
+- to include a custom EVA View "field"
+- which displays the node's attached media rendered in a custom media display mode
+- which for that media type is configured
+- to display nothing but the file in a viewer.
+
+### Relevant files:
+
+Islandora Defaults is a Feature, and the following YAML files in `islandora_defaults/config/install` contain configuration items that are loaded when the feature is enabled. Changes to these files will not affect the live site configuration, and changes to the live site configuration will not be reflected in these files. 
+
+| Filename | Comments|
+|---|---|
+| `core.entity_view_mode.node.open_seadragon.yml` | (a media display mode) defines the Open Seadragon display mode as an option for any Media |
+| `media.type.file.yml` | (a media type) define File media, or in this case, re-define an existing type provided by Core. This feature will override the core settings. |
+| `field.field.media.file.field_media_file.yml` | (a field that can use the viewer) Defines a file field on File media called field_media_file, or in this case, re-defines it because it was already part of core. Usually you need a field.storage too but it was already defined in core and is not overridden here. |
+| `field.field.media.file.field_media_of.yml` | (a field that points to a parent node) attach the the "Media Of" field to File media. In this case again, the field storage is not present because it was defined in Islandora Core Feature. |
+| `core.entity_view_display.media.file.open_seadragon.yml` | (view mode configuration) configures the Open Seadragon display mode for File media, so it shows only the field_media_file using the Open Seadragon field formatter. |
+| `views.view.openseadragon_media_evas.yml` | (an EVA View) defines a view that shows a Media that is "Media Of" the current node (from URL) and is published and has "Media Use" = Original File. (there are two other EVAs defined by this view that use Preservation Master and Service File respectively.) |
+| `core.entity_view_mode.node.open_seadragon.yml` | (a content display mode) defines the Open Seadragon display mode as an option for any Node |
+| `node.type.islandora_object.yml` | (a content type) defines the Repository Item content type |
+| `core.entity_view_display.node.islandora_object.open_seadragon.yml` | (view mode configuration) configures the Open Seadragon display mode for Repository Item, so it shows the Open Seadragon EVA for Original File as well as normal metadata |
+| `taxonomy.vocabulary.islandora_display.yml` | (taxonomy vocabulary) define a vocabulary to hold display hints  |
+| `migrate_plus.migration.islandora_defaults_tags.yml` | (migration) create a term in that vocabulary for "Open Seadragon." Taxonomy terms are "content" so must be entered through a migration. |
+| `field.storage.node.field_display_hints.yml` | (field storage for display hints) defines the display hints field as an option for any node |
+| `field.field.node.islandora_object.field_display_hints.yml` | (field for display hints) configures the display hints field on Repository Item |
+| `context.context.open_seadragon.yml` | (a context) tells nodes with term "Open Seadragon" to use display mode "Open Seadragon" |
+
+
+## Improvements
+
+This is awfully complex. If you'd like to help simplify it, we have an open issue about getting rid of display hints, and instead "sniffing' the file's mime type: [Deprecate display hints in favor of Contexts? #1193](https://github.com/Islandora/documentation/issues/1193). Other suggestions and solutions are welcome in the [issue queue](https://github.com/Islandora/documentation/issues).
+

docs/user-documentation/resource-nodes.md

@@ -1,3 +1,6 @@
+# Resource Nodes
+
+_last updated 03-12-2020_
 
 A resource node holds the descriptive metadata for content, as well as grouping together an original file and
 all of the derivatives files generated from it.   
@@ -104,19 +107,19 @@ the "Members" tab, Actions can be performed in bulk using the checkboxes and Act
 
 See [the media section](media.md) for more details.
 
-## Display Hints
+## Display Modes
 
-Drupal uses "View Modes" to provide alternative ways to present content to users. You may be familiar with the "full" and "teaser" versions of nodes, which are rendered using two corresponding kinds of View modes. Islandora also uses view modes to control how media content is displayed. Islandora provides two view modes for Media, one which renders the OpenSeadragon viewer and the other which renders the PDFjs viewer. These two 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 using [Contexts](context.md).
+Drupal uses "display modes" (also called "view modes") as alternative ways to present content to users. You may be familiar with the "full" and "teaser" versions of nodes, which are rendered using two corresponding display modes. Islandora makes use of display modes to control how media content is displayed. Islandora Defaults provides two display modes for Media, one which renders the OpenSeadragon viewer and the other which renders the pdf.js viewer. These two display modes can be enabled by using "Display hints" in the node edit form, or you can configure Islandora to use a specific display mode for all media based on the file's Mime type. Both methods make use of [Contexts](context.md).
 
-To set it explicitly on the resource node's edit form, simply check the View mode you want to use for that node in the _Display hints_ field:
+To set the display mode on the resource node's edit form, select the display mode you want to use for that node in the _Display hints_ field:
 
 ![Display hints](../assets/resource_nodes_display_hints.png)
 
-The selected View mode will then be used when the resource node's page is rendered.
+Due to the associated Context configurations ("Open Seadragon" and "PDFjs Viewer") that are shipped with Islandora Defaults, the selected display mode will then be used when the resource node's page is rendered. 
 
 At a global level, there are a couple of ways to tell Drupal to use the PDFjs viewer to render the content of the media field whenever the media has a Mime type of `application/pdf`.
 
-The first way is to edit the "PDFjs" Context. By default, this Context tells Drupal to use the PDFjs viewer if the node has the term "PDFjs" (yes, that's a taxonomy term):
+The first way is to edit the "PDFjs Viewer" Context. By default, this Context tells Drupal to use the PDFjs viewer if the node has the term "PDFjs" (yes, that's a taxonomy term):
 
 ![Default PDFjs Context](../assets/resource_nodes_pdfjs_context_default.png)
 
@@ -126,13 +129,13 @@ If you add the Condition "Node has Media with Mime type" and configure it to use
 
 Context will use whichever Condition applies (as long as you don't check "Require all conditions"). That is, if the "PDFjs" display hint option in the node edit form is checked, *or* if the node's media has a Mime type of `application/pdf`, the media content will be rendered using the PDFjs viewer.
 
-The second way to use the media's Mime type to render its content with the PDFjs viewer is to create a separate Context that will detect the media's Mime type and use the configured View mode automatically. To do this, create a new Context. Add a "Node has Media with Mime type" condition and specify the Mime type, and then add a "Change View mode" Reaction that selects the desired view mode:
+The second way to use the media's Mime type to render its content with the PDFjs viewer is to create a separate Context that will detect the media's Mime type and use the configured display mode automatically. To do this, create a new Context. Add a "Node has Media with Mime type" condition and specify the Mime type, and then add a "Change View mode" Reaction that selects the desired display mode:
 
 ![Display hints](../assets/resource_nodes_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.
+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 display mode.
 
-The node-level and global approaches are not exclusive to one another. One Context can override another depending on the order of execution. Whichever Condition applies last between the node-level Condition (which in this case is the "Node has term" condition) the global Condition (which is "Node has Media with Mime type"), that one will override the other. An example of having the View mode specified in the node edit form intentionally override the View mode based on Mime type is to have media with the `image/jp2` mime-type configured to use to use the OpenSeadragon viewer, but to manually select the OpenSeadragon view mode for nodes with JPEG media (for example, a very large JPEG image of a map, where the OpenSeadragon's pan and zoom features would be useful).
+The node-level and global approaches are not exclusive to one another. One Context can override another depending on the order of execution. Whichever Condition applies last between the node-level Condition (which in this case is the "Node has term" condition) the global Condition (which is "Node has Media with Mime type"), that one will override the other. An example of having the display mode specified in the node edit form intentionally override the display mode based on Mime type is to have media with the `image/jp2` mime-type configured to use to use the OpenSeadragon viewer, but to manually select the OpenSeadragon display mode for nodes with JPEG media (for example, a very large JPEG image of a map, where the OpenSeadragon's pan and zoom features would be useful).
 
 ## Members
 

mkdocs.yml

@@ -134,6 +134,8 @@ nav:
               # conceptual
           - 'Extending Islandora': 'user-documentation/extending.md'
               # conceptual, repository managers/ developers
+          - 'Viewers': 'user-documentation/file_viewers.md'
+              # conceptual, understanding a very complex network of config. For repo managers/devs.
           - 'IIIF': 'user-documentation/iiif.md'
               # conceptual/ procedural, repository managers
               # add reference documentation about IIIF presentation API implementation