Update the way links in descriptions work to use the new 'Path' functionality

[jamesrwelch]

Introduction

Any item (container, model, model item, facet) in Mauro can now be referenced by a path. This ticket is to update the link functionality in descriptions and other long text fields to use the new paths for links between Mauro items. The aim is that these name-based paths can be used instead of UUIDs in links, so that descriptions are more easily portable and can be more easily created automatically during bulk operations.

• This applies to descriptions, and to any other long text field in profiles, etc where the HTML / Markdown editors are used.
• It should be implemented in both HTML and Markdown editors

It is related to #417 which provides an alternative to the current wizard for choosing an element.

Paths

A path in Mauro can take one of two forms: absolute and relative

• Absolute paths start from a folder or model identified by name and version.
• Relative paths start from the containing model of the item that is being edited.

A path has the syntax:

type : name [version] | more_path

Where:

• type denotes the type of Mauro item - for example dm is DataModel, fo is Folder, etc. Types are always two characters
• name is the label of the item in question.
• version is used to disambiguate finalised models and versioned folders. If no version is provided, then the latest model with that label will be chosen.

The | character is used to build up chains of paths to navigate through the hierarchy.

Examples

dm:DataModel1 is a link to the latest version of the model named ‘DataModel1’. Note you don’t need the folder path to reach a data model or versioned folder.
dm:DataModel1|dc:DataClass1 is a link to the top-level DataClass called ‘DataClass1’ in the latest version of the data model above.

dc|DataClass1 is a relative link to the top-level DataClass within the current model.

Functionality

• When a long text field is rendered - either normally, or in ‘preview’ mode when editing (in HTML, and in Markdown), the UI should be able to resolve those links. That may involve adding a prefix to the urls to ensure that they lead somewhere within the single-page app. This can use the Pathing API endpoints to resolve to a Mauro item.
• When a long text field is edited, the links should be displayed using this pathing notation so that they can be easily edited by users
• When the ‘add element’ button is selected, the selection of a Mauro item should result in a link that uses this pathing notation.

Decisions

• We will need to decide on a syntax to disambiguate absolute and relative paths. For example, a path starting dm:DataModel1 might either be an absolute path to a data model, or a relative path within the same versioned folder. Initial suggestion would be a prefix of || for an absolute path (c.f. xpath), but happy to take suggestions.
• When links are manually added through the item picker, we might need a way to decide whether an absolute or default path is required. My suggestion is that relative paths should be used where possible, as this ensures links can be resolved when models are imported into other catalogues.

[jamesrwelch]

Tagging @pjmonks and @olliefreeman for discussion

[pjmonks]

These path strings/links still seem to mostly assume that Markdown is used in description fields, so you would store a path like this:

Here is a [catalogue item](dm:Data Model 1|dc:Data Class 1)

But when using the HTML editor, it produces an actual anchor tag in the description (source), and will be URL encoded, like this:

Here is a <a href="#/catalogue/dataModel/dm%3AData%20Model%201/dataClass/dc%3AData%20Class%201">catalogue item</a>

This goes back to some points I made in issue #223 where the ability to switch between Markdown and HTML editors causes confusion as to how best to render the text. I think some consensus on that should also be had before tackling this issue.

[jamesrwelch]

@pjmonks We decided on '|' for a separator in paths because it was less likely to be used in a label than '/'. We do need to do some rationalising here - looking at #223. When we looked before, there weren't any decent html / markdown combined wysiwyg editors. Happy to revisit things now though

[pjmonks]

Having looked at the existing code for picking items, generating the paths to them and rendering them as links, I've noticed that the current version is actually very buggy and does not produce adequate results. Also, tracing the function calls to render links is more complex than I would expect, plus does not cover every use case.

To that end, I think this process can be simplified a bit as well as improved. The two main problems so far are:

1. Paths returned are not correct and do not generate the correct front-end URLs to go to the correct page views.
2. Even if the paths produced correct URLs, each page view (e.g. viewing a Data Model) wouldn't load because the URL is expected to have UUIDs to identify catalogue items instead of labels/path strings.

Generate URLs from paths

To fix the first problem, a new backend issue was created - MauroDataMapper/mdm-core#406 - so that selecting a catalogue item from the item picker (from the Markdown/HTML editor "Select link" dialog) would return the correct path value for that item - including version/branch info and full path to parent (in the case of child items like Data Classes/Elements etc).

Once the correct path is known for any catalogue item, a new UI Router state can be mapped to the frontend URL #/catalogue/item/{path}. This is the URL that should ultimately be rendered by the Markdown and HTML editors for descriptions.

Load item by path

URLs to #/catalogue/item/{path} will actually work like an internal redirect:

1. Capture {path} from the URL
2. Send to Mauro endpoint GET /{domainName}/path/{path} to map back to the exact catalogue item
3. Use the catalogue item information to redirect to the correct page view e.g. if the item is a Data Model, this would redirect to #/catalogue/dataModel/{dataModelId}