geoblacklight_admin 0.5.1 → 0.6.0

data/app/controllers/admin/elements_controller.rb

@@ -1,29 +1,40 @@
 # frozen_string_literal: true
 
 # Admin::ElementsController
+# This controller manages the CRUD operations for elements within the admin namespace.
+# It includes actions for listing, showing, creating, updating, and deleting elements.
+# Additionally, it provides a custom action for sorting elements.
 module Admin
   class ElementsController < Admin::AdminController
     before_action :set_element, only: %i[show edit update destroy]
 
     # GET /elements or /elements.json
+    # Lists all elements, ordered by position in ascending order.
+    # Uses pagination to limit the number of elements displayed per page.
     def index
       @pagy, @elements = pagy(Element.all.order(position: :asc), items: 100)
     end
 
     # GET /elements/1 or /elements/1.json
+    # Displays a specific element.
     def show
     end
 
     # GET /elements/new
+    # Initializes a new element object.
     def new
       @element = Element.new
     end
 
     # GET /elements/1/edit
+    # Prepares an element for editing.
     def edit
     end
 
     # POST /elements or /elements.json
+    # Creates a new element with the provided parameters.
+    # If successful, redirects to the element's show page with a success notice.
+    # If unsuccessful, re-renders the new element form with error messages.
     def create
       @element = Element.new(element_params)
 
@@ -39,6 +50,9 @@ module Admin
     end
 
     # PATCH/PUT /elements/1 or /elements/1.json
+    # Updates an existing element with the provided parameters.
+    # If successful, redirects to the element's show page with a success notice.
+    # If unsuccessful, re-renders the edit form with error messages.
     def update
       respond_to do |format|
         if @element.update(element_params)
@@ -52,6 +66,8 @@ module Admin
     end
 
     # DELETE /elements/1 or /elements/1.json
+    # Deletes a specific element.
+    # Redirects to the elements index page with a success notice.
     def destroy
       @element.destroy
 
@@ -61,6 +77,9 @@ module Admin
       end
     end
 
+    # POST /elements/sort
+    # Sorts elements based on the provided list of IDs.
+    # Renders an empty response body.
     def sort
       Element.sort_elements(params[:id_list])
       render body: nil
@@ -69,6 +88,8 @@ module Admin
     private
 
     # Use callbacks to share common setup or constraints between actions.
+    # Finds an element by ID and sets it as an instance variable.
+    # Redirects to the elements index page with an alert if the element is not found.
     def set_element
       @element = Element.find(params[:id])
     rescue ActiveRecord::RecordNotFound
@@ -76,6 +97,7 @@ module Admin
     end
 
     # Only allow a list of trusted parameters through.
+    # Permits specific parameters for element creation and updates.
     def element_params
       params.require(:element).permit(:label, :solr_field, :field_definition, :field_type, :required, :repeatable,
         :formable, :placeholder_text, :data_entry_hint, :test_fixture_example, :controlled_vocabulary, :js_behaviors, :html_attributes, :display_only_on_persisted, :importable, :import_deliminated, :import_transformation_method, :exportable, :export_transformation_method, :indexable, :index_transformation_method, :validation_method, :position)

data/app/controllers/admin/form_elements_controller.rb

@@ -1,29 +1,54 @@
 # frozen_string_literal: true
 
 # Admin::FormElementsController
+#
+# This controller manages the CRUD operations for form elements within the admin namespace.
+# It provides actions to list, show, create, update, and delete form elements.
+#
+# Actions:
+# - index: Lists all form elements.
+# - show: Displays a specific form element.
+# - new: Renders a form for creating a new form element.
+# - edit: Renders a form for editing an existing form element.
+# - create: Creates a new form element.
+# - update: Updates an existing form element.
+# - destroy: Deletes a form element.
+# - sort: Sorts form elements based on a provided list of IDs.
+#
+# Before Actions:
+# - set_form_element: Sets the form element for show, edit, update, and destroy actions.
+#
+# Private Methods:
+# - set_form_element: Finds and sets the form element by ID, redirects if not found.
+# - form_element_params: Permits only trusted parameters for form elements.
 module Admin
   class FormElementsController < Admin::AdminController
     before_action :set_form_element, only: %i[show edit update destroy]
 
     # GET /form_elements or /form_elements.json
