Manage guestbook page integration

CHANGELOG.md

@@ -8,6 +8,11 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Added
 
+- Manage Guestbooks page integration, including:
+  - a guestbooks table with sorting, enable/disable actions, preview, and per-guestbook response download
+  - Create Guestbook and Download All Responses actions
+  - the Create Guestbook page
+  - a checkbox for including guestbooks from parent collections
 - Dataset Templates UI integration, including create/edit flows, previews, and skeleton states.
 - Dataset Page: added a sidebar to show dataset reviews
 

public/locales/en/collection.json

@@ -52,11 +52,11 @@
   "editCollection": {
     "edit": "Edit",
     "generalInfo": "General Information",
+    "datasetGuestbooks": "Dataset Guestbooks",
     "themeAndWidgets": "Theme + Widgets",
     "permissions": "Permissions",
     "groups": "Groups",
     "datasetTemplates": "Dataset Templates",
-    "datasetGuestbooks": "Dataset Guestbooks",
     "featuredDataverses": "Featured Dataverses",
     "deleteCollection": "Delete Collection"
   },

public/locales/en/guestbooks.json

@@ -1,21 +1,69 @@
 {
   "title": "Dataset Guestbooks",
+  "filters": {
+    "includeFromParent": "Include Guestbooks from {{parent}}"
+  },
+  "actions": {
+    "create": "Create Dataset Guestbook",
+    "enable": "Enable",
+    "disable": "Disable",
+    "downloadAllResponses": "Download All Responses",
+    "view": "View",
+    "copy": "Copy",
+    "edit": "Edit",
+    "downloadResponses": "Download responses",
+    "viewResponses": "View Responses"
+  },
   "errors": {
-    "getGuestbook": "Something went wrong getting the guestbook. Try again later."
+    "getGuestbook": "Something went wrong getting the guestbook. Try again later.",
+    "toggleEnabled": "Something went wrong updating the guestbook status. Try again later.",
+    "downloadResponses": "Something went wrong downloading guestbook responses. Try again later."
+  },
+  "alerts": {
+    "statusUpdated": "The guestbook status has been updated.",
+    "downloadStarted": "Your download has started."
   },
   "preview": {
     "title": "Preview Guestbook",
     "description": "Upon downloading files the guestbook asks for the following information.",
     "guestbookNameLabel": "Guestbook Name",
     "guestbookDataLabel": "Collected Data",
     "guestbookDataTip": "User data collected by the guestbook.",
+    "collectedDataLabel": "Collected Data",
+    "collectedDataTip": "User data collected by the guestbook.",
     "accountInformation": "Account Information",
     "customQuestionsLabel": "Custom Questions",
     "required": "Required",
     "optional": "Optional"
   },
+  "table": {
+    "name": "Guestbook Name",
+    "created": "Created",
+    "usage": "Usage",
+    "responses": "Responses",
+    "action": "Action",
+    "guestbookCreatedAt": "Guestbook created at {{alias}}"
+  },
+  "emptyState": {
+    "whyTitle": "Why Use Guestbooks?",
+    "whyBullets": [
+      "Guestbooks allow you to collect data about who is downloading the files from your datasets. You can decide to collect account information (username, given name & last name, affiliation, etc.) as well as create custom questions (e.g., What do you plan to use this data for?).",
+      "You can download the data collected from the enabled guestbooks to be able to store it outside of Dataverse."
+    ],
+    "howTitle": "How To Use Guestbooks",
+    "howBullets": [
+      "A guestbook can be used for multiple datasets but only one guestbook can be used for a dataset.",
+      "Custom questions can have free form text answers or have a user select an answer from several options."
+    ],
+    "footer": "To get started, click on Edit Collection in this Dataverse and then select <anchorGeneral>General Information</anchorGeneral>. To learn more about guestbooks, visit the <anchorGuide>Dataset Guestbook</anchorGuide> section of the User Guide."
+  },
   "create": {
+    "title": "Create Dataset Guestbook",
+    "info": "To learn more about guestbooks, visit the <anchor>Dataset Guestbook</anchor> section of the User Guide.",
     "fields": {
+      "name": {
+        "label": "Guestbook Name"
+      },
       "dataCollected": {
         "label": "Data Collected",
         "help": "Dataverse account information that will be collected when a user downloads a file. Check the ones that will be required.",
@@ -25,7 +73,26 @@
           "institution": "Institution",
           "position": "Position"
         }
+      },
+      "customQuestions": {
+        "label": "Custom Questions",
+        "help": "Create your own questions to have users provide more than their account information when they download a file. Questions can be required or optional and answers can be text or multiple choice.",
+        "typeLabel": "Question Type",
+        "questionText": "Question Text",
+        "required": "Required field",
+        "addQuestion": "Add question",
+        "types": {
+          "singleLine": "Single Line",
+          "multipleLine": "Multiple Line",
+          "multipleChoice": "Multiple Choice"
+        },
+        "responseOptions": "Response Options",
+        "addOption": "Add response option",
+        "removeOption": "Remove response option",
+        "removeQuestion": "Remove question"
       }
-    }
+    },
+    "submit": "Create Dataset Guestbook",
+    "cancel": "Cancel"
   }
 }

