geoblacklight_admin 0.5.0 → 0.6.0

data/app/controllers/admin/documents_controller.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
 # Admin::DocumentsController
+# This controller handles the management of documents within the admin interface.
+# It provides actions to list, create, update, and delete documents, as well as
+# export them in various formats.
 module Admin
   class DocumentsController < Admin::AdminController
+    # Allow all parameters (not recommended for production use)
     ActionController::Parameters.permit_all_parameters = true
-    before_action :set_document,
-      only: %i[show edit update destroy admin versions]
+
+    # Set the document before certain actions
+    before_action :set_document, only: %i[show edit update destroy admin versions]
 
     # GET /documents
     # GET /documents.json
+    # Lists all documents with support for various export formats.
     def index
+      # Construct the request URL
       @request = "#{request.protocol}#{request.host}:#{request.port}"
 
+      # Define query parameters for the document search
       query_params = {
         q: params["q"],
         f: params["f"],
@@ -22,56 +30,47 @@ module Admin
       }
       @documents = BlacklightApi.new(@request, **query_params)
 
+      # Respond to different formats
       respond_to do |format|
         format.html { render :index }
         format.json { render json: @documents.results.to_json }
-
-        # JSON - BTAA Aardvark
         format.json_btaa_aardvark do
-          ExportJsonJob.perform_later(@request, current_user, query_params.merge!({format: "json_btaa_aardvark"}),
-            ExportJsonService)
+          ExportJsonJob.perform_later(@request, current_user, query_params.merge!({format: "json_btaa_aardvark"}), ExportJsonService)
           head :no_content
         end
-
-        # JSON - GBL Aardvark
         format.json_aardvark do
           ExportJsonJob.perform_later(@request, current_user, query_params.merge!({format: "json_aardvark"}), ExportJsonService)
           head :no_content
         end
-
-        # JSON - GBL v1
         format.json_gbl_v1 do
           ExportJsonJob.perform_later(@request, current_user, query_params.merge!({format: "json_gbl_v1"}), ExportJsonService)
           head :no_content
         end
-
-        # JSON - FILE
         format.json_file do
           ExportJsonBulkJob.perform_later(@request, current_user, query_params.merge!({format: "json_file"}), ExportJsonService)
           head :no_content
         end
-
-        # CSV - B1G
         format.csv do
           ExportJob.perform_later(@request, current_user, query_params, ExportCsvService)
           head :no_content
         end
-
-        # CSV Document Downloads - B1G
         format.csv_document_downloads do
           ExportJob.perform_later(@request, current_user, query_params, ExportCsvDocumentDownloadsService)
           head :no_content
         end
-
-        # CSV Document Access Links - B1G
         format.csv_document_access_links do
           ExportJob.perform_later(@request, current_user, query_params, ExportCsvDocumentAccessLinksService)
           head :no_content
         end
+        format.csv_document_distributions do
+          ExportJob.perform_later(@request, current_user, query_params, ExportCsvDocumentDistributionsService)
+          head :no_content
+        end
       end
     end
 
-    # Fetch documents from array of friendlier_ids
+    # Fetch documents from an array of friendlier_ids
+    # This action retrieves documents based on their friendlier IDs.
     def fetch
       @request = "#{request.protocol}#{request.host}:#{request.port}"
       @documents = Document.where(friendlier_id: params["ids"])
@@ -79,71 +78,62 @@ module Admin
       respond_to do |format|
         format.html { render :index }
         format.json { render json: @documents.to_json }
-
-        # JSON - BTAA Aardvark
         format.json_btaa_aardvark do
-          ExportJsonJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "json_btaa_aardvark"},
-            ExportJsonService)
+          ExportJsonJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "json_btaa_aardvark"}, ExportJsonService)
           head :no_content
         end
-
-        # JSON - GBL Aardvark
         format.json_aardvark do
-          ExportJsonJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "json_aardvark"},
-            ExportJsonService)
+          ExportJsonJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "json_aardvark"}, ExportJsonService)
           head :no_content
         end
-
-        # JSON - GBL v1
         format.json_gbl_v1 do
-          ExportJsonJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "json_gbl_v1"},
-            ExportJsonService)
+          ExportJsonJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "json_gbl_v1"}, ExportJsonService)
           head :no_content
         end
-
-        # CSV - B1G
         format.csv do
-          ExportJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "csv"},
-            ExportCsvService)
+          ExportJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "csv"}, ExportCsvService)
           head :no_content
         end
-
-        # CSV Document Downloads - B1G
         format.csv_document_downloads do
-          ExportJob.perform_later(@request, current_user,
-            {ids: @documents.pluck(:friendlier_id), format: "csv_document_downloads"}, ExportCsvDocumentDownloadsService)
+          ExportJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "csv_document_downloads"}, ExportCsvDocumentDownloadsService)
           head :no_content
         end
-
-        # CSV Document Downloads - B1G
         format.csv_document_access_links do