+    # Lists all form elements.
     def index
       @form_elements = FormElement.all
     end
 
     # GET /form_elements/1 or /form_elements/1.json
+    # Displays a specific form element.
     def show
     end
 
     # GET /form_elements/new
+    # Renders a form for creating a new form element.
     def new
       @form_element = FormElement.new
     end
 
     # GET /form_elements/1/edit
+    # Renders a form for editing an existing form element.
     def edit
     end
 
     # POST /form_elements or /form_elements.json
+    # Creates a new form element.
     def create
       @form_element = FormElement.new(form_element_params)
 
@@ -39,6 +64,7 @@ module Admin
     end
 
     # PATCH/PUT /form_elements/1 or /form_elements/1.json
+    # Updates an existing form element.
     def update
       respond_to do |format|
         if @form_element.update(form_element_params)
@@ -52,6 +78,7 @@ module Admin
     end
 
     # DELETE /form_elements/1 or /form_elements/1.json
+    # Deletes a form element.
     def destroy
       @form_element.destroy
 
@@ -61,6 +88,8 @@ module Admin
       end
     end
 
+    # POST /form_elements/sort
+    # Sorts form elements based on a provided list of IDs.
     def sort
       FormElement.sort_elements(params[:id_list])
       render body: nil
@@ -69,6 +98,7 @@ module Admin
     private
 
     # Use callbacks to share common setup or constraints between actions.
+    # Finds and sets the form element by ID, redirects if not found.
     def set_form_element
       @form_element = FormElement.find(params[:id])
     rescue ActiveRecord::RecordNotFound
@@ -76,6 +106,7 @@ module Admin
     end
 
     # Only allow a list of trusted parameters through.
+    # Permits only trusted parameters for form elements.
     def form_element_params
       params.require(:form_element).permit(:type, :label, :element_solr_field)
     end

data/app/controllers/admin/import_documents_controller.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
 # Admin::ImportDocumentsController
+#
+# This controller handles the import documents within the admin namespace.
+# It inherits from Admin::AdminController and provides actions related to
+# import documents.
 module Admin
   class ImportDocumentsController < Admin::AdminController
+    # Before action callback to set the import document for the show action.
     before_action :set_import_document, only: %i[show]
 
+    # GET /admin/import_documents/:id
+    #
+    # Displays a specific import document.
     def show
     end
 
     private
 
-    # Use callbacks to share common setup or constraints between actions.
+    # Sets the import document based on the ID provided in the parameters.
+    #
+    # @return [ImportDocument] the import document found by ID
     def set_import_document
       @import_document = ImportDocument.find(params[:id])
     end

data/app/controllers/admin/imports_controller.rb

@@ -1,34 +1,60 @@
 # frozen_string_literal: true
 
 # Admin::ImportsController
+#
+# This controller handles the CRUD operations for Import objects within the admin namespace.
+# It provides actions to list, show, create, update, and delete imports, as well as run an import.
+#
+# Before Actions:
+# - set_import: Sets the @import instance variable for actions that require an import ID.
+#
+# Actions:
+# - index: Lists all imports with pagination.
+# - show: Displays a specific import and its associated documents, with pagination for success and failed states.
+# - new: Initializes a new Import object.
+# - edit: Prepares an existing Import object for editing.
+# - create: Creates a new Import object and redirects to import mappings if successful.
+# - update: Updates an existing Import object and redirects to the import if successful.
+# - destroy: Deletes an Import object and redirects to the imports list.
+# - run: Executes the import process and redirects to the import show page.
+#
+# Private Methods:
+# - set_import: Finds and sets the import based on the provided ID.
+# - permittable_params: Returns an array of permitted parameters for import.
+# - import_params: Permits parameters for creating or updating an import, including nested attributes.
 module Admin
   class ImportsController < Admin::AdminController
     before_action :set_import, only: %i[show edit update destroy run]
 
     # GET /imports
     # GET /imports.json
