Developer docs for catalog navigation design

[jsheunis]

We need a thorough description of how navigation (URL- and user-based) works in the catalog. It is completely undescribed at the moment and would need someone to be very well versed in VueJS and Vue Router if they want to contribute to the code.

Below is the first attempt. It should ultimately find its way into the docs.

[jsheunis]

Background information

• The catalog is built with Vuejs 2, uses Bootstrap-Vue components, and implements URL-based navigation with Vue Router 3.
• Any instance of a Vue app or component is subject to the standard Vue Life cycle hooks, meaning that a set of standard functions will be called in order when the instance is created.
• For components linked to specific named routes in the context of Vue Router, navigation guards can be used to run code at specific points in the routing process.

The catalog app navigation options

Precursors

Whenever a catalog page is opened in a new tab/window in a browser, or when it's refreshed, the Vue app instance is created: https://github.com/datalad/datalad-catalog/blob/main/datalad_catalog/catalog/assets/app.js. This happens irrespective of whether the URL contains parameters or not.

Apart from setting up the basic content of the outer wrapper of the catalog (logo, social links, etc) from a configuration file, this Vue app instance also specifies inclusion of the router instance, which is specified and instantiated here: https://github.com/datalad/datalad-catalog/blob/main/datalad_catalog/catalog/assets/app_router.js

Subsequently, the router handles navigation.

A. Navigate to http://mycatalog.com by entering that URL into a browser

1. Router recognises home route from the URL (there are no parameters), and navigates to it
2. Router calls beforeEnter() of home route:
   • check if a home page is specified via ./metadata/super.json
   • if home dataset_id and dataset_version NOT available from that file, navigate to 404 page --> router.push({ name: "404" })
   • if home dataset_id and dataset_version available, navigate to dataset page (which has an associated component) -->

         router.push({
           name: "dataset",
           params: {
             dataset_id: superds["dataset_id"],
             dataset_version: superds["dataset_version"],
           },
         });

3. Router navigates to dataset route, which creates the datasetView component and its children and then calls async created() of this component, which does the following:
   • try to identify the dataset from route parameters dataset_id and dataset_version and then access its metadata file (unavailable file results in router.push({ name: "404" }))
   • set component data for selected dataset from available file
   • grab subdatasets of selected dataset and set some more component data
   • set available tabs of selected dataset
   • set the correct tab by calling setCorrectTab()

B. Navigate to another dataset from within a catalog by user action

Notes

• home route is never actually entered, because it navigates to the dataset route or 404 route inside of beforeEnter() navigation guard
• dataset route will always have parameters dataset_id and dataset_version
• when exactly should dataset_ready, subdatasets_ready and files_ready be set (since these variables are being watched).
• consider calling setCorrectTab() from watcher?

[jsheunis]

These docs should take the redesign with aliases and concept-id implemented in https://github.com/datalad/datalad-catalog/pull/430 into account.