public/locales/es/guestbooks.json

@@ -1,21 +1,69 @@
 {
   "title": "Libros de visitas del dataset",
+  "filters": {
+    "includeFromParent": "Incluir libros de visitas de {{parent}}"
+  },
+  "actions": {
+    "create": "Crear libro de visitas del dataset",
+    "enable": "Habilitar",
+    "disable": "Deshabilitar",
+    "downloadAllResponses": "Descargar todas las respuestas",
+    "view": "Ver",
+    "copy": "Copiar",
+    "edit": "Editar",
+    "downloadResponses": "Descargar respuestas",
+    "viewResponses": "Ver respuestas"
+  },
   "errors": {
-    "getGuestbook": "Algo salió mal al obtener el libro de visitas. Inténtalo de nuevo más tarde."
+    "getGuestbook": "Algo salió mal al obtener el libro de visitas. Inténtalo de nuevo más tarde.",
+    "toggleEnabled": "Algo salió mal al actualizar el estado del libro de visitas. Inténtalo de nuevo más tarde.",
+    "downloadResponses": "Algo salió mal al descargar las respuestas del libro de visitas. Inténtalo de nuevo más tarde."
+  },
+  "alerts": {
+    "statusUpdated": "El estado del libro de visitas se ha actualizado.",
+    "downloadStarted": "La descarga ha comenzado."
   },
   "preview": {
     "title": "Vista previa del libro de visitas",
     "description": "Al descargar ficheros, el libro de visitas solicita la siguiente información.",
     "guestbookNameLabel": "Nombre del libro de visitas",
     "guestbookDataLabel": "Datos recopilados",
     "guestbookDataTip": "Datos del usuario recopilados por el libro de visitas.",
+    "collectedDataLabel": "Datos recopilados",
+    "collectedDataTip": "Datos del usuario recopilados por el libro de visitas.",
     "accountInformation": "Información de la cuenta",
     "customQuestionsLabel": "Preguntas personalizadas",
     "required": "Obligatorio",
     "optional": "Opcional"
   },
+  "table": {
+    "name": "Nombre del libro de visitas",
+    "created": "Creado",
+    "usage": "Uso",
+    "responses": "Respuestas",
+    "action": "Acción",
+    "guestbookCreatedAt": "Libro de visitas creado en {{alias}}"
+  },
+  "emptyState": {
+    "whyTitle": "¿Por qué usar libros de visitas?",
+    "whyBullets": [
+      "Los libros de visitas te permiten recopilar datos sobre quién descarga los ficheros de tus datasets. Puedes decidir recopilar información de la cuenta (nombre de usuario, nombre y apellido, afiliación, etc.) y crear preguntas personalizadas (por ejemplo, ¿para qué planeas usar estos datos?).",
+      "Puedes descargar los datos recopilados de los libros de visitas habilitados para almacenarlos fuera de Dataverse."
+    ],
+    "howTitle": "Cómo usar los libros de visitas",
+    "howBullets": [
+      "Un libro de visitas puede utilizarse en varios datasets, pero un dataset solo puede usar un libro de visitas.",
+      "Las preguntas personalizadas pueden tener respuestas de texto libre o permitir que el usuario seleccione una respuesta entre varias opciones."
+    ],
+    "footer": "Para comenzar, haz clic en Editar colección en este Dataverse y luego selecciona <anchorGeneral>Información general</anchorGeneral>. Para obtener más información sobre los libros de visitas, visita la sección <anchorGuide>Libro de visitas del dataset</anchorGuide> de la Guía de usuario."
+  },
   "create": {
+    "title": "Crear libro de visitas del dataset",
+    "info": "Para obtener más información sobre los libros de visitas, visita la sección <anchor>Libro de visitas del dataset</anchor> de la Guía de usuario.",
     "fields": {
+      "name": {
+        "label": "Nombre del libro de visitas"
+      },
       "dataCollected": {
         "label": "Datos recopilados",
         "help": "Información de la cuenta de Dataverse que se recopilará cuando un usuario descargue un fichero. Marca las que serán obligatorias.",
@@ -25,7 +73,26 @@
           "institution": "Institución",
           "position": "Cargo"
         }
+      },
+      "customQuestions": {
+        "label": "Preguntas personalizadas",
+        "help": "Crea tus propias preguntas para que los usuarios proporcionen más información que la de su cuenta cuando descarguen un fichero. Las preguntas pueden ser obligatorias u opcionales, y las respuestas pueden ser de texto o de opción múltiple.",
+        "typeLabel": "Tipo de pregunta",
+        "questionText": "Texto de la pregunta",
+        "required": "Campo obligatorio",
+        "addQuestion": "Añadir pregunta",
+        "types": {
+          "singleLine": "Una línea",
+          "multipleLine": "Varias líneas",
+          "multipleChoice": "Opción múltiple"
+        },
+        "responseOptions": "Opciones de respuesta",
+        "addOption": "Añadir opción de respuesta",
+        "removeOption": "Eliminar opción de respuesta",
+        "removeQuestion": "Eliminar pregunta"
       }
-    }
+    },
+    "submit": "Crear libro de visitas del dataset",
+    "cancel": "Cancelar"
   }
 }