+    # Lists all imports with pagination.
     def index
       @pagy, @imports = pagy(Import.all.order("created_at DESC"), items: 20)
     end
 
     # GET /imports/1
     # GET /imports/1.json
+    # Displays a specific import and its associated documents, with pagination for success and failed states.
     def show
       @pagy_failed, @import_failed_documents = pagy(@import.import_documents.not_in_state(:success), items: 50, page_param: :failed_page)
       @pagy_success, @import_success_documents = pagy(@import.import_documents.in_state(:success), items: 50, page_param: :success_page)
     end
 
     # GET /imports/new
+    # Initializes a new Import object.
     def new
       @import = Import.new
     end
 
     # GET /imports/1/edit
+    # Prepares an existing Import object for editing.
     def edit
     end
 
     # POST /imports
     # POST /imports.json
+    # Creates a new Import object and redirects to import mappings if successful.
     def create
       @import = Import.new(import_params)
 
@@ -48,6 +74,7 @@ module Admin
 
     # PATCH/PUT /imports/1
     # PATCH/PUT /imports/1.json
+    # Updates an existing Import object and redirects to the import if successful.
     def update
       respond_to do |format|
         if @import.update(import_params)
@@ -62,6 +89,7 @@ module Admin
 
     # DELETE /imports/1
     # DELETE /imports/1.json
+    # Deletes an Import object and redirects to the imports list.
     def destroy
       @import.destroy
       respond_to do |format|
@@ -70,6 +98,7 @@ module Admin
       end
     end
 
+    # Runs the import process and redirects to the import show page.
     def run
       @import.run!
       redirect_to admin_import_url(@import), notice: "Import is running. Check back soon for results."
@@ -78,17 +107,18 @@ module Admin
     private
 
     # Use callbacks to share common setup or constraints between actions.
+    # Finds and sets the import based on the provided ID.
     def set_import
       @import = Import.find(params[:id])
     end
 
-    # Never trust parameters from the scary internet, only allow the white list through.
-
+    # Returns an array of permitted parameters for import.
     def permittable_params
       %i[type name filename source description row_count encoding content_type extension validity validation_result
         csv_file run]
     end
 
+    # Permits parameters for creating or updating an import, including nested attributes.
     def import_params
       # Handle STI key
       key = (params.keys & %w[import import_btaa import_btaa_aardvark import_gblv1])[0]

data/app/controllers/admin/mappings_controller.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 # Admin::MappingsController
+# This controller manages the CRUD operations for Mappings within an Import context.
+# It provides actions to list, show, create, update, and destroy mappings.
 module Admin
   class MappingsController < Admin::AdminController
     before_action :set_import
@@ -8,6 +10,7 @@ module Admin
 
     # GET /import/:id/mappings
     # GET /import/:id/mappings.json
+    # Lists all mappings for a specific import. If no mappings exist, it initializes a new one.
     def index
       @mappings = Mapping.where(import_id: @import)
 
@@ -17,21 +20,26 @@ module Admin
 
     # GET /mappings/1
     # GET /mappings/1.json
+    # Shows a specific mapping.
     def show
       @import = Import.find(params[:import_id])
     end
 
     # GET /mappings/new
+    # Initializes a new mapping object.
     def new
       @mapping = Mapping.new
     end
 
     # GET /mappings/1/edit
+    # Prepares a mapping for editing.
     def edit
     end
 
     # POST /mappings
     # POST /mappings.json
+    # Creates a new mapping. If successful, redirects to the mapping's show page.
+    # Otherwise, re-renders the new form.
     def create
       @mapping = Mapping.new(mapping_params)
 
@@ -50,6 +58,8 @@ module Admin
 
     # PATCH/PUT /mappings/1
     # PATCH/PUT /mappings/1.json
+    # Updates an existing mapping. If successful, redirects to the mappings index.
+    # Otherwise, re-renders the edit form.
     def update
       respond_to do |format|
         if @mapping.update(mapping_params)
