diff --git a/docs/assets/images/access_annotation_panel.png b/docs/assets/images/access_annotation_panel.png new file mode 100644 index 0000000000..2436a26967 Binary files /dev/null and b/docs/assets/images/access_annotation_panel.png differ diff --git a/docs/assets/images/add-new-resource-value.png b/docs/assets/images/add-new-resource-value.png new file mode 100644 index 0000000000..5f3433f35f Binary files /dev/null and b/docs/assets/images/add-new-resource-value.png differ diff --git a/docs/assets/images/add-new-text-value.png b/docs/assets/images/add-new-text-value.png new file mode 100644 index 0000000000..e9d328aa77 Binary files /dev/null and b/docs/assets/images/add-new-text-value.png differ diff --git a/docs/assets/images/add-value.png b/docs/assets/images/add-value.png new file mode 100644 index 0000000000..1a6c2566b9 Binary files /dev/null and b/docs/assets/images/add-value.png differ diff --git a/docs/assets/images/advanced-search-linked-resource.png b/docs/assets/images/advanced-search-linked-resource.png index 02a5fc4b25..9d19fe989c 100644 Binary files a/docs/assets/images/advanced-search-linked-resource.png and b/docs/assets/images/advanced-search-linked-resource.png differ diff --git a/docs/assets/images/advanced-search-match.png b/docs/assets/images/advanced-search-match.png index 5151e0e2f9..eef687d599 100644 Binary files a/docs/assets/images/advanced-search-match.png and b/docs/assets/images/advanced-search-match.png differ diff --git a/docs/assets/images/advanced-search-regex.png b/docs/assets/images/advanced-search-regex.png index 4cb9ecff9c..f1bd34ce78 100644 Binary files a/docs/assets/images/advanced-search-regex.png and b/docs/assets/images/advanced-search-regex.png differ diff --git a/docs/assets/images/comment-value.png b/docs/assets/images/comment-value.png new file mode 100644 index 0000000000..7d392b5fec Binary files /dev/null and b/docs/assets/images/comment-value.png differ diff --git a/docs/assets/images/compare-resource-select.png b/docs/assets/images/compare-resource-select.png new file mode 100644 index 0000000000..b2b50cda9d Binary files /dev/null and b/docs/assets/images/compare-resource-select.png differ diff --git a/docs/assets/images/compare-resource-view.png b/docs/assets/images/compare-resource-view.png new file mode 100644 index 0000000000..54c457ce87 Binary files /dev/null and b/docs/assets/images/compare-resource-view.png differ diff --git a/docs/assets/images/copy-ark.png b/docs/assets/images/copy-ark.png new file mode 100644 index 0000000000..1417eca2e2 Binary files /dev/null and b/docs/assets/images/copy-ark.png differ diff --git a/docs/assets/images/create-new-res-btn.png b/docs/assets/images/create-new-res-btn.png new file mode 100644 index 0000000000..b85735f925 Binary files /dev/null and b/docs/assets/images/create-new-res-btn.png differ diff --git a/docs/assets/images/create-new-resource-form-step1.png b/docs/assets/images/create-new-resource-form-step1.png new file mode 100644 index 0000000000..c7a860a2cf Binary files /dev/null and b/docs/assets/images/create-new-resource-form-step1.png differ diff --git a/docs/assets/images/create-new-resource-form-step2.png b/docs/assets/images/create-new-resource-form-step2.png new file mode 100644 index 0000000000..998ffd0e79 Binary files /dev/null and b/docs/assets/images/create-new-resource-form-step2.png differ diff --git a/docs/assets/images/dashboard-header.png b/docs/assets/images/dashboard-header.png index 23c4924710..aec0706e7c 100644 Binary files a/docs/assets/images/dashboard-header.png and b/docs/assets/images/dashboard-header.png differ diff --git a/docs/assets/images/delete-erase-resource.png b/docs/assets/images/delete-erase-resource.png new file mode 100644 index 0000000000..53c5035368 Binary files /dev/null and b/docs/assets/images/delete-erase-resource.png differ diff --git a/docs/assets/images/delete-value.png b/docs/assets/images/delete-value.png new file mode 100644 index 0000000000..3f4e3d54b9 Binary files /dev/null and b/docs/assets/images/delete-value.png differ diff --git a/docs/assets/images/edit-resource-label.png b/docs/assets/images/edit-resource-label.png new file mode 100644 index 0000000000..2f5799e83d Binary files /dev/null and b/docs/assets/images/edit-resource-label.png differ diff --git a/docs/assets/images/edit-value-steps.png b/docs/assets/images/edit-value-steps.png new file mode 100644 index 0000000000..6a28e9f3a7 Binary files /dev/null and b/docs/assets/images/edit-value-steps.png differ diff --git a/docs/assets/images/edit-value.png b/docs/assets/images/edit-value.png new file mode 100644 index 0000000000..53b30ab478 Binary files /dev/null and b/docs/assets/images/edit-value.png differ diff --git a/docs/assets/images/link_copy_internal_link.png b/docs/assets/images/link_copy_internal_link.png new file mode 100644 index 0000000000..9462c32324 Binary files /dev/null and b/docs/assets/images/link_copy_internal_link.png differ diff --git a/docs/assets/images/link_edit_value.png b/docs/assets/images/link_edit_value.png new file mode 100644 index 0000000000..d00a9ae664 Binary files /dev/null and b/docs/assets/images/link_edit_value.png differ diff --git a/docs/assets/images/link_paste_link.png b/docs/assets/images/link_paste_link.png new file mode 100644 index 0000000000..b5251a6ce8 Binary files /dev/null and b/docs/assets/images/link_paste_link.png differ diff --git a/docs/assets/images/link_saved_as_standoff.png b/docs/assets/images/link_saved_as_standoff.png new file mode 100644 index 0000000000..171095dcb5 Binary files /dev/null and b/docs/assets/images/link_saved_as_standoff.png differ diff --git a/docs/assets/images/project-info.png b/docs/assets/images/project-info.png index 4c28943b01..bf58a1f912 100644 Binary files a/docs/assets/images/project-info.png and b/docs/assets/images/project-info.png differ diff --git a/docs/assets/images/project-members.png b/docs/assets/images/project-members.png new file mode 100644 index 0000000000..2177222d79 Binary files /dev/null and b/docs/assets/images/project-members.png differ diff --git a/docs/assets/images/region_annotation_panel.png b/docs/assets/images/region_annotation_panel.png new file mode 100644 index 0000000000..f46994b1be Binary files /dev/null and b/docs/assets/images/region_annotation_panel.png differ diff --git a/docs/assets/images/region_draw.png b/docs/assets/images/region_draw.png new file mode 100644 index 0000000000..b603ca676b Binary files /dev/null and b/docs/assets/images/region_draw.png differ diff --git a/docs/assets/images/region_fillin_form.png b/docs/assets/images/region_fillin_form.png new file mode 100644 index 0000000000..597a98af7f Binary files /dev/null and b/docs/assets/images/region_fillin_form.png differ diff --git a/docs/assets/images/region_new_annotation.png b/docs/assets/images/region_new_annotation.png new file mode 100644 index 0000000000..c2e78e872c Binary files /dev/null and b/docs/assets/images/region_new_annotation.png differ diff --git a/docs/assets/images/resource-permissions.png b/docs/assets/images/resource-permissions.png new file mode 100644 index 0000000000..758976f6a2 Binary files /dev/null and b/docs/assets/images/resource-permissions.png differ diff --git a/docs/assets/images/resource-view-with-image.png b/docs/assets/images/resource-view-with-image.png index a47cff1877..b6c117c5fc 100644 Binary files a/docs/assets/images/resource-view-with-image.png and b/docs/assets/images/resource-view-with-image.png differ diff --git a/docs/assets/images/search-3modes.png b/docs/assets/images/search-3modes.png index 640ab3319a..69a8b8d898 100644 Binary files a/docs/assets/images/search-3modes.png and b/docs/assets/images/search-3modes.png differ diff --git a/docs/assets/images/search-advanced-link.png b/docs/assets/images/search-advanced-link.png index c4d02d6e80..b35caccffc 100644 Binary files a/docs/assets/images/search-advanced-link.png and b/docs/assets/images/search-advanced-link.png differ diff --git a/docs/assets/images/search-expert-link.png b/docs/assets/images/search-expert-link.png index 26058f2be3..8af2f7f072 100644 Binary files a/docs/assets/images/search-expert-link.png and b/docs/assets/images/search-expert-link.png differ diff --git a/docs/assets/images/search-expert.png b/docs/assets/images/search-expert.png index 155a8a6d5f..c89a699e87 100644 Binary files a/docs/assets/images/search-expert.png and b/docs/assets/images/search-expert.png differ diff --git a/docs/assets/images/search-fulltext-filterByProject.png b/docs/assets/images/search-fulltext-filterByProject.png index 11f9b84db5..51dd9dc9b1 100644 Binary files a/docs/assets/images/search-fulltext-filterByProject.png and b/docs/assets/images/search-fulltext-filterByProject.png differ diff --git a/docs/assets/images/search-history.png b/docs/assets/images/search-history.png index 66c0e8568e..c67221715e 100644 Binary files a/docs/assets/images/search-history.png and b/docs/assets/images/search-history.png differ diff --git a/docs/assets/images/search-results-list.png b/docs/assets/images/search-results-list.png index b4e01db3ef..8087768209 100644 Binary files a/docs/assets/images/search-results-list.png and b/docs/assets/images/search-results-list.png differ diff --git a/docs/assets/images/show-hide-properties.png b/docs/assets/images/show-hide-properties.png new file mode 100644 index 0000000000..854516fc7c Binary files /dev/null and b/docs/assets/images/show-hide-properties.png differ diff --git a/docs/assets/images/system-user-menu.png b/docs/assets/images/system-user-menu.png index dcf1d3bed5..ea46677dd1 100644 Binary files a/docs/assets/images/system-user-menu.png and b/docs/assets/images/system-user-menu.png differ diff --git a/docs/assets/images/user-account.png b/docs/assets/images/user-account.png index 1a70ae6259..5ac150845d 100644 Binary files a/docs/assets/images/user-account.png and b/docs/assets/images/user-account.png differ diff --git a/docs/assets/images/user-edit-profile.png b/docs/assets/images/user-edit-profile.png index 7aa65f2df0..894c3bcf8a 100644 Binary files a/docs/assets/images/user-edit-profile.png and b/docs/assets/images/user-edit-profile.png differ diff --git a/docs/assets/images/usermenu-to-userprofile.png b/docs/assets/images/usermenu-to-userprofile.png index c73918d98a..735dcbce5a 100644 Binary files a/docs/assets/images/usermenu-to-userprofile.png and b/docs/assets/images/usermenu-to-userprofile.png differ diff --git a/docs/assets/images/value-info.png b/docs/assets/images/value-info.png new file mode 100644 index 0000000000..989a5f79de Binary files /dev/null and b/docs/assets/images/value-info.png differ diff --git a/docs/user-guide/data.md b/docs/user-guide/data.md index 85470e8f5d..d57dc174b8 100644 --- a/docs/user-guide/data.md +++ b/docs/user-guide/data.md @@ -1,81 +1,90 @@ # Data management -Once your [data model](/user-guide/project/#data-model) is ready, you're able to add data. The DSP-APP offers several possibilities to add data, whether you are starting from scratch or importing data from another program. +Once your [data model](https://docs.dasch.swiss/latest/DSP-APP/user-guide/project/#data-model) is ready, you're able to add data. The DSP-APP offers several possibilities to add data, whether you are starting from scratch or importing data from another program. ## Start from scratch -⚠ *NOT YET IMPLEMENTED* (only mockups are presented) -When a project starts from scratch, you will enter and generate new data directly in the DSP-APP itself. Generating new data can be done one by one with a form or with a table-based (Excel like) tool. +When a project starts from scratch, you will enter and generate new data directly in the DSP-APP itself. Generating new data can be done one by one with a form at the moment: -- Upload the files, e.g., the actual audio file of an interview or images of the photographs discussed in the interview +- Upload files, e.g., an audio file, photography, a video, or a document - Augment the metadata -- In case of interview transcriptions from audio or video files, DSP-APP will offer a simple transcription tool -![Create new source e.g. upload audio file of an interview.](../assets/images/mock-source-new-edit.png)*Create new source; e.g. upload audio file of an interview.* +### Create new resource instances + +You can create a new resource instance using the "create new resource" form: + +![Create a new resource instance e.g. a new audio file](../assets/images/create-new-res-btn.png)*There is a button to open the create new resource form in the main header.* + +**Step1:** Select the project you want to work with (if you are part of several ones), select the ontology (if the project has several ones), and then select the resource class you want to create a new instance. Click on Next. + +![Create a new resource instance e.g. a new audio file](../assets/images/create-new-resource-form-step1.png)*Step 1: Create a new resource instance e.g. a new audio file.* + +**Step2:** Fill in the form and upload the file if requested (depending on the type of resource). Please, note that the required fields are marked with an asterisk `*` after the property label. Click on `Save` to create the new resource instance. To go back to Step 1, click on `Back`. If you cannot click on `Save`, it means that a required field has not been filled in. + +![Create a new resource instance e.g. a new audio file](../assets/images/create-new-resource-form-step2.png)*Step2: Create a new resource instance e.g. a new audio file in MP3 format.* + +N.B.: Please, note that the image, video, and audio files must be in one of the required file types supported by the database. The supported types are listed in the upload section of the form. --- -### Organize data and create additional sources -⚠ *NOT YET IMPLEMENTED* +### Connect your data -The workspace of the DSP-APP includes tools to connect different sources, even if they're not in the same project (linkage), to comment on a source and on their metadata fields (annotate), and to transcribe audio-visual material. These actions will generate more data and will help to find specific sources and their relations easily. -It's possible to collect different sources and to store them in an individual collection. You can define more than one collection. You can share collections and invite other users to collaborate. +The workspace of the DSP-APP allows you to connect different resources, even if they are not in the same project (linkage), to comment on a resource and on their metadata fields (annotate). These actions will generate more data and will help to find specific resources and their relations easily. --- ## Search and browse -DSP-APP offers the possibility to the user to search in 3 different ways: **full text** search, **advanced** search and **expert** search (Gravsearch query). The search bar is always available in the header of each page, whether logged in or out. +DSP-APP offers the possibility for the user to search in 3 different ways: **full-text** search, **advanced** search, and **expert** search (Gravsearch query). The search bar is always available in the header of each page, whether logged in or out. -![Search bar with the 3 search modes: full text, advanced and expert](../assets/images/search-3modes.png) +![Search bar with the 3 search modes: full-text, advanced, and expert](../assets/images/search-3modes.png) -### Full text search +### Full-text search -Full text search performs queries including one or more terms or phrases, and returns data that matches search conditions. By default, the search is performed in all projects stored in DSP. However, it is possible to filter by project using the menu "Filter by project" on the left side of the search bar. +The full-text search performs queries including one or more terms or phrases and returns data that matches search conditions. By default, the search is performed in all projects stored in DSP. However, it is possible to filter by the project using the menu "Filter by project" on the left side of the search bar. -![Filter your full text search by specific project](../assets/images/search-fulltext-filterByProject.png)* - Search 1: Full text search* +![Filter your full-text search by specific project](../assets/images/search-fulltext-filterByProject.png)* - Search 1: Full-text search* When clicking on the search bar, the search history panel is displayed. The **10** last searches are registered. It is also possible to clear the search history list (*Clear list* button at the bottom of the panel or the *x* at the end of each line). -![Search history panel](../assets/images/search-history.png)*Search history list is accessible for the full text search from any webpage.* +![Search history panel](../assets/images/search-history.png)*Search history list is accessible for the full-text search from any webpage.* Special syntax: -- question mark? can be used as wildcard symbol for a single character. -- asterisk* can be used as a wildcard symbol for zero, one or multiple characters. +- question mark? can be used as a wildcard symbol for a single character. +- asterisk* can be used as a wildcard symbol for zero, one, or multiple characters. - "quotation marks" searches for the whole pattern. --- ### Advanced search -![Advanced search link is findable in the search menu at the right of the full text search field.](../assets/images/search-advanced-link.png) +![Advanced search link is findable in the search menu at the right of the full-text search field.](../assets/images/search-advanced-link.png) -The advanced search allows for the creation of complex queries using a graphical widget. -The widget's contents are then turned into a string representing a Gravsearch (SPARQL) query to be sent to DSP-API. +The advanced search allows the creation of complex queries using a form. +The form creates a string representing a Gravsearch (SPARQL) query to be sent to DSP-API. A query consists of the following elements: -- data model selection +- selection of the data model - selection of a resource class belonging to the selected data model (optional) - specification of properties, comparison operators, and values (optional). -Although selection of a resource or a property or both are optional, either a resource class has to be selected or at least one property has to be specified, -otherwise the query is not considered valid and cannot be submitted. +Although the selection of a resource or a property or both are optional, either a resource class has to be selected or at least one property has to be specified, otherwise, the query is not considered valid and cannot be submitted. -![Search 2: Advanced search offers many filter combinations and is a powerful search tool.](../assets/images/search-advanced.png)* - Search 2: Advanced search offers many filter combinations and is a powerful search tool.* +![Search 2: Advanced search offers many filter combinations and is a powerful search tool.](../assets/images/search-advanced.png)* - Search 2: Advanced search offers many filter combinations and is a powerful search tool.* #### Comparison Operators Depending on the value type of the chosen property, one or more of the following comparison operators can be selected: -- `is equal to`: value equality: same number, exact same string, overlap of date periods, same target resource. +- `is equal to`: value equality: same number, exact same string, an overlap of date periods, same target resource. - `is not equal to`: value inequality: not same number, not exact same string, no overlap of date periods, not same target resource. - `is greater than`: value comparison: number is greater than search value, date period begins after search value. -- `is greater than or equal to` value equality / value comparison: number is equal to or greater than search value, overlap of date periods or date period begins after search value. +- `is greater than or equal to` value equality/value comparison: number is equal to or greater than search value, an overlap of date periods or date period begins after search value. - `is less than`: value comparison: number is less than search value, date period ends before search value. -- `is less than or equal to`: value equality / value comparison: number is equal to or less than search value, overlap of date periods or date period ends before search value. +- `is less than or equal to`: value equality/value comparison: number is equal to or less than search value, an overlap of date periods or date period ends before search value. - `exists`: value for the given property exists. - `is like`: search value is contained in a text using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function (supports regular expressions). - `matches`: @@ -84,16 +93,16 @@ one or more of the following comparison operators can be selected: #### Search Examples -##### Regular Expressions (is like) +##### is like (regular Expressions) The `is like` operator lets the user search for texts that are *like* the search value via the support of regular expressions In this example, all books are found whose title contains "Narrenschiff" followed by a space and some other characters like "(lat.)" or "(dt.)". -For general information about regular expressions see this [interactive tutorial](https://regexone.com). +For general information about regular expressions, see this [interactive tutorial](https://regexone.com). ![Advanced search panel with a search example](../assets/images/advanced-search-regex.png) -##### Lucene Parser Syntax (matches) +##### matches (Lucene Parser Syntax) Used with a text property, the `matches` operator lets the user search for texts that *match* the search value, supporting [Lucene Query Parser Syntax](https://docs-api.dasch.swiss/08-lucene/lucene-query-parser-syntax/). @@ -104,12 +113,12 @@ This search finds "Jacob" as well as "Jakob". ![Advanced search panel with a search example](../assets/images/advanced-search-match.png) -##### Specifying a Linked Resource (matches) +##### matches (specifying a Linked Resource) Used with a linking property, the `matches` operator lets the user search for a linked resource that matches the specified properties. In this example, the user writes a query looking for all letters that have an author that: -1. was born after January 1st 1650 +1. was born after January 1st, 1650 1. whose family name is "Bernoulli" This is different from the "is equal to" operator that lets the user specify a certain person (selected from a list). @@ -120,13 +129,13 @@ This is different from the "is equal to" operator that lets the user specify a c ### Expert search -![Expert search link is findable in the search menu at the right of the full text search field.](../assets/images/search-expert-link.png) +![Expert search link is findable in the search menu at the right of the full-text search field.](../assets/images/search-expert-link.png) The expert search can be more powerful than the advanced search, but requires knowing how to use the query language Gravsearch (based on SparQL and developed by the DaSCH team). With Gravsearch, expert users can build searches by combining text-related criteria with any other criteria. **For example**: you could search for a page in a manuscript that contains a certain element and also mentions a person, who lived in the same country as another person, who is the author of another author. -![Expert search is a text area in which you can create Gravsearch queries.](../assets/images/search-expert.png)* - Search 3: Expert search is a text area in which you can create Gravsearch queries. Here is the default example you can find in the app.* +![Expert search is a text area in which you can create Gravsearch queries.](../assets/images/search-expert.png)* - Search 3: Expert search is a text area in which you can create Gravsearch queries. Here is the default example you can find in the app.* To learn Gravsearch, go to the DSP-API documentation [→ Gravsearch](https://docs-api.dasch.swiss/03-apis/api-v2/query-language/) @@ -134,14 +143,14 @@ To learn Gravsearch, go to the DSP-API documentation [→ Gravsearch](https:/ ## Search results -### Simple list -The results of the search are displayed in an organised list with a small preview. You can select one result at a time to get more information. + +The results of the search are displayed in an organized list. You can select one result at a time to get more information. ![Search result 1: Simple list of results, similar to Google's list of results.](../assets/images/search-results-list.png)*Search result 1: Simple list of results, similar to Google's list of results.* -⚠ *NOT YET IMPLEMENTED* -It is not possible yet to sort or order by criteria when searching with the full text search, use the advanced search or the expert search instead to get back sorted results. - +⚠ +It is not possible to sort or order by criteria when searching with the full-text search, use the advanced search or the expert search instead to get back sorted results. + --- ## Do research and work on your data -Once you have found the desired sources, you can (re)view them and annotate the source itself, the media file, or single metadata values. If you select more than one source, you can compare them in a side-by-side view, link them, edit them all at once, or save them in a collection. A collection is similar to a playlist in a music app or shopping basket in an online store. +Once you have found the desired resources, you can (re)view them and annotate the resource itself, the media file, or single metadata values. If you select more than one resource, you can compare them in a side-by-side view or link them. + +### Data permissions + +In order to know what you are allowed to see or do with the selected resource, please check the permissions that are granted for your user role. You can find more details about the [permissions in the documentation of DSP-API](https://docs.dasch.swiss/latest/DSP-API/02-knora-ontologies/knora-base/?h=permission#permissions). + +If you don't have the permissions you were supposed to get, please contact the [DaSCH team](mailto:support@dasch.swiss). + +![Get the resource permissions.](../assets/images/resource-permissions.png)*Check the resource permissions you are granted.* + +### Display data + +#### Display a resource + +DSP-APP offers different resource views for different media types. There's a viewer for still images, moving images, audio, and document files. You open them from the list of search results. Depending on the media type, DSP-APP offers different tools to work on the resource. + +In a still image resource, you're able to draw regions on the image and annotate this region. Usually, a still image resource is used for book pages, photographs, postcards, letters, etc. + + + +![Single resource view. The resource type in this example is "Photo".](../assets/images/resource-view-with-image.png)*Single resource view. The resource type in this example is "Page".* + +Additionally, you can work on the resource directly, e.g, mark regions of interest on still images and on documents. + +#### Display resource properties + +By default, only important properties are shown in the resource viewer. To display them all, click on the "unfold" button in the resource toolbar. + +![Show or hide properties.](../assets/images/show-hide-properties.png)*Show or hide properties from the toolbar.* + +To get more information about the property value, i.e. date of creation and author name, you mouse over the value and then on the info button. + +![Get more information about the value](../assets/images/value-info.png)*Get the creation date and the author name of the value.* + +#### Display a value comment + +To display the existing value comment, you mouse over the property value and click on the comment button (3rd icon from the left). + +![Mouse over the property value to see if there is a comment.](../assets/images/comment-value.png)*Mouse over the property value to see if there is a comment and display it.* + +#### Image viewer + +When you open a resource that contains an image, this one is displayed in a viewer. Several functionalities are accessible from the image viewer, e.g. zoom in/out, copy the IIIF link, replace the image or draw a region on the image. + +![Image viewer](../assets/images/region_annotation_panel.png)*Image viewer toolbar.* + +To access the regions, go to the annotation panel. You can **click on a region** in the image viewer, the focus of the page will be redirected to the annotation information. + +![Access the annotation panel](../assets/images/access_annotation_panel.png)*Access the annotation panel from the resource toolbar.* + +--- + +### Display and compare several resources + +You can compare 2 or more resources of any type at the same time side by side. From the search result list, select your resources of interest by checking the checkbox (right side of each result) and clicking on the compare button on the right-side tile. -### Display a source - +![Select 3 resources and compare them.](../assets/images/compare-resource-select.png)*Example: Select 3 resources and compare them.* -The DSP-APP offers different source views for different media types. There's a viewer for still images, moving images, audio and document files. You can open them from the list of search results. Depending on the media type, DSP-APP offers different tools to work on the source. +To keep in mind: The more you compare, the smaller the resource viewer for each will be. You can deselect one or more resources to remove them from the compare viewer. -In a still image source, you're able to draw regions on the image and to annotate or transcribe this region. Usually, a still image source is used for book pages, photographs, postcards, letters etc. +![Visualise your selected resources side-by-side, e.g. 3 resources.](../assets/images/compare-resource-view.png)*Visualise your selected resources side-by-side. You can compare 2 images with an object without representation for instance.* -In time-based sources like moving image or audio document, you can mark sequences on the timeline. A transcription tool helps to annotate and to transcribe the sequence. +--- + +### Add new data + +⚠ You must have the granted permission to proceed. + +#### Add a resource + +See section [Create new resource instances](https://docs.dasch.swiss/latest/DSP-APP/user-guide/data/#create-new-resource-instances). + +#### Add a property value + +You can create a new property value **if your data model allows it**. The value should have a cardinality of 0-1, 0-N or, 1-N. +A "plus" button is displayed to the right of the label or after the first value field. You fill in the form field and save the changes by clicking on the floppy disk button. You can undo (back arrow button) or cancel the changes (x button). + +![Add a new property value.](../assets/images/add-value.png)*Add a new property value.* + +![Save or undo the changes.](../assets/images/add-new-text-value.png)*Save or undo the changes you made.* + +If your property is linked to another resource, you can search for an existing value by typing the first letter of the resource label you are looking for. You can also create a new resource instance by clicking on the first option in the drop-down menu, `Create new: xxx`. -![Single source view. The source type in this example is "Photo".](../assets/images/resource-view-with-image.png)*Single source view. The source type in this example is "Page".* +![Add a new linked resource value.](../assets/images/add-new-resource-value.png) -DSP-APP will offer a graph view to visualize the connection of a selected source. The graph view is a powerful tool because you will find more information about the source by clicking through the nodes. +#### Add an image region -![Graph view of a single source.](../assets/images/source-graph-view.png)*Graph view of a single source.* +To create a new region on an image, you click on the button Draw a region in the toolbar, then select the region you want on the image. -Additionally, you can work on the source directly, e.g, transcribe a moving image or a taped interview or mark regions of interest on still images and on documents. +![Select a region.](../assets/images/region_draw.png)*Select a region on the image with the drawing tool.* -![Single source fullframe view with the transcription tool at the bottom. The source type in this example is "Video" with a table-based sequence protocol on the right hand-side.](../assets/images/source-selected-fullframe.png)*Single source fullframe view with the transcription tool at the bottom. The source type in this example is "Video" with a table-based sequence protocol on the right hand-side.* +Enter the information about the region, an informative label and a description as a comment. You can change the color. + +![Fill in the form.](../assets/images/region_fillin_form.png)*Fill in the form about the selected region.* + +The new region information is displayed after the image viewer. You can edit or delete if you have the granted permissions. A region has also an AKR URL you can copy and share. + +![Region created.](../assets/images/region_new_annotation.png)*A new region has been created.* --- -### Select more than one source - +### Edit your data + +⚠ You must have the granted permission to proceed. + +#### Edit a resource + +To edit the resource label, you reach the edit form by opening the resource menu on the right-side of the toolbar and clicking on `Edit label`. + +![Add a new linked resource value.](../assets/images/edit-resource-label.png) + +#### Edit a property value + +You can edit a property value from the resource viewer. You mouse over the value and click on the edit button. -![Three sources selected; what do you want to do with them?](../assets/images/source-selected-three.png)*Three sources are selected; what do you want to do with them?* +![Add a new linked resource value.](../assets/images/edit-value.png)*Edit button when mousing over the value.* -By selecting more than one source, you will be able to edit them all at once, add them to a collection, share or connect them. -Or you could compare the sources (see [Compare the sources](/user-guide/data/#compare-the-sources)). +You edit your value by changing the text content, searching for another resource label, or creating a new resource instance. Don't forget to save your changes (floppy disk button) or undo them (back arrow button) to leave the edit mode. + +![Add a new linked resource value.](../assets/images/edit-value-steps.png) + +It is the same process to add, edit or delete a comment to the value. --- -### Compare the sources - +### Delete your data + +⚠ You must have the granted permission to proceed. + +#### Delete or erase a resource + +To delete a resource, there are 2 possibilities: -You will be able to compare from two to six source objects at the same time side by side. +1. **Delete** resource: the resource is not searchable or findable in DSP-APP anymore but the data still exists in the database. -![Compare 2 to 6 sources with each other, similar to the Mirador web app.](../assets/images/source-compare-viewer.png)*Compare 2 to 6 sources with each other, similar to the Mirador web app.* +2. **Erase** resource: the resource is **definitely** deleted from the database, it will be impossible to get it back. + +![Delete or erase a resource.](../assets/images/delete-erase-resource.png)*Delete or erase a resource.* + +#### Delete a property value + +You can delete a property value. You mouse over the value and click on the delete button. You have to confirm your choice. It is possible to comment on the deletion of the value in the confirmation pop-up window to explain why it is being deleted. + +![Delete a property value.](../assets/images/delete-value.png)*Delete a property value.* --- -### Annotate and connect your data (sources and/or metadata) - +### Annotate and link your data + +The main feature of the flexible data storage that DSP-APP uses is the possibility to annotate and link resources and their metadata. An annotation can be a small note about a date like "Not sure about the birthdate of this person. There's another date mentioned in the resource XYZ". Inside the note, it will be possible to link to another resource. -A main feature of the flexible data storage that DSP-APP uses is the possibility to annotate and link sources and their metadata. An annotation can be a small note about a date like "Not sure about the birthdate of this person. There's another date mentioned in the source XYZ". Inside the note, it will be possible to link to another source. +Links in DSP-APP are always bi-directional. If you link resource A with resource B, then resource B knows about this connection. If you find resource B, you have the connection to resource A as well. -Links in DSP-APP are always bi-directional. If you link source A with source B, then source B knows about this connection. If you find source B, you have the connection to source A as well. +To link 2 resources (A is an image and B is a document in the example), you go to your resource A that will be linked, open the **Share** menu and click on the button `Copy internal link on clipboard`. You have copied the internal link of your resource A that will be used to make the link with your resource B. + +![Copy the internal link](../assets/images/link_copy_internal_link.png)*Copy the internal link of the resource A.* + +Go to your resource B. You click on the **edit** button of the property value where you want to add the link (by mousing over the value content). This value must be of type **rich text**. + +![Edit the property value](../assets/images/link_edit_value.png)*Edit the property value of type rich text to add the link.* + +You write and select a word or a group of words you want to attach the link to, then click on the **Link** button in the toolbar of the text editor, paste the internal link of resource A here, and click on **Save**. + +![Add the link to your description](../assets/images/link_paste_link.png)*Add the link in your text and save.* + +The word (or the group of words) is now highlighted in blue-grey and is clickable. + +![Link has been added to the text](../assets/images/link_saved_as_standoff.png)*The link has been added to your text.* --- -### Export, save or share the data -⚠ *NOT YET IMPLEMENTED* +### Share your data + +Each resource of your dataset gets an ARK URL (Archival Resource Key), a persistent identifier that will allow citing permanently your resource in papers, conference presentations, books, etc. -Data sets and metadata extracted through a search can be exported as CSV, XML, or other predefined file formats. -It will be also possible to store full text, advanced, and expert search queries to reuse them later, collect source objects in a collection similar to a playlist of a music app or a shopping basket. +You will find it in the **Share** menu of the resource toolbar, click on `Copy ARK to clipboard` to copy and paste it wherever you want. -![The share menu offers many tools to export the data, to send it to someone or to store it in an individual source collection.](../assets/images/share-export-menu.png)*The share menu offers many tools to export the data, to send it to someone or to store it in an individual source collection.* +![Copy ARK URL.](../assets/images/copy-ark.png)*Copy ARK URL.* diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 1a883406d4..47e13c18c1 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -6,23 +6,23 @@ This is the documentation for the generic DSP Web Application of the Data and Se ## Getting started -DSP-APP is an intuitive, easy to use web-based application placed on top of [DSP-API](https://docs.dasch.swiss/developers/dsp-api/documentation/index.md) to directly use its powerful data management functionalities. With this modern web application, the researchers can create their data models, search, browse, and work with their qualitative data as easily as they could with a desktop data management tool. In addition, data models and data will automatically follow accepted standards, be interoperable, findable, and re-usable. Researchers and scholars with small to medium data sets (e.g. PhD research, pilot project, or proof of concept) have access to long-term accessibility to keep their research data alive, guaranteeing longevity of the data. +DSP-APP is an intuitive, easy to use web-based application placed on top of [DSP-API](https://docs.dasch.swiss/latest/DSP-API/01-introduction/what-is-knora/) to directly use its powerful data management functionalities. With this modern web application, the researchers can create their data models, search, browse, and work with their qualitative data as easily as they could with a desktop data management tool. In addition, data models and data will automatically follow accepted standards, be interoperable, findable, and re-usable. Researchers and scholars with small to medium data sets (e.g. PhD research, pilot project, or proof of concept) have access to long-term accessibility to keep their research data alive, guaranteeing longevity of the data. --- ## Login -To login, click on the LOGIN button of the header (right side), a login form will appear. Fill in the form with your credentials (user name or email and password). - ![Get access to the login form.](../assets/images/dashboard-header.png) -In case of a forgotten password, please contact the [DaSCH Team](https://dasch.swiss/team). +To login, click on the LOGIN button of the header (right side), a login form will appear. Fill in the form with your credentials (user name or email and password). + +In case of a forgotten password, please contact the [DaSCH team](mailto:support@dasch.swiss). --- ## Registration -You can use the DSP-APP with restricted access as guest. Otherwise, you'll need a login. At the moment, you have to contact the [DaSCH Team](https://dasch.swiss/team) to get your login credentials. In the future (end of 2020), we will support the [SWITCH edu-ID](https://www.switch.ch/edu-id/). +You can use the DSP-APP with restricted access as guest. Otherwise, you'll need a login. At the moment, you have to contact the [DaSCH team](mailto:support@dasch.swiss) to get your login credentials. --- diff --git a/docs/user-guide/project.md b/docs/user-guide/project.md index 03d8e81c1a..d4572616a6 100644 --- a/docs/user-guide/project.md +++ b/docs/user-guide/project.md @@ -2,7 +2,7 @@ ## Project -Once you are [logged in](/user-guide/#login), the dashboard displays the list of your project(s). If you are a project administrator or a system administrator, you can edit the project information or archive your project from the project menu. Archived projects are stored in a list on your dashboard and they can be "reactivated" at any time. +Once you are [logged in](https://docs.dasch.swiss/latest/DSP-APP/user-guide/#login), the dashboard displays the list of your project(s). If you are a project administrator or a system administrator, you can edit the project information or archive your project from the project menu. Archived projects are stored in a list on your dashboard and they can be "reactivated" at any time. ![Project list and project menu](../assets/images/dashboard.png)* - By clicking on the project name, you get access to the full project information.* @@ -16,21 +16,19 @@ As project administrator or system administrator, you can define your project, a --- -## Collaboration +## Project members -As a system administrator, you can add users as project members and define their permissions roles: *Who is able to edit or to see your project data?* Data includes the research sources and their metadata. [Permissions](/user-guide/project/#permission-groups) can be set for the entire project or for single metadata fields. +As a system administrator, you can add users as project members. A user menu with different actions is accessible for each member of the project (the three-dot icon to the right side of the user line). The admin can grant another user as project admin (or remove this permission), edit user's information, change user's password if forgotten, and remove a user from the project. -A user menu with different actions is accessible for each member of the project (link to the right side of the user line). The admin can appoint another user as project admin (or remove this permission), edit user's information, change user's password if forgotten, and remove a user. +![Collaboration page](../assets/images/project-members.png)* - Project members page where project admin and system admin can add new user to the team.* -![Collaboration page](../assets/images/project-collaboration.png)* - Collaboration page where project admin and system admin can add new user to the team.* - -> **_NOTE:_** **Permissions for project admins to add new users as project member will be implemented soon.** + --- ## Data model -The definition of the data model (*ontology*) is the most important step. The data model is indispensable for structuring your data. Our platform provides a tool for an easy creation of one or more project data models. First, you have to know which data and sources you want to work with. The data model can be flexible and customizable. +The definition of the data model (*ontology*) is the most important step. The data model is indispensable for structuring your data. Our platform provides a tool for an easy creation of one or more project data models. First, you have to know which data and resources you want to work with. The data model can be flexible and customizable. The question which you have to answer before you create your data model is **according to which criteria do you organize your data**? In this respect it may be useful to ask yourself: @@ -39,7 +37,6 @@ The question which you have to answer before you create your data model is **acc As soon as you have come to a conclusion concerning the structure of your data, you're all set to create your data model. - ### Create your data model **Go to *Data model* and click *New data model*** @@ -50,7 +47,6 @@ Go to your project, select the tab `Data model` (step 1) and click the button `N By clicking `New data model`, a dialog box opens: ![Define new data model.](../assets/images/Fig3.png) - **Create data model** Now you have to set a unique name (*please consider the NOTE*) and you can add a comment. Push the button `Create` to create your data model. @@ -120,10 +116,10 @@ You can choose from a selection of the following basic types with various subtyp - Location (*Place*; a [geonames-identifier](https://www.geonames.org/)) - Shape (*color*) -Since in our example you want to add a property for the number of pages of your book, you choose `Number`. Now you will see that you can either choose the type `Decimal`, `Integer` or `Page number` for your property. +Since in our example you want to add a property for the number of pages of your book, you choose `Number`. Now you will see that you can either choose the type `Decimal`, `Integer` or `Page number` for your property. ![Property types.](../assets/images/Fig14.png) -Page numbers have no decimal places, thus you will selecet `Integer` (or `Page number` which is a special case (s. [next section](#correct-property-selection-in-case-of-special-classes))) as the type for your property. The following window pops up: +Page numbers have no decimal places, thus you will select `Integer` (or `Page number` which is a special case (s. [next section](#correct-property-selection-in-case-of-special-classes))) as the type for your property. The following window pops up: ![Property of integer type.](../assets/images/Fig15.png) In the field *Property label* add for example *Number of pages*, in the comment section you should add a meaningful explanation. It might also make sense to toggle `Required field?` since every PDF Document consists of a number of pages. If you toggle it, the number of pages MUST be given if you add data to the class *Book* - it would then be a required field, not an optional one and data could only be saved if you add the number of pages. @@ -194,31 +190,39 @@ To delete a whole data model, you have to click the button `Delete` on the right In the alert window appearing, you click the red button `Delete`. The data model is now deleted. - ## An example In the following example we focus on how we can reflect about our data before building our model and how a data model can relate classes to each other. - ### Preparing a data model You have interviewed 20 people and recorded the interviews. During these interviews you talked about photographs. Among all the data collected during the project, the most important are: -o audio-files of the interview -o transcribed text of conversations (or transcribe the files within the web application) -o photographs -o data about the person you interviewed -o location where the photograph was taken -The following Diagram 1 shows the initial situation: -![Diagram 1: the initial situation.](../assets/images/Fig23.png)*Diagram 1: the initial situation.* +- audio-files of the interview +- transcribed text of conversations (or transcribe the files within the web application) +- photographs +- data about the person you interviewed +- location where the photograph was taken + +The following Diagram 1 shows the initial situation: + +![Diagram 1: the initial situation.](../assets/images/Fig23.png) + +*Diagram 1: the initial situation.* The second step will be to consider the hierarchy of the data. How your hierarchy looks like depends on which criteria your data were organized and what your purposes are. It might even be possible that you don’t need a hierarchy as shown in Diagram 1. In our case, we know that the transcripts are linked to the audio-interviews, persons are linked to interviews and audio-interviews, photographs are linked to audio-interviews and transcripts plus locations are linked to the photographs. How the practical arrangement finally looks like depends on your purposes and preferences. For example we could choose to arrange the data with regards to their audio source as seen in Diagram 2: -![Diagram 2: Focus on the audio-interview.](../assets/images/Fig24.png)*Diagram 2: Focus on the audio-interview.* + +![Diagram 2: Focus on the audio-interview.](../assets/images/Fig24.png) + +*Diagram 2: Focus on the audio-interview.* However, we can also prefer another visualization which focuses on the transcript (Diagram 3): -![Diagram 3: Focus on the transcript.](../assets/images/Fig25.png)*Diagram 3: Focus on the transcript.* + +![Diagram 3: Focus on the transcript.](../assets/images/Fig25.png) + +*Diagram 3: Focus on the transcript.* We could think of many different hierarchies, lastly it depends on what serves your purposes best. Our next step will be to implement the hierarchy in Diagram 3 in our data model. @@ -229,7 +233,7 @@ First, we create the resource classes that constitute the basic containers of ou ![Create resource classes.](../assets/images/Fig26.png) **2. Relate resource classes** -According to our Diagram 3, we determined the transcript to be the centre of the hierarchy. In the transcript, the photographs are mentioned, the interviewed person is linked to the transcript and the audio-interview as the raw source is linked to the transcript too. Thus, we have to add photograph, audio-interview and person as properties to the transcript. +According to our Diagram 3, we determined the transcript to be the center of the hierarchy. In the transcript, the photographs are mentioned, the interviewed person is linked to the transcript and the audio-interview as the raw resource is linked to the transcript too. Thus, we have to add photograph, audio-interview and person as properties to the transcript. In the box of *Transcript* click on `+ Add property`: ![Add property to resource class.](../assets/images/Fig27.png) diff --git a/docs/user-guide/system.md b/docs/user-guide/system.md index bbcb0e19a8..7346bed360 100644 --- a/docs/user-guide/system.md +++ b/docs/user-guide/system.md @@ -38,4 +38,4 @@ For each user, the system admin has access to several actions: ![System admin can add a user as a member user of a project](../assets/images/system-manage-project-membership.png) -- *Suspend user*: the user is deactivated and has no more access to DSP-APP. The system admin can reactivate it at any time. +- *Suspend user*: the user is deactivated and no longer has access to DSP-APP. The system admin can reactivate it at any time. diff --git a/docs/user-guide/user.md b/docs/user-guide/user.md index 9df8513c9e..f014c41645 100644 --- a/docs/user-guide/user.md +++ b/docs/user-guide/user.md @@ -1,34 +1,22 @@ # User Profile -![Get access to your user profile and more](../assets/images/usermenu-to-userprofile.png)* - Get access to your user profile, collections and account from the main user menu.* - ---- - ## Your user profile and projects -To change your personal information as well as your default language used by the interface, you can edit your profile clicking *Edit*. Currently, the avatar image comes from gravatar.com (go on their [website](http://en.gravatar.com/) to register if you want your customized user photo). - -![Get access to your user profile and more](../assets/images/user-profile.png)* - Overview of your user profile and your projects.* - -The list of your projects is accessible, click on one project to get more information about it. As project admin, you can also edit or archive your projects, and as system admin, you can additionally create new project on this page. - -![Edit user's profile](../assets/images/user-edit-profile.png)*Edit your user profile. The username, the email address and the admin rules are not editable.* - ---- +To change your personal information as well as your default language used by the interface, you can edit your profile by clicking *Edit my profile*. Currently, the avatar image comes from gravatar.com (go on their website to register if you want your customized user photo). -## Your collections +![Get access to your user profile and more](../assets/images/usermenu-to-userprofile.png)* - Overview of your user profile and your projects.* -⚠ *NOT YET IMPLEMENTED* +The list of your projects is accessible from here, click on one project to get more information about it. As a project admin, you can also edit or archive your projects, and as a system admin, you can additionally create new projects. -You will be able to store collections of sources or specific searches to work with them later or share them with collaborators. +![Edit user's profile](../assets/images/user-edit-profile.png)*Edit your user profile. The username, the email address, and the admin rules are not editable.* --- ## Your account -As a matter of security, it is strongly recommended to update your password at least once a year. In your account page, you can update your password. +As a matter of security, it is strongly recommended to update your password at least once a year. On your account page, you can update your password. ![Get access to the user account where the user can reset its password and deactivate its own account](../assets/images/user-account.png)* - Update your password and deactivate your user account.* ⚠ -You can delete (deactivate) your own user account. Only a system administrator will be able to reactivate it. +You can delete (deactivate) your own user account. However, only a system administrator will be able to reactivate it.