-          ExportJob.perform_later(@request, current_user,
-            {ids: @documents.pluck(:friendlier_id), format: "csv_document_access_links"}, ExportCsvDocumentAccessLinksService)
+          ExportJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "csv_document_access_links"}, ExportCsvDocumentAccessLinksService)
+          head :no_content
+        end
+        format.csv_document_distributions do
+          ExportJob.perform_later(@request, current_user, {ids: @documents.pluck(:friendlier_id), format: "csv_document_distributions"}, ExportCsvDocumentDistributionsService)
           head :no_content
         end
       end
     end
 
     # GET /documents/new
+    # Renders a form for creating a new document.
     def new
       @document = Document.new
       render :edit
     end
 
     # GET /documents/1/edit
+    # Renders a form for editing an existing document.
     def edit
     end
 
     # GET /documents/1/admin
+    # Admin view for a specific document.
     def admin
     end
 
     # GET /documents/1/versions
+    # Displays the version history of a document.
     def versions
     end
 
     # POST /documents
     # POST /documents.json
+    # Creates a new document with the provided parameters.
     def create
       @document = Document.new(document_params)
       @document.friendlier_id = @document.send(GeoblacklightAdmin::Schema.instance.solr_fields[:id])
@@ -152,7 +142,7 @@ module Admin
           format.html { redirect_to edit_admin_document_path(@document), notice: "Document was successfully created." }
           format.json { render :show, status: :created, location: @document }
         else
-          format.html { render :edit }
+          format.html { render :edit, status: :unprocessable_entity }
           format.json { render json: @document.errors, status: :unprocessable_entity }
         end
       end
@@ -160,13 +150,14 @@ module Admin
 
     # PATCH/PUT /documents/1
     # PATCH/PUT /documents/1.json
+    # Updates an existing document with the provided parameters.
     def update
       respond_to do |format|
         if @document.update(document_params)
           format.html { redirect_to edit_admin_document_path(@document), notice: "Document was successfully updated." }
           format.json { render :show, status: :ok, location: @document }
         else
-          format.html { render :edit }
+          format.html { render :edit, status: :unprocessable_entity }
           format.json { render json: @document.errors, status: :unprocessable_entity }
         end
       end
@@ -174,6 +165,7 @@ module Admin
 
     # DELETE /documents/1
     # DELETE /documents/1.json
+    # Deletes a document.
     def destroy
       @document.destroy
       respond_to do |format|
@@ -184,6 +176,8 @@ module Admin
       end
     end
 
+    # GET /documents/1
+    # Shows a document in various formats.
     def show
       respond_to do |format|
         format.html { redirect_to edit_admin_document_url(@document) }
@@ -191,37 +185,29 @@ module Admin
         format.json_aardvark
         format.json_btaa_aardvark
         format.json_gbl_v1
-        # B1G CSV
         format.csv { send_data collect_csv([@document]), filename: "documents-#{Time.zone.today}.csv" }
-
-        # @TODO:
-        # geoblacklight_version: 1.0 (strict)
-        # geoblacklight_version: 1.0 + B1G customizations
-        # geoblacklight_version: 2.0 (strict)
-        # geoblacklight_version: 2.0 + B1G customizations
       end
     end
 
     private
 
     # Use callbacks to share common setup or constraints between actions.
+    # Finds and sets the document based on the friendlier_id.
     def set_document
       @document = Document.includes(:leaf_representative).find_by!(friendlier_id: params[:id] || params[:document_id])
     end
 
-    # only allow whitelisted params through (TODO, we're allowing all document params!)
-    # Plus sanitization or any other mutation.
-    #
-    # This could be done in a form object or otherwise abstracted, but this is good
-    # enough for now.
+    # Defines the list of permitted parameters for document creation and updates.
     def permittable_params
       %i[title publication_state layer_geom_type_s dct_references_s q f page sort rows daterange]
     end
 
+    # Strong parameters for document creation and updates.
     def document_params
       Kithe::Parameters.new(params).require(:document).permit_attr_json(Document).permit(permittable_params)
     end
 
+    # Collects documents into a CSV format.
     def collect_csv(documents)
       CSV.generate(headers: true) do |csv|
         csv << GeoblacklightAdmin::Schema.instance.exportable_fields.map { |k, _v| k.to_s }

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,11 +88,16 @@ 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
+      redirect_to admin_elements_url, alert: "Element not found."
     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,11 +98,15 @@ 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
+      redirect_to admin_form_elements_url, alert: "Form element not found."
     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/ids_controller.rb

@@ -397,5 +397,11 @@ module Admin
         end
       end
     end
+
+    private
+
+    def ids_params
+      params.permit(:id)
+    end
   end
 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)
 
@@ -40,7 +66,7 @@ module Admin
           end
           format.json { render :show, status: :created, location: @import }
         else
-          format.html { render :new }
+          format.html { render :new, status: :unprocessable_entity }
           format.json { render json: @import.errors, status: :unprocessable_entity }
         end
       end
@@ -48,13 +74,14 @@ 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)
           format.html { redirect_to admin_import_path(@import), notice: "Import was successfully updated." }
           format.json { render :show, status: :ok, location: @import }
         else
-          format.html { render :edit }
+          format.html { render :edit, status: :unprocessable_entity }
           format.json { render json: @import.errors, status: :unprocessable_entity }
         end
       end
@@ -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,