src/guestbooks/domain/models/Guestbook.ts

@@ -26,4 +26,6 @@ export interface Guestbook {
   customQuestions: GuestbookCustomQuestion[]
   createTime: string
   dataverseId: number
+  usageCount?: number
+  responseCount?: number
 }

src/guestbooks/domain/models/GuestbookResponse.ts

@@ -0,0 +1,32 @@
+export interface GuestbookResponse {
+  id: number
+  dataset: string
+  datasetPid: string
+  date: string
+  type: EventType
+  fileName?: string
+  fileId?: number
+  filePid?: string
+  userName: string
+  email?: string
+  institution?: string
+  position?: string
+  customQuestions?: GuestbookResponseCustomQuestion[]
+}
+
+export interface GuestbookResponseCustomQuestion {
+  question: string
+  response: string
+}
+
+export interface GuestbookResponseSubset {
+  guestbookResponses: GuestbookResponse[]
+  totalGuestbookResponseCount: number
+}
+
+export enum EventType {
+  ACCESS_REQUEST = 'AccessRequest',
+  DOWNLOAD = 'Download',
+  SUBSET = 'Subset',
+  EXPLORE = 'Explore'
+}

src/guestbooks/domain/repositories/GuestbookRepository.ts

@@ -1,8 +1,33 @@
+import { type CreateGuestbookDTO } from '@iqss/dataverse-client-javascript'
 import { Guestbook } from '../models/Guestbook'