@@ -64,6 +74,7 @@ module Admin
 
     # DELETE /mappings/1
     # DELETE /mappings/1.json
+    # Deletes a mapping and redirects to the mappings index.
     def destroy
       @mapping.destroy
       respond_to do |format|
@@ -75,15 +86,19 @@ module Admin
     private
 
     # Use callbacks to share common setup or constraints between actions.
+
+    # Sets the import based on the import_id parameter.
     def set_import
       @import = Import.find(params[:import_id])
     end
 
+    # Sets the mapping based on the id parameter.
     def set_mapping
       @mapping = Mapping.find(params[:id])
     end
 
     # Only allow a list of trusted parameters through.
+    # Permits the parameters required for creating or updating a mapping.
     def mapping_params
       params.require(:mapping).permit(
         :source_header,

data/app/controllers/admin/notifications_controller.rb

@@ -1,14 +1,28 @@
 # frozen_string_literal: true
 
 # Admin::NotificationsController
+#
+# This controller manages the notifications for the admin panel. It provides
+# actions to list, update, destroy, and batch update notifications.
 module Admin
   class NotificationsController < Admin::AdminController
     before_action :set_notification, only: %i[update destroy]
 
+    # GET /admin/notifications
+    #
+    # Lists all notifications for the current user, paginated.
+    #
+    # @return [void]
     def index
       @pagy, @notifications = pagy(current_user.notifications.order(created_at: :desc), items: 20)
     end
 
+    # PATCH/PUT /admin/notifications/:id
+    #
+    # Updates the read status of a notification.
+    #
+    # @param [String] read The read status, "0" for unread, "1" for read.
+    # @return [void]
     def update
       case params[:read]
       when "0"
@@ -25,6 +39,11 @@ module Admin
       end
     end
 
+    # DELETE /admin/notifications/:id
+    #
+    # Destroys a notification and purges its associated file.
+    #
+    # @return [void]
     def destroy
       @notification.file.purge
       @notification.destroy
@@ -34,6 +53,11 @@ module Admin
       end
     end
 
+    # POST /admin/notifications/batch
+    #
+    # Marks all notifications as read.
+    #
+    # @return [void]
     def batch
       return unless params[:read] == "all"
 
@@ -44,6 +68,9 @@ module Admin
 
     private
 
+    # Sets the notification based on the provided ID.
+    #
+    # @return [void]
     def set_notification
       @notification = Notification.find(params[:id])
     end

data/app/controllers/admin/reference_types_controller.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Admin::ReferenceTypesController
+#
+# This controller manages the CRUD operations for ReferenceType objects
+# within the admin namespace. It includes actions to list, show, create,
+# update, and destroy reference types, as well as a custom sort action.
+class Admin::ReferenceTypesController < Admin::AdminController
+  before_action :set_reference_type, only: %i[show edit update destroy]
+
+  # GET /admin/reference_types or /admin/reference_types.json
+  #
+  # Lists all reference types.
+  def index
+    @reference_types = ReferenceType.all
+  end
+
+  # GET /admin/reference_types/1 or /admin/reference_types/1.json
+  #
+  # Shows a specific reference type.
+  def show
+  end
+
+  # GET /admin/reference_types/new
+  #
+  # Initializes a new reference type.
+  def new
+    @reference_type = ReferenceType.new
+  end
+
+  # GET /admin/reference_types/1/edit
+  #
+  # Edits an existing reference type.
+  def edit
+  end
+
+  # POST /admin/reference_types or /admin/reference_types.json
+  #
+  # Creates a new reference type. If successful, redirects to the show page
+  # of the newly created reference type. Otherwise, re-renders the new form.
+  def create
+    @reference_type = ReferenceType.new(reference_type_params)
+
+    respond_to do |format|
+      if @reference_type.save
+        format.html { redirect_to admin_reference_type_path(@reference_type), notice: "Reference type was successfully created." }
+        format.json { render :show, status: :created, location: @reference_type }
+      else
+        format.html { render :new, status: :unprocessable_entity }
+        format.json { render json: @reference_type.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  # PATCH/PUT /admin/reference_types/1 or /admin/reference_types/1.json
+  #
+  # Updates an existing reference type. If successful, redirects to the show
+  # page of the updated reference type. Otherwise, re-renders the edit form.
+  def update
+    respond_to do |format|
+      if @reference_type.update(reference_type_params)
+        format.html { redirect_to admin_reference_type_path(@reference_type), notice: "Reference type was successfully updated." }
+        format.json { render :show, status: :ok, location: @reference_type }
+      else
+        format.html { render :edit, status: :unprocessable_entity }
+        format.json { render json: @reference_type.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  # DELETE /admin/reference_types/1 or /admin/reference_types/1.json
+  #
+  # Destroys a reference type. Redirects to the index page with a notice.
+  def destroy
+    @reference_type.destroy!
+
+    respond_to do |format|
+      format.html { redirect_to admin_reference_types_path, status: :see_other, notice: "Reference type was successfully destroyed." }
+      format.json { head :no_content }
+    end
+  end
+
+  # POST /admin/reference_types/sort
+  #
+  # Sorts reference types based on the provided list of IDs.
+  def sort
+    ReferenceType.sort_elements(params[:id_list])
+    render body: nil
+  end
+
+  private
+
+  # Use callbacks to share common setup or constraints between actions.
+  #
+  # Sets the @reference_type instance variable for actions that require it.
+  def set_reference_type
+    @reference_type = ReferenceType.find(params[:id])
+  end
+
+  # Only allow a list of trusted parameters through.
+  #
+  # Permits the parameters required for creating or updating a reference type.
+  def reference_type_params
+    params.require(:reference_type).permit(:name, :reference_type, :reference_uri, :label, :note, :position)
+  end
+end

data/app/controllers/admin/search_controller.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 # Admin::SearchController
+# This controller handles search-related actions for the admin interface.
 module Admin
   class SearchController < Admin::AdminController
+    # GET /admin/search
+    #
+    # This action sets up the request URL and retrieves facet options
+    # from the Blacklight API.
+    #
+    # @return [void]
     def index
       @request = "#{request.protocol}#{request.host}:#{request.port}"
       @facet_options = BlacklightApiFacets.new(@request).facets

data/app/controllers/admin/users_controller.rb

@@ -1,8 +1,18 @@
 # frozen_string_literal: true
 
 # Admin::UsersController
+#
+# This controller handles the actions related to admin users.
+# It inherits from Admin::AdminController, which provides
+# common functionality for all admin-related controllers.
 module Admin
   class UsersController < Admin::AdminController
+    # GET /admin/users
+    #
+    # This action retrieves all users with admin privileges.
+    # It assigns the result to the @users instance variable,
+    # which can be used in the corresponding view to display
+    # the list of admin users.
     def index
       @users = User.where(admin: true)
     end

data/app/helpers/asset_helper.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 # AssetHelper
+#
+# This module provides helper methods for asset management.
 module AssetHelper
+  # Determines if an asset has a thumbnail to render.
+  #
+  # @param asset [Object] The asset object to check.
+  # @return [Boolean] Returns true if the asset has a file URL and file derivatives present, otherwise false.
   def asset_thumb_to_render?(asset)
     asset&.file_url&.present? && asset&.file_derivatives&.present?
   end

data/app/helpers/bulk_actions_helper.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 # BulkActionsHelper
+#
+# This module provides helper methods for handling bulk actions
+# within the GeoblacklightAdmin application.
 module BulkActionsHelper
+  # Returns a collection of attributes that can be used for bulk actions.
+  #
+  # The collection includes all importable fields from the GeoblacklightAdmin
+  # schema, with "Publication State" prepended to the list.
+  #
+  # @return [Array<String>] an array of attribute names
   def bulk_actions_collection
     attrs = GeoblacklightAdmin::Schema.instance.importable_fields.collect { |key, _value| key }
     attrs.prepend("Publication State")