Integration

Three ways to get the suggestion list onto a page. All of them read the same stored rows and honour the same TypoScript settings.

As a content element

Add the Semantic Suggestions element (plugin semanticsuggestion_suggestions) wherever an editor should place the list. No TypoScript needed.

In a Fluid template

The extension registers a reusable TypoScript object. Call it from any Fluid template:

<div class="section section-semantic-suggestion">
    <f:cObject typoscriptObjectPath="lib.semantic_suggestion" />
</div>

Or from TypoScript directly:

page.100 =< lib.semantic_suggestion

lib.semantic_suggestion references — rather than copies — the plugin's view, persistence and settings, so a template override applies to both integration paths at once.

Bootstrap Package

The extension ships page templates for every Bootstrap Package layout, each placing the suggestions after the main content (colPos 0) and before the bottom content (colPos 9), inside <div class="section section-semantic-suggestion">.

Enable them in the Constant Editor, category semantic_suggestion > Template Integration, or in TypoScript constants:

plugin.tx_semanticsuggestion_suggestions.settings.overrideBootstrapTemplates = 1

Then flush the cache.

Warning

Set this constant in the root template of the Bootstrap Package site only, never globally.

This extension's TypoScript is loaded instance-wide, so the constant registers our page templates in page.10.templateRootPaths.100 for every site that inherits it. The shipped templates are Bootstrap Package templates: they call lib.dynamicContent and read theme.pagelayout, neither of which exists elsewhere. On a site that does not use Bootstrap Package but whose page template happens to be named Default.html — a very common name — our template wins and the page body renders empty.

Covered layouts: Default, Simple, None, 2Columns, 2Columns2575, 2Columns5050, 2ColumnsOffsetRight, 3Columns, SpecialFeature, SpecialStart, SubnavigationLeft, SubnavigationRight, SubnavigationLeft2Columns, SubnavigationRight2Columns.

Overriding the template

The plugin renders Templates/Suggestions/List.html. Point TypoScript at your own copy, using index 10 or above — 0 and 1 are taken by the extension:

plugin.tx_semanticsuggestion_suggestions.view {
    templateRootPaths.10 = EXT:my_sitepackage/Resources/Private/Templates/
    partialRootPaths.10  = EXT:my_sitepackage/Resources/Private/Partials/
    layoutRootPaths.10   = EXT:my_sitepackage/Resources/Private/Layouts/
}

Variables available in List.html:

Variable	Content
`suggestions`	Array keyed by page UID. Each entry has `similarity` (float), `excerpt` (string) and `data` (the page record, plus `data.media`, the first media file of the page, or `null`).
`currentPageTitle`	Title of the page being rendered.
`pagination`	`currentPage`, `numberOfPages`, `hasNextPage`, `hasPreviousPage`, `startRecord`, `endRecord`, `totalItems`. The plugin paginates at 10 items per page, which is above `maxSuggestions` by default, so a single page of results is the norm.
`debugLogs`	Only filled when debugMode is on, and rendered as a visible block.

Styling

The shipped template reuses Bootstrap card markup, so it inherits the site's styles when Bootstrap is present. The classes it emits:

/* wrapper, only present when you add it yourself or use the shipped page templates */
.section-semantic-suggestion { }

/* emitted by the plugin template */
.card-menu { }              /* the list */
.card-menu-item { }         /* one suggestion, carries proximity="<score>" */
.card-menu-item .card-title { }
.card-menu-item .card-text { }   /* excerpt */
.card-menu-item .card-info { }   /* last modified, score */

Disabling suggestions on some pages

Either remove the object for those pages:

[page["uid"] == 42]
    lib.semantic_suggestion >
[END]

or keep them out of the suggestion lists of other pages with excludePages. The two are not the same thing: the first hides the list on page 42, the second stops page 42 from being suggested.