+import { GuestbookResponseSubset } from '../models/GuestbookResponse'
 
 export interface GuestbookRepository {
+  createGuestbook: (
+    collectionIdOrAlias: number | string,
+    guestbook: CreateGuestbookDTO
+  ) => Promise<number>
   getGuestbook: (guestbookId: number) => Promise<Guestbook>
-  getGuestbooksByCollectionId: (collectionIdOrAlias: number | string) => Promise<Guestbook[]>
+  getGuestbooksByCollectionId: (
+    collectionIdOrAlias: number | string,
+    includeStats?: boolean,
+    includeInherited?: boolean
+  ) => Promise<Guestbook[]>
+  getGuestbookResponsesByGuestbookId: (
+    guestbookId: number,
+    limit?: number,
+    offset?: number
+  ) => Promise<GuestbookResponseSubset>
+  setGuestbookEnabled: (
+    collectionIdOrAlias: number | string,
+    guestbookId: number,
+    enabled: boolean
+  ) => Promise<void>
+  downloadGuestbookResponsesByCollectionId: (collectionId: number | string) => Promise<string>
+  downloadGuestbookResponsesByGuestbookId: (
+    collectionId: number | string,
+    guestbookId: number
+  ) => Promise<string>
   assignDatasetGuestbook: (datasetId: number | string, guestbookId: number) => Promise<void>
   removeDatasetGuestbook: (datasetId: number | string) => Promise<void>
 }

src/guestbooks/domain/useCases/createGuestbook.ts

@@ -0,0 +1,10 @@
+import { type CreateGuestbookDTO } from '@iqss/dataverse-client-javascript'
+import { GuestbookRepository } from '../repositories/GuestbookRepository'
+
+export function createGuestbook(
+  guestbookRepository: GuestbookRepository,
+  collectionIdOrAlias: number | string,
+  guestbook: CreateGuestbookDTO
+): Promise<number> {
+  return guestbookRepository.createGuestbook(collectionIdOrAlias, guestbook)
+}

src/guestbooks/domain/useCases/downloadGuestbookResponsesByCollectionId.ts

@@ -0,0 +1,8 @@
+import { GuestbookRepository } from '../repositories/GuestbookRepository'
+
+export function downloadGuestbookResponsesByCollectionId(
+  guestbookRepository: GuestbookRepository,
+  collectionId: number | string
+): Promise<string> {
+  return guestbookRepository.downloadGuestbookResponsesByCollectionId(collectionId)
+}

src/guestbooks/domain/useCases/downloadGuestbookResponsesByGuestbookId.ts

@@ -0,0 +1,9 @@
+import { GuestbookRepository } from '../repositories/GuestbookRepository'
+
+export function downloadGuestbookResponsesByGuestbookId(
+  guestbookRepository: GuestbookRepository,
+  collectionId: number | string,
+  guestbookId: number
+): Promise<string> {
+  return guestbookRepository.downloadGuestbookResponsesByGuestbookId(collectionId, guestbookId)
+}

src/guestbooks/domain/useCases/getGuestbookResponsesByGuestbookId.ts

@@ -0,0 +1,11 @@
+import { GuestbookResponseSubset } from '../models/GuestbookResponse'
+import { GuestbookRepository } from '../repositories/GuestbookRepository'
+
+export function getGuestbookResponsesByGuestbookId(
+  guestbookRepository: GuestbookRepository,
+  guestbookId: number,
+  limit?: number,
+  offset?: number
+): Promise<GuestbookResponseSubset> {
+  return guestbookRepository.getGuestbookResponsesByGuestbookId(guestbookId, limit, offset)
+}

src/guestbooks/domain/useCases/setGuestbookEnabled.ts

@@ -0,0 +1,10 @@
+import { GuestbookRepository } from '../repositories/GuestbookRepository'
+
+export function setGuestbookEnabled(
+  guestbookRepository: GuestbookRepository,
+  collectionIdOrAlias: number | string,
+  guestbookId: number,
+  enabled: boolean
+): Promise<void> {
+  return guestbookRepository.setGuestbookEnabled(collectionIdOrAlias, guestbookId, enabled)
+}