Broken Link API

[maxime-rainville]

THE ACCEPTANCE CRITERIA BELOW ARE OUT OF DATE

We decided to tackle this more holistically, with an eye to improving content author awareness of broken content more broadly.

As developer creating a custom link types, I want an explicit way to mark a link as broken so I can communicate to content authors that they need to fix the link.

Acceptance criteria

• A link can be marked as broken.
• Broken link API is documented.
• All built-in Link types implement the broken link API.
• A developer can define some mechanism to check if a link is broken.
• This mechanism can be run asynchronously.
• Broken status is reflected in the LinkField UI.
• Interoperability with pre-existing broken link report is considered, but the report is not updated right away.

Note

• There's some pre-existing logic to identify broken links in the WYSIWYG. Have a look at that and try to align to it if appropriate.
• Identify broken link on page load might be difficult. If we do do it, make sure it doesn't negatively impact user experience.

Related card

• Broken links #8
• Provide feedback if a page/file link is missing its relation #124

[GuySartorelli]

I think we might need to take a quick step back on this one to make sure the API lines up with whatever we'll need in regards to reporting.

For context, there are currently two reports for broken links:

1. Broken links reports - reports on broken links to File records or to SiteTree records
2. Broken external links reports - reports on broken links to external URLs

Both of these explicitly only check links in HTML fields on SiteTree records, and cannot check for any other type of link on any other type of object.

There are two open issues about this, ostensibly about getting the reports to look at elemental blocks:

• Broken page / Broken link reports do not work with elemental content area silverstripe-elemental#689
• Include broken links from content blocks silverstripe-externallinks#68

We really need to revisit those reports, and probably make a new report for broken links which models can register into, with each model declaring its own way of identifying and marking broken links.

We should do that before looking at a "broken link API" for linkfield, as I suspect we'll want to implement an initial API on DataObject, and just have the Link models override the relevant methods.

See also

• https://github.com/silverstripeltd/product-issues/issues/443
• RFC: Introduce a consistent content API silverstripe-cms#2454

[maxime-rainville]

After talking to our design team, we've concluded that broken link is an overarching concern that goes beyond LinkFIeld.

We'll de-prioritise the card for now while we explore the wider issue.