RFC: Introduce a consistent content API

[ScopeyNZ]

Background

Historically, content of a page has been built and saved into the Content field on SiteTree. A lot of parts of SilverStripe take this for granted now:

- cwp-search configuration of fulltextsearch:

https://github.com/silverstripe/cwp-search/blob/14f469e158169c62c71589ccf41a4bbe44cdcf91/src/Solr/CwpSolrIndex.php#L17-L23

- Broken external links in silverstripe/externallinks:

https://github.com/silverstripe/silverstripe-externallinks/blob/c9f5ca6c722843ae563bfe2b23904737f218d8d0/src/Tasks/CheckExternalLinksTask.php#L184

- Broken link tracking in CMS:

This actually looks at all fields on a page, not just the page itself

silverstripe-cms/code/Model/SiteTreeLinkTracking.php

Lines 119 to 131 in 115ed92

	foreach ($allFields as $field => $fieldSpec) {
	$fieldObj = $this->owner->dbObject($field);
	if ($fieldObj instanceof DBHTMLText) {
	// Merge links in this field with global list.
	$linksInField = $this->trackLinksInField($field, $anyBroken);
	$linkedPages = array_merge($linkedPages, $linksInField);
	}
	}
	// Soft support for HasBrokenLink db field (e.g. SiteTree)
	if ($this->owner->hasField('HasBrokenLink')) {
	$this->owner->HasBrokenLink = $anyBroken;
	}

In a similar vein we have some interesting situations occurring since SiteTreeLinkTracking was applied to every DataObject:

silverstripe-cms/_config/linktracking.yml

Lines 4 to 6 in 0ecdba3

	SilverStripe\ORM\DataObject:
	extensions:
	- SilverStripe\CMS\Model\SiteTreeLinkTracking

This now fills the "Dependant Pages" tab on pages with a bunch of items that aren't actually pages - causing issues:

• Dependent pages can have empty titles #2428
• Cannot view dependent pages when the link exists on content outside of SiteTree silverstripe-subsites#436

At the moment all modules/functionality that want to interact with the content of a page need to do this in their own magic way, and can't really aggregate the content. I'm proposing that we move towards giving a more consolidated API for content as we move towards the idea of having content existing on more than just the SiteTree (ie. content blocks).

Potential goals

• Code that wants to inspect the visible content of a page can easily collect it with one API endpoint.
  • Examples; search indexing and translation exporting
• Content that exists on DataObjects that aren't the "page" have a consistent interface for declaring their relationship to a page
  • Currently CMSEditLink provides an edit link that may or may not be the page. In the future, content will hopefully all be edited from the page
  • The edit link isn't necessarily relevant in all cases. Dependent pages probably should be an example of this. Right now it shows any data object regardless of whether it's a page
• Code can provide "transformations" to run on content on a page (ideally in specific field types).
  • In some cases (eg silverstripe/externallinks) we edit the content to add DOM. Ideally if you want to implement this functionality won't have to determine which HTMLFields are relevant.

Keen to hear thoughts before I go ahead and think about solutions and designing some interfaces.

[maxime-rainville]

Yes, we probably need to take a step back and see how Page and Content block all fit together as an abstraction.

This will probably impact how we adapt the Headless CMS use case as well.

[chillu]

Another use case: SEO analysis on content incl. blocks - Quinn-Interactive/silverstripe-seo#16

[brynwhyman]

Might be another related issue: #2393

[muskie9]

Apologies if I'm not caught up on usages, however my question related to this is in terms of "linking" modules that are considered supported. This may be a whole other can of worms, but it would be amazing for the linking UX available in the WYSIWYG editor to be available as a field in a community module.

The topic is mainly here from my understanding. In my shared experience the full linking UX is "expected" by CMS users, while there are a number of implementation options currently. I understand this is likely something outside of the realm of the core implementation, however clearly defining the best use case for the community in supporting linking outside of the WYSIWYG may be beneficial.

That being said, I think providing a consistent API, similar if not what is suggested in this RFC, will help level this out moving forward for the community. Linking has become increasingly complex and identifying a path for developers to consistently and confidently provide link tracking would be a very welcome improvement.