geoblacklight_admin 0.5.1 → 0.6.0

data/app/helpers/document_helper.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 # DocumentHelper
+#
+# This module provides helper methods for handling document-related
+# functionalities such as generating publication state badges, creating
+# localized links, and handling pagination links.
 module DocumentHelper
+  # Generates a badge for the publication state of a document.
+  #
+  # @param document [Object] the document object containing the publication state
+  # @return [String] HTML link with a span element representing the publication state
   def publication_state_badge(document)
     case document.publication_state
     when "draft"
@@ -19,15 +27,27 @@ module DocumentHelper
     end
   end
 
+  # Localizes a given link by parsing its URI and appending it to a base path.
+  #
+  # @param link [String] the link to be localized
+  # @return [String] the localized link
   def localize_link(link)
     uri = URI.parse(link)
     "/admin/documents?#{uri.query}"
   end
 
+  # Creates a sort link with a label and localized URL.
+  #
+  # @param link [Hash] a hash containing link attributes and self link
+  # @return [String] HTML link element for sorting
   def sort_link(link)
     link_to link["attributes"]["label"], localize_link(link["links"]["self"]), {class: "dropdown-item"}
   end
 
+  # Processes a link from an API response, determining whether to add or remove a facet.
+  #
+  # @param link [Hash] a hash containing links for adding or removing facets
+  # @return [Hash] a hash with action and link keys
   def link_from_api(link)
     # Append facet - Full URI returned
     uri = URI.parse(link["links"]["self"])
@@ -38,6 +58,10 @@ module DocumentHelper
     {action: "remove", link: "/admin/documents?#{uri.query}"}
   end
 
+  # Generates a link to the previous page in a paginated list.
+  #
+  # @param links [Hash] a hash containing pagination links
+  # @return [String] HTML link element for the previous page
   def previous_link(links)
     if links["prev"]
       link_to "Previous", localize_link(links["prev"]), {class: "btn btn-outline-primary btn-sm"}
@@ -46,6 +70,10 @@ module DocumentHelper
     end
   end
 
+  # Generates a link to the next page in a paginated list.
+  #
+  # @param links [Hash] a hash containing pagination links
+  # @return [String] HTML link element for the next page
   def next_link(links)
     if links["next"]
       link_to "Next", localize_link(links["next"]), {class: "btn btn-outline-primary btn-sm"}
@@ -54,10 +82,18 @@ module DocumentHelper
     end
   end
 
+  # Constructs a link to a document's page in the Blacklight catalog.
+  #
+  # @param document [Object] the document object
+  # @return [String] the URL to the document's Blacklight catalog page
   def blacklight_link(document)
     "#{BLACKLIGHT_URL}/catalog/#{document.friendlier_id}"
   end
 
+  # Determines if a document's thumbnail should be rendered.
+  #
+  # @param document [Object] the document object
+  # @return [Boolean] true if the thumbnail should be rendered, false otherwise
   def thumb_to_render?(document)
     document&.thumbnail&.file_url&.present? && document&.thumbnail&.file_derivatives&.present?
   end

data/app/helpers/geoblacklight_admin_helper.rb

@@ -1,13 +1,20 @@
 # frozen_string_literal: true
 
 # GeoblacklightAdminHelper
+#
+# This module provides helper methods for the GeoBlacklight admin interface.
+# It includes methods for handling JSON data, generating paths, formatting
+# flash messages, and more.
 module GeoblacklightAdminHelper
   # @TODO:
   # Cannot generate app if uncommented...
   # Uncomment after app is generated to fix view errors
   include ::Pagy::Frontend if defined?(Pagy)
 
-  # jbuilder helper
+  # Removes blank values from JSON data.
+  #
+  # @param value [String, Array] the value to check for presence
+  # @return [String, Array, nil] the original value if present, otherwise nil
   def no_json_blanks(value)
     case value
     when String
@@ -17,17 +24,21 @@ module GeoblacklightAdminHelper
     end
   end
 
