cocina_display 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13fa31ddb1ced6dce4cff9ba6c23273a717c517853724b0338834c8bc0584053
-  data.tar.gz: 393ea9fd0d3b923526eb2ef9165d1341bd0a59d4053e5cd0d3994cdc4b2e0ad2
+  metadata.gz: ddd051f7ce562501ccdbfb06831d81619742b1eeda24df081b79502473000dbc
+  data.tar.gz: 958bfe184a73058d469d6961284b0480544d7d26bad6e2a0c278cd968d143f1f
 SHA512:
-  metadata.gz: 269e719358ed43c1b76ff2f9a7dc63b2fca62f5fd3b1e9fd2a08b9fd978f3d052347a06424c5b06b54e64b39b32330cb77a6ee0ba840cae8b4b0f3ffeb578c10
-  data.tar.gz: 8227461a14e0a326652b49d32582ab7847b1946a7851e3b2b6f8123b5a5a21efbce2d4d86ff754c9ab65ac6bae315cdeb0fe4a9bbd159dd64199c0d522a061fd
+  metadata.gz: d0df0a44ee42f7ecb5163e8ce71d9f1564ff4f6b5ffbca529c41838393d81122d365e3dcae1e86f018131e48ccb40cca8552163d6655e14482191d860d838282
+  data.tar.gz: 78ac4f16998a9adf1bebd70f7d05a0f0bf1d6f5489f0ff4f5b76eb573c4f2c74c85bcf682a409459721de6e42b88bdaa7eeaef69cb1f046658629fd82be6fae7

data/README.md

@@ -88,6 +88,79 @@ cat spec/fixtures/bb112zx3193.json | janeway "$.description.contributor[?@.role[
 ]
 ```
 
+### Formatting for display
+
+Methods ending in `_display_data` usually return arrays of a class called `DisplayData`, which is designed for rendering into HTML by a consuming application. Each `DisplayData` object has a `label`, which serves as a heading under which its data is grouped. The `values` method returns an array of strings, which are the individual values to be displayed under that heading.
+
+For example, when displaying contributors, the label is usually determined by the role of the contributor, and the values are the display names of the contributors with that role:
+
+```ruby
+> rec.contributor_display_data.first.label
+=> "Former owner"
+> rec.contributor_display_data.first.values
+=> ["Hearst Magazines, Inc."]
+```
+
+The `#to_hash` helper method, which collapses all provided `DisplayData` into a single hash, can be used as a quick way to check the overall structure:
+
+```ruby
+> CocinaDisplay::DisplayData.to_hash(record.subject_display_data)
+=> {"Marque"=>["Bugatti"], "Model"=>["Bugatti T51A"], "Subject"=>["Bugatti automobile"]}
+```
+
+Note that usage of the `displayLabel` attribute in Cocina overrides the `label` that would ordinarily be used to group an item. If some items in a field have a `displayLabel` and others do not, each unique `displayLabel` will get its own `DisplayData` object, because those items will be grouped under a separate heading. If you call a method like `#subject_display_data`, it's always possible that you will get some items grouped under the default label "Subject" as well as others grouped under custom labels.
+
+#### Creating display data
+
+In some cases, you may wish to create `DisplayData` for some data that isn't immediately available via a `_display_data` method. Depending on what you have, there are several helper methods available to do this that will label and group the data for you.
+
+If the data you have is an array of objects that respond to `#label` and `#to_s`, you can use `DisplayData.from_objects`, which will automatically group the objects by their `label` and set the `values` to the result of calling `#to_s` on each object. Most of the objects returned by `CocinaRecord` methods, like `Contributor` and `Subject`, respond to these methods, and also handle nested `structuredValue`s in the Cocina when rendering to string. Handling of `parallelValue`s is also included for some object types like `Name` and `Title`.
+
+```ruby
+# This is actually equivalent to record.contributor_display_data!
+> CocinaDisplay::DisplayData.from_objects(record.contributors)
+```
+
+If the data you have is a simple array of strings, you can use `DisplayData.from_strings`. You need to provide a `label` to group the strings under:
+
+```ruby
+> CocinaDisplay::DisplayData.from_strings(["Bugatti", "Bugatti T51A", "Bugatti automobile"], label: "Subject")
+```
+
+If the data you have is a hash from parsed Cocina JSON, you can use `DisplayData.from_cocina`. This will respect any `displayLabel` attributes in the provided Cocina. You can optionally provide a `label` to use if the Cocina did not contain a `displayLabel` attribute:
+
+```ruby
+> cocina = { 'value' => 'Bugatti', 'displayLabel' => 'Marque' }
+# Will create a DisplayData with label "Marque" and value "Bugatti"
+> CocinaDisplay::DisplayData.from_cocina(cocina)
+# The same, but if the Cocina did not contain a displayLabel, it would use "Brand" instead
+> CocinaDisplay::DisplayData.from_cocina(cocina, label: 'Brand')
+```
+
+Note that `DisplayData.from_cocina` does not handle `structuredValue`s or `parallelValue`s in the provided Cocina. Because the correct handling is dependent on the type of data, you're usually better off selecting the appropriate objects from the `CocinaRecord` and using `DisplayData.from_objects` instead. To find out more about the various objects returned by `CocinaRecord` methods, see the [API Documentation](https://sul-dlss.github.io/cocina_display/).
+
+#### Custom formatting
+
+In some cases, you may need more control over the formatting. The `DisplayData#objects` method gives access to the underlying objects that were grouped under a particular `label`, allowing you to format them as needed.
+
+For contributors, the underlying objects are `Contributor` instances, which provide access to the associated `Name` and `Role` objects, as well as some other useful methods like `#forename` and `#organization?`:
+
+```ruby
+> record.contributor_display_data.first.label
+=> "Former owner"
+# All of the Contributors grouped under "Former owner"
+> former_owners = record.contributor_display_data.first.objects
+=> 
+[#<CocinaDisplay::Contributors::Contributor:0x0000000123ad6550
+...
+> former_owners.first.names.first.to_s
+=> "Hearst Magazines, Inc."
+> former_owners.first.organization?
+=> true
+```
+
+To review all the methods available on `Contributor`, see the [API Documentation](https://sul-dlss.github.io/cocina_display/CocinaDisplay/Contributors/Contributor.html).
+
 ### Searching for records
 
 Sometimes you need to determine if records exist "in the wild" that exhibit particular characteristics in the Cocina metadata, like the presence or absence of a field, or a specific value in a field. There is a template script in the `scripts/` directory that can be used to crawl all DRUIDs released to a particular target, like Searchworks, and examine each record.
@@ -104,13 +177,13 @@ find /stacks -name cocina.json | head -10000 |
 You may create a custom error handler by implementing the `Honeybadger` interface (or just using Honeybadger) and assigning it to the `CocinaRecord.notifier`.
 
 For example:
+
 ```ruby
 Rails.application.config.to_prepare do
   CocinaDisplay.notifier = Honeybadger
 end
 ```
 
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. This is a useful place to try out JSONPath expressions with `CocinaRecord#path`.

data/lib/cocina_display/contributors/affiliation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module CocinaDisplay
+  module Contributors
+    # An affiliation associated with a contributor.
+    class Affiliation
+      attr_reader :cocina
+
+      # Initialize an Affiliation from Cocina structured data.
+      # @param cocina [Hash]
+      def initialize(cocina)
+        @cocina = cocina
+      end
+
+      # String representation of the affiliation, using display name.
+      # @return [String, nil]
+      def to_s
+        display_name
+      end
+
+      # The name of the institution or organization.
+      # @return [String, nil]
+      # @example "Stanford University, Department of Special Collections"
+      def display_name
+        name_components.join(", ") if name_components.any?
+      end
+
+      # Does this Affiliation have a ROR ID?
+      # @return [Boolean]
+      def ror?
+        ror_identifier.present?
+      end
+
+      # ROR URI for the Affiliation, if present.
+      # @return [String, nil]
+      # @example https://ror.org/00f54p054
+      def ror
+        ror_identifier&.uri
+      end
+
+      # ROR ID for the Affiliation, if present.
+      # @return [String, nil]
+      # @example 00f54p054
+      def ror_id
+        ror_identifier&.identifier
+      end
+
+      # Identifiers associated with the Affiliation.
+      # @return [Array<CocinaDisplay::Identifier>]
+      def identifiers
+        @identifiers ||= Utils.flatten_nested_values(cocina)
+          .pluck("identifier").flatten.compact_blank.map { |id| CocinaDisplay::Identifier.new(id) }
+      end
+
+      # All components of the Affiliation name as an array of strings.
+      # @return [Array<String>]
+      # @example ["Stanford University", "Department of Special Collections"]
+      def name_components
+        @name_components ||= Utils.flatten_nested_values(cocina).pluck("value").compact_blank
+      end
+
+      # The first Identifier object that contains a ROR ID.
+      # @note This will usually be the most general ROR ID, if multiple.
+      # @return [CocinaDisplay::Identifier, nil]
+      def ror_identifier
+        identifiers.find { |id| id.type == "ROR" }
+      end
+    end
+  end
+end

data/lib/cocina_display/contributors/contributor.rb

@@ -24,12 +24,6 @@ module CocinaDisplay
         other.is_a?(Contributor) && other.cocina == cocina
       end
 
-      # Identifiers for the contributor.
-      # @return [Array<Identifier>]
-      def identifiers
-        Array(cocina["identifier"]).map { |id| Identifier.new(id) }
-      end
-
       # Is this contributor a human?
       # @return [Boolean]
       def person?
@@ -136,6 +130,46 @@ module CocinaDisplay
       def roles
         @roles ||= Array(cocina["role"]).map { |role| Role.new(role) }
       end
+
+      # Affiliation data for the contributor.
+      # @return [Array<CocinaDisplay::Contributors::Affiliation>]
+      def affiliations
+        @affiliations ||= Array(cocina["affiliation"]).map { |affiliation| Affiliation.new(affiliation) }
+      end
+
+      # Identifiers for the contributor.
+      # @return [Array<Identifier>]
+      def identifiers
+        @identifiers ||= Array(cocina["identifier"]).map { |id| Identifier.new(id) }
+      end
+
+      # Does this contributor have an ORCID?
+      # @return [Boolean]
+      def orcid?
+        orcid_identifier.present?
+      end
+
+      # ORCID URI for the contributor, if present.
+      # @return [String, nil]
+      # @example https://orcid.org/0000-0003-4168-7198
+      def orcid
+        orcid_identifier&.uri
+      end
+
+      # ORCID ID for the contributor, if present.
+      # @return [String, nil]
+      # @example 0000-0003-4168-7198
+      def orcid_id
+        orcid_identifier&.identifier
+      end
+
+      private
+
+      # The first Identifier object containing an ORCID.
+      # @return [CocinaDisplay::Identifier, nil]
+      def orcid_identifier
+        identifiers.find { |id| id.type == "ORCID" }
+      end
     end
   end
 end

data/lib/cocina_display/utils.rb

@@ -51,29 +51,29 @@ module CocinaDisplay
     end
 
     # Recursively remove empty values from a hash, including nested hashes and arrays.
-    # @param hash [Hash] The hash to process
-    # @param output [Hash] Used for recursion, should be empty on first call
-    # @return [Hash] The hash with empty values removed
+    # @param [Hash, String, NilClass] node The object to process
+    # @return [Hash, String] The hash with empty values removed, string if the node you pass in is a string
     # @example
     #  hash = { "name" => "", "age" => nil, "address => { "city" => "Anytown", "state" => [] } }
     #  #  Utils.remove_empty_values(hash)
     #  #=> { "address" => { "city" => "Anytown" } }
-    def self.deep_compact_blank(node, output = {})
+    def self.deep_compact_blank(node)
       return node unless node.is_a?(Hash)
 
-      node.each do |key, value|
-        if value.is_a?(Hash)
+      node.each_with_object({}) do |(key, value), output|
+        case value
+        when Hash
           nested = deep_compact_blank(value)
           output[key] = nested unless nested.empty?
-        elsif value.is_a?(Array)
-          compacted_array = value.map { |v| deep_compact_blank(v) }.reject(&:blank?)
+        when Array
+          compacted_array = value.map { |v| deep_compact_blank(v) }.compact_blank
           output[key] = compacted_array unless compacted_array.empty?
-        elsif value.present?
+        when TrueClass, FalseClass
           output[key] = value
+        else
+          output[key] = value if value.present?
         end
       end
-
-      output
     end
   end
 end

data/lib/cocina_display/version.rb

@@ -2,5 +2,5 @@
 
 # :nodoc:
 module CocinaDisplay
-  VERSION = "1.2.2" # :nodoc:
+  VERSION = "1.3.0" # :nodoc:
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocina_display
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Nick Budak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-26 00:00:00.000000000 Z
+date: 2025-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: janeway-jsonpath
@@ -246,6 +246,7 @@ files:
 - lib/cocina_display/concerns/subjects.rb
 - lib/cocina_display/concerns/titles.rb
 - lib/cocina_display/concerns/url_helpers.rb
+- lib/cocina_display/contributors/affiliation.rb
 - lib/cocina_display/contributors/contributor.rb
 - lib/cocina_display/contributors/name.rb
 - lib/cocina_display/contributors/role.rb