-  # qa (questioning_authoriry) gem oddly gives us no route helpers, so
-  # let's make one ourselves, for it's current mount point, we can change
-  # it if needed but at least it's DRY.
+  # Generates a search path for the QA (questioning_authority) gem.
+  #
+  # @param vocab [String] the vocabulary to search
+  # @param subauthority [String, nil] the subauthority to search
+  # @return [String] the generated search path
   def qa_search_vocab_path(vocab, subauthority = nil)
     path = "/authorities/search/#{CGI.escape vocab}"
-
     path += "/#{CGI.escape subauthority}" if subauthority
-
     path
   end
 
+  # Maps flash message levels to CSS classes.
+  #
+  # @param level [String] the flash message level
+  # @return [String] the corresponding CSS class
   def flash_class(level)
     alerts = {
       "notice" => "alert alert-info",
@@ -38,6 +49,9 @@ module GeoblacklightAdminHelper
     alerts[level]
   end
 
+  # Provides a mapping of institution codes to institution names.
+  #
+  # @return [Hash] a hash mapping institution codes to names
   def b1g_institution_codes
     {
       "01" => "Indiana University",
@@ -58,11 +72,17 @@ module GeoblacklightAdminHelper
     }
   end
 
+  # Generates an HTML badge for bookmarks.
+  #
+  # @return [String] the HTML string for the bookmarks badge
   def bookmarks_badge
     bookmarks_classes = ["badge", "badge-dark"]
     "<span class='#{bookmarks_classes.join(" ")}' id='bookmarks-count'>#{current_user.bookmarks.size}</span>"
   end
 
+  # Generates an HTML badge for notifications.
+  #
+  # @return [String] the HTML string for the notifications badge
   def notifications_badge
     notifications_classes = ["badge"]
     notifications_classes << "badge-dark" if current_user.notifications.unread.empty?
@@ -70,7 +90,10 @@ module GeoblacklightAdminHelper
     "<span class='#{notifications_classes.join(" ")}' id='notification-count'>#{current_user.notifications.unread.size}</span>"
   end
 
-  # From Blacklight::HiddenSearchStateComponent
+  # Converts parameters into hidden form fields.
+  #
+  # @param params [Hash] the parameters to convert
+  # @return [String] the HTML string of hidden fields
   def params_as_hidden_fields(params)
     hidden_fields = []
     flatten_hash(params).each do |name, value|
@@ -83,6 +106,12 @@ module GeoblacklightAdminHelper
     safe_join(hidden_fields, "\n")
   end
 
+  # Flattens a nested hash into a single-level hash with keys representing the
+  # nested structure.
+  #
+  # @param hash [Hash] the hash to flatten
+  # @param ancestor_names [Array] the ancestor keys for nested hashes
+  # @return [Hash] the flattened hash
   def flatten_hash(hash, ancestor_names = [])
     flat_hash = {}
     hash.each do |k, v|
@@ -100,6 +129,10 @@ module GeoblacklightAdminHelper
     flat_hash
   end
 
+  # Generates a key for a flattened hash from an array of names.
+  #
+  # @param names [Array] the array of names
+  # @return [String] the generated key
   def flat_hash_key(names)
     names = Array.new(names)
     name = names.shift.to_s.dup
@@ -109,6 +142,10 @@ module GeoblacklightAdminHelper
     name
   end
 
+  # Maps a character to a CSS class for diff highlighting.
+  #
+  # @param char [String] the character representing a diff operation
+  # @return [String] the corresponding CSS class
   def diff_class(char)
     case char
     when "~"
@@ -122,6 +159,10 @@ module GeoblacklightAdminHelper
     end
   end
 
+  # Generates a link to the admin import page for a given import.
+  #
+  # @param import [Object] the import object
+  # @return [String] the HTML link to the admin import page
   def link_to_admin_import(import)
     path = admin_documents_path(
       {
@@ -132,6 +173,12 @@ module GeoblacklightAdminHelper
     link_to import.name, path
   end
 
+  # Generates a link to the GeoBlacklight import page with optional state.
+  #
+  # @param label [String] the link label
+  # @param import [Object] the import object
+  # @param state [Boolean] the publication state
+  # @return [String] the HTML link to the GeoBlacklight import page
   def link_to_gbl_import(label, import, state = false)
     path = if state
       blacklight_path(
@@ -152,7 +199,40 @@ module GeoblacklightAdminHelper
     link_to(label, path)
   end
 
+  # Generates options for asset DCT references.
+  #
+  # @return [String] the escaped JavaScript string of options
   def assets_dct_references_options
-    escape_javascript(options_for_select(I18n.t("activemodel.enum_values.document/reference.category").invert.sort.insert(0, ["Choose Reference Type", nil]))).to_s
+    escape_javascript(options_for_select(I18n.t("activemodel.asset_enum_values.document/reference.category").invert.sort.insert(0, ["Choose Reference Type", nil]))).to_s
+  end
+
+  # Determines if a document's thumbnail should be rendered.
+  #
+  # @param document [Object] the document object
+  # @return [Boolean] true if the thumbnail should be rendered, false otherwise
+  def thumb_to_render?(document)
+    if document&.thumbnail&.file_url&.present? && document&.thumbnail&.file_derivatives&.present?
+      true
+    elsif document&.document_assets&.any?
+      document.document_assets.any? do |asset|
+        asset.file_derivatives&.key?(:thumb_standard_2X)
+      end
+    else
+      false
+    end
+  end
+
+  # Returns the URL of the thumbnail to render for a document.
+  #
+  # @param document [Object] the document object
+  # @return [String] the URL of the thumbnail to render
+  def thumbnail_to_render(document)
+    if document&.thumbnail&.file_url&.present? && document&.thumbnail&.file_derivatives&.present?
+      document.thumbnail.file_url(:thumb_standard_2X)
+    elsif document&.document_assets&.any?
+      document.document_assets.find do |asset|
+        asset.file_derivatives&.key?(:thumb_standard_2X)
+      end&.file_url(:thumb_standard_2X)
+    end
   end
 end

data/app/helpers/mappings_helper.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 # MappingsHelper
+#
+# This module provides helper methods for handling mappings in the application.
+# It includes methods to generate attribute collections and provide mapping
+# and delimiter suggestions based on import configurations.
 module MappingsHelper
+  # Returns a collection of attributes that can be used for mapping.
+  #
+  # The collection is generated from importable elements, sorted, and includes
+  # additional options for an empty string and "Discard".
+  #
+  # @return [Array<String>] a sorted array of attribute names with additional options.
   def attribute_collection
     attrs = Element.importable.map(&:solr_field).sort
     attrs.prepend("")
@@ -9,6 +19,14 @@ module MappingsHelper
     attrs
   end
 
+  # Provides a mapping suggestion for a given header based on the import configuration.
+  #
+  # Checks if the header is included in the import's mapping configuration and returns
+  # the destination if available.
+  #
+  # @param import [Object] the import object containing mapping configurations.
+  # @param header [String] the header for which the mapping suggestion is needed.
+  # @return [String, false] the destination mapping if available, otherwise false.
   def mapping_suggestion(import, header)
     if import.mapping_configuration.include?(header.to_sym)
       import.mapping_configuration[header.to_sym][:destination]
@@ -17,6 +35,14 @@ module MappingsHelper
     end
   end
 
+  # Provides a delimiter suggestion for a given header based on the import configuration.
+  #
+  # Checks if the header is included in the import's mapping configuration and returns
+  # the delimiter if available.
+  #
+  # @param import [Object] the import object containing mapping configurations.
+  # @param header [String] the header for which the delimiter suggestion is needed.
+  # @return [String, false] the delimiter if available, otherwise false.
   def delimiter_suggestion(import, header)
     if import.mapping_configuration.include?(header.to_sym)
       import.mapping_configuration[header.to_sym][:delimited]

data/app/indexers/document_indexer.rb

@@ -1,6 +1,24 @@
 # frozen_string_literal: true
 
 # Solr indexing for our document class. Still a work in progress.
+#
+# The DocumentIndexer class is responsible for configuring how documents
+# are indexed into Solr. It uses the Kithe::Indexer framework to map
+# document attributes to Solr fields.
+#
+# The configuration block defines various fields that are indexed, including
+# fields specific to GeoBlacklight and custom fields defined via the Element model.
+#
+# Fields:
+# - model_pk_ssi: The primary key of the model, extracted from the object's ID.
+# - gbl_mdVersion_s: A static version string for GeoBlacklight.
+# - gbl_mdModified_dt: The modification date of the metadata.
+# - date_created_dtsi: The creation date of the record, in UTC ISO8601 format.
+# - date_modified_dtsi: The last modification date of the record, in UTC ISO8601 format.
+# - b1g_geom_import_id_ssi: The import ID for GeoBlacklight administration.
+#
+# If the "elements" table exists, additional fields are indexed based on
+# the Element model's configuration.
 class DocumentIndexer < Kithe::Indexer
   configure do
     # Kithe
@@ -12,8 +30,10 @@ class DocumentIndexer < Kithe::Indexer
     # to_field 'geomg_id_s', obj_extract('friendlier_id') # the actual db pk, a UUID
 
     # Define `to_field`(s) via Element
-    Element.indexable.each do |elm|
-      to_field elm.solr_field, obj_extract(elm.index_value)
+    if ActiveRecord::Base.connection.table_exists?("elements")
+      Element.indexable.each do |elm|
+        to_field elm.solr_field, obj_extract(elm.index_value)
+      end
     end
 
     to_field "gbl_mdModified_dt", obj_extract("gbl_mdModified_dt")

data/app/javascript/channels/consumer.js

@@ -0,0 +1,6 @@
+// Action Cable provides the framework to deal with WebSockets in Rails.
+// You can generate new channels where WebSocket features live using the `bin/rails generate channel` command.
+
+import { createConsumer } from "@rails/actioncable"
+
+export default createConsumer()

data/app/javascript/channels/export_channel.js

@@ -0,0 +1,30 @@
+import consumer from "./consumer"
+
+consumer.subscriptions.create({ channel: "ExportChannel" }, {
+  connected() {
+    // Called when the subscription is ready for use on the server
+    console.log("GBL Admin - ExportChannel connected");
+  },
+
+  disconnected() {
+    // Called when the subscription has been terminated by the server
+    console.log("GBL Admin - ExportChannel disconnected");
+  },
+
+  received(data) {
+    console.log('GBL Admin - ExportChannel received!');
+    console.log(data);
+
+    if (data['progress']) {
+      console.log(data['progress']);
+    }
+
+    if (data['actions']) {
+      for (let index = 0; index < data.actions.length; ++index) {
+        var fnstring = data.actions[index].method;
+        var fn = window["GBLADMIN"][fnstring];
+        if (typeof fn === "function") fn(data.actions[index].payload);
+      }
+    }
+  }
+});

data/app/javascript/channels/index.js

@@ -0,0 +1,3 @@
+export { default as consumer } from './consumer';
+export { default as exportChannel } from './export_channel';
+export { default as index } from './index';

data/app/javascript/controllers/results_controller.js

@@ -12,6 +12,7 @@ import { Controller } from "stimulus"
 export default class extends Controller {
 
   connect() {
+    console.log("GBL Admin - ResultsController connected");
   }
 
   checkedState(checked, selector='input[type=checkbox]') {
@@ -228,6 +229,7 @@ export default class extends Controller {
   }
 
   exportCsvDocumentDownloads() {
+    console.log('Export - CsvDocumentDownloads')
     var scope = this.checkSelectionScope();
     var el = document.querySelector('#result-selected-options');
     if(scope === 'pageset') {
@@ -238,6 +240,7 @@ export default class extends Controller {
   }
 
   exportCsvDocumentAccessLinks() {
+    console.log('Export - CsvDocumentAccessLinks')
     var scope = this.checkSelectionScope();
     var el = document.querySelector('#result-selected-options');
     if(scope === 'pageset') {
@@ -247,6 +250,17 @@ export default class extends Controller {
     }
   }
 
+  exportCsvDocumentDistributions() {
+    console.log('Export - CsvDocumentDistributions')
+    var scope = this.checkSelectionScope();
+    var el = document.querySelector('#result-selected-options');
+    if(scope === 'pageset') {
+      window.location = el.dataset.pageset + "&format=csv_document_distributions"
+    } else {
+      window.location = el.dataset.resultset + "&format=csv_document_distributions"
+    }
+  }
+
   bulkAction() {
     var scope = this.checkSelectionScope();
     var el = document.querySelector('#result-selected-options');

data/app/javascript/index.js

@@ -1,8 +1,14 @@
 console.log('Vite ⚡️ Rails - GBL Admin')
 
-// Stimulus
+// Import Stimulus and controllers
 import { Application } from '@hotwired/stimulus'
 import ResultsController from "./controllers/results_controller"
 
+// Initialize Stimulus
 window.Stimulus = Application.start()
-Stimulus.register("results", ResultsController)
+
+// Register controllers
+Stimulus.register("results", ResultsController)
+
+// Import channels
+import '../channels';

data/app/jobs/export_job.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "csv"
+require "zip"
 
 # ExportJob
 class ExportJob < ApplicationJob
@@ -23,27 +24,53 @@ class ExportJob < ApplicationJob
     logger.debug("Document Ids: #{document_ids}")
 
     # Send progress
-    file_content = export_service.call(document_ids)
+    file_content_documents = export_service.call(document_ids)
+    file_content_document_distributions = ExportCsvDocumentDistributionsService.call(document_ids)
 
-    # Write into tempfile
-    @tempfile = Tempfile.new(["export-#{Time.zone.today}", ".csv"]).tap do |file|
+    # Write Documents into tempfile
+    @tempfile_documents = Tempfile.new(["documents-#{Time.zone.today}", ".csv"]).tap do |file|
       CSV.open(file, "wb") do |csv|
-        file_content.each do |row|
+        file_content_documents.each do |row|
           csv << row
         end
       end
+      logger.debug("Tempfile Documents Path: #{file.path}")
+      logger.debug("Tempfile Documents Size: #{File.size(file.path)} bytes")
     end
 
+    # Write DocumentDistributions into tempfile
+    @tempfile_document_distributions = Tempfile.new(["document-distributions-#{Time.zone.today}", ".csv"]).tap do |file|
+      CSV.open(file, "wb") do |csv|
+        file_content_document_distributions.each do |row|
+          csv << row
+        end
+      end
+      logger.debug("Tempfile Document Distributions Path: #{file.path}")
+      logger.debug("Tempfile Document Distributions Size: #{File.size(file.path)} bytes")
+    end
+
+    # Create a zip file containing both tempfiles
+    zipfile_name = "export-#{Time.zone.today}.zip"
+    tmp_dir = Rails.root.join("tmp")
+    @tempfile_zip = Tempfile.new([zipfile_name, ".zip"], tmp_dir)
+
+    Zip::File.open(@tempfile_zip.path, Zip::File::CREATE) do |zipfile|
+      zipfile.add("documents.csv", @tempfile_documents.path)
+      zipfile.add("document-distributions.csv", @tempfile_document_distributions.path)
+    end
+    logger.debug("Zipfile Path: #{@tempfile_zip.path}")
+    logger.debug("Zipfile Size: #{File.size(@tempfile_zip.path)} bytes")
+
     # Create notification
     # Message: "Download Type|Row Count|Button Label"
-    notification = ExportNotification.with(message: "CSV (#{export_service.short_name})|#{ActionController::Base.helpers.number_with_delimiter(file_content.size - 1)} rows|CSV")
+    notification = ExportNotification.with(message: "ZIP (#{export_service.short_name})|#{ActionController::Base.helpers.number_with_delimiter(file_content_documents.size - 1)} rows|ZIP")
 
     # Deliver notification
     notification.deliver(current_user)
 
-    # Attach CSV file (can only attach after persisted)
-    notification.record.file.attach(io: @tempfile, filename: "geomg-export-#{Time.zone.today}.csv",
-      content_type: "text/csv")
+    # Attach ZIP file (can only attach after persisted)
+    notification.record.file.attach(io: File.open(@tempfile_zip), filename: zipfile_name,
+      content_type: "application/zip")
 
     # Update UI
     ActionCable.server.broadcast("export_channel", {

data/app/jobs/geoblacklight_admin/delete_thumbnail_job.rb

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
+##
+# Module for GeoblacklightAdmin related jobs.
 module GeoblacklightAdmin
+  ##
+  # A job to delete the thumbnail associated with a Solr document.
+  #
+  # This job is enqueued with a priority queue and can optionally handle
+  # a bad document ID to transition its state.
   class DeleteThumbnailJob < ApplicationJob
+    ##
+    # Determines the queue to use based on the last argument.
     queue_as do
       arguments.last
     end
 
+    ##
+    # Performs the job to delete a thumbnail.
+    #
+    # @param solr_document_id [String] the ID of the Solr document
+    # @param bad_id [String, nil] optional ID of a bad document to transition
+    # @param queue [Symbol] the queue to use, defaults to :priority
+    #
+    # If the document has a thumbnail, it will be destroyed.
+    # If a bad_id is provided, it will transition the state of the
+    # BulkActionDocument to :success.
     def perform(solr_document_id, bad_id = nil, queue = :priority)
       document = Document.find_by_friendlier_id(solr_document_id)
       if document.thumbnail.present?

data/app/jobs/geoblacklight_admin/remove_parent_dct_references_uri_job.rb

@@ -1,9 +1,25 @@
 # frozen_string_literal: true
 
+##
+# Module for GeoblacklightAdmin jobs.
 module GeoblacklightAdmin
+  ##
+  # Job to remove a specific DCT references URI from the parent asset.
+  #
+  # This job is queued with a priority level and is responsible for
+  # removing a DCT references URI from the parent of a given asset.
   class RemoveParentDctReferencesUriJob < ApplicationJob
     queue_as :priority
 
+    ##
+    # Performs the job of removing the DCT references URI from the parent asset.
+    #
+    # This method checks if the asset has a `dct_references_uri_key` present.
+    # If present, it deletes the URI from the parent's `dct_references_s` array
+    # if it matches the asset's full file URL, and then saves the parent asset.
+    #
+    # @param asset [Object] The asset whose parent's DCT references URI is to be removed.
+    # @raise [StandardError] Logs an error if an exception occurs during the process.
     def perform(asset)
       if asset.dct_references_uri_key.present?
         asset.parent.dct_references_s.delete_if { |i| i.value == asset.full_file_url }

data/app/jobs/geoblacklight_admin/set_parent_dct_references_uri_job.rb

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
+##
+# Module for GeoblacklightAdmin jobs.
 module GeoblacklightAdmin
+  ##
+  # Job to set the parent DCT references URI for a given asset.
+  #
+  # This job is responsible for creating a new reference for the asset's
+  # DCT references URI key and appending it to the parent asset's
+  # `dct_references_s` array. It then saves the parent asset.
+  #
+  # If an error occurs during the process, it logs the error message.
   class SetParentDctReferencesUriJob < ApplicationJob
+    # Sets the queue for this job to :priority
     queue_as :priority
 
+    ##
+    # Performs the job to set the parent DCT references URI.
+    #
+    # @param asset [Object] The asset for which the DCT references URI is to be set.
+    #
+    # @return [void]
     def perform(asset)
       if asset.dct_references_uri_key.present?
         reference = Document::Reference.new

data/app/jobs/geoblacklight_admin/store_image_job.rb

@@ -1,11 +1,33 @@
 # frozen_string_literal: true
 
+##
+# Module for GeoblacklightAdmin jobs.
 module GeoblacklightAdmin
+  ##
+  # StoreImageJob is responsible for handling the storage of images
+  # associated with a Solr document. It manages the lifecycle of the
+  # image storage process, including state transitions and error handling.
   class StoreImageJob < ApplicationJob
+    ##
+    # Sets the queue for the job based on the last argument provided.
     queue_as do
       arguments.last
     end
 
+    ##
+    # Performs the job to store an image for a given Solr document.
+    #
+    # @param solr_document_id [String] the ID of the Solr document
+    # @param bad_id [String, nil] optional ID for a BulkActionDocument
+    # @param queue [Symbol] the queue to use for the job, defaults to :default
+    #
+    # This method:
+    # - Finds the document by its friendlier ID.
+    # - Deletes any existing thumbnail.
+    # - Transitions the document's thumbnail state to 'queued'.
+    # - Waits for a random period to ensure polite crawling.
+    # - Stores the image using the ImageService.
+    # - Transitions the BulkActionDocument state to 'success' if a bad_id is provided.
     def perform(solr_document_id, bad_id = nil, queue = :default)
       # Find the document
       document = Document.find_by_friendlier_id(solr_document_id)