Funnelback for higher education implementation guide

The Higher Education package is divided into multiple components:

The Higher Education package relies on the presence of the Stencils, a library containing the re-usable UI components as well as hook scripts to implement custom logic used by the Higher Education package.

On Funnelback Cloud the Stencils are pre-installed and there is no setup required. For self-hosted implementations, the Stencils package need to be installed separately.

The table below gives an overview of the collections within the package.

The Higher Education package supports multiple versions of Funnelback. These are are managed as release branches in git.

Please note that from Funnelback v15.20, there will be dedicated release branches for each new version of Funnelback.

Individual collections need to be created for each data source to index (Events, faculty, courses, etc.).

The collection type and configuration will depend on the data source and how the data is accessed, but typically:

Note that the package comes with a set of example collections but these cannot be easily re-used: They are "Local" type collections which are suitable for the dummy example data (e.g. the example XML feeds are stored directly in the collection configuration folder), but unsuitable for a production implementation. It’s likely that a production implementation will require accessing an XML feed of courses remotely for example, via a standard web collection.

Once the component collections are setup, you can configure the main meta collection providing the search endpoint.

Rather than starting from scratch, you can just copy the example meta collection as a starting point, and customize it to suit the client needs. To do so:

Finally, the example meta collection references the Stencils UI components via FreeMarker’s #include directive. This is not desirable for a deployment as these UI components will need to be modified to suit the client look and feel (CSS, HTML). Additionally these components may change overtime, impacting existing implementations if they were referenced as-is. As a result it’s preferable to make a copy of the UI components from the Stencils directly into the main meta collection. That will allow modifying the components and will make the collection independent on Stencils changes.

To do so, locate all the templates that #import a library file from the Stencils. For example in tabs.ftl:

The $SEARCH_HOME/share/stencils/libraries/tabs/tabs.ftl needs to be copied directly into the collection and overwrite the file doing the inclusion, e.g. $SEARCH_HOME/conf/<client>-meta/_default_preview/tabs.ftl (both for the _default_preview and _default profiles).

Repeat this for all the files referencing Stencils UI components:

You are tasked with deploying the Higher Education package for the "Funnelback University (FBU)". FBU:

Deploying the Higher Education package for FBU will need the creation of brand new collections for each datasource, and the copy of the example meta collection for the search endpoint:

The list of supported metadata can be obtained by looking in the configuration of the example collections: higher-education-facebook, higher-education-courses, etc.

For each collection, check the xml.cfg configuration file to view the mapped metadata. For example on the higher-education-courses collection:

Note that the data source doesn’t matter, it doesn’t have to be XML and could be HTML and use metamap.cfg. The only thing that matters is to map the metadata to the predefined index fields (e.g. stencilsCoursesNumber, stencilsCoursesCampus, etc.) so that the package templates will work out of the box without requiring modification.

That being said it’s absolutely possible to use custom names and modify the package templates accordingly.

The search results section is rendered by project.ftl. in the Results macro. This macro calls various macros to compose the search results page: Best bets and Curator messages, spelling suggestions, results, facets, contextual navigation, etc.

Most sub-sections are implemented in base.ftl and facets.ftl.

The Results macro is rarely customized, except if elements of the results section need to be re-ordered.

The following templates are used to render generic features used on a search results page, independently of the client specific needs:

These templates are rarely customized, unless there’s the need to alter the appearance of the tabs or the facets.

Finally, each result type has it own template:

The Higher Education package has been designed to render the right template depending on the type of result being returned. For example if the first result being returned for a search is a Staff directory profile, the people.ftl template will be called.

This allow customization of specific result types display by focusing on short templates containing only result-type specific code, without having to worry about the other templates used to render the page.

The template dispatch is driven by the collection the result is coming from. A setting in collection.cfg maps the collection identifier with the template to use:

Examples:

The dispatching can also be based on the gscopes assigned to the result. This is especially useful for results coming from the same collection (e.g. a web crawl) but that need to be presented differently (e.g. the Program pages of the website vs. all the other content). For example for results with the gscope Courses to use the courses namespace:

Due to FreeMarker architecture, the dispatching of template can only be done based on a FreeMarker namespace, and not a template file name. The namespace is indicated when importing a template, for example:

The dispatching system will look for a macro named Result in the target namespace (e.g. facebook.Result). As a consequence, the template facebook.ftl should declare a Result macro:

Templates for the results shortlist also support the same dispatch mechanism, so that the shortlist can display different result types. The example meta collection only provide a shortlist template for courses:

The result type dispatch is also controlled via collection.cfg:

Adding a new result type for the shortlist works similarly as adding a regular result type template. Re-using the previous example of adding a template for an Instagram collection name fbu-instagram:

To provide structured suggestions via Concierge, a CSV file containing all the possible suggestions need to be generated. For example for staff directory suggestions the CSV file would contain every possible name in the staff directory and what to display for each name.

In a simplified form:

Generating this file manually would be difficult and time consuming. We can leverage the fact that Funnelback is already indexing the staff directory in a separate collection, and generate this CSV file from the data Funnelback has indexed.

This is achieved by using a special FreeMarker template that will list all of the possible entries in the index (all possible staff profiles) and output the data in CSV form.

The template needs to be queried just after the indexing phase, and its output saved into a CSV file, which will then be taken into account by Funnelback to generate Concierge suggestions.

This is simpler to get started with, but causes maintenance problems on the long run as the Funnelback version of the HTML need to be kept in sync with any changes made on the header and footer of the website

To use a custom header and footer, simply edit content_header.ftl and content_footer.ftl and insert the desired HTML code. These two templates are included as part of the main template (simple.ftl) and will be rendered as-is.

html_header.ftl is also available to include additional static resources in the <head> block of the page. This is useful if a set of client-specific CSS and scripts need to be included.

This requires a little bit more work but reduces maintenance over time as Funnelback will simply grab the header and footer from the client website on the fly.

It can however be brittle if future changes are made on the header and footer, and the client is not aware that the header and footer are also used in the Funnelback rendered search page.

Remote includes are configured in collection.cfg:

The URL should point to an HTML document containing a fragment to inject in the <head> block, or in the content header and footer of the page. The HTML is expected to be a partial fragment and not a complete page. For example the document should only contain an HTML fragment with <header>…​</header> or <div class="header">…​</div>

Alternatively the URL can be pointed to the client website homepage and regular expressions can be used to extract the relevant section of the page, based on the HTML source:

This will cause Funnelback to request https://example.org/ and attempt to extract snippets of HTML based on the start and end regular expressions.

This is a powerful technique to easily get a header and footer without needing the client do provide separate HTML document, but it is likely to be brittle as the regular expressions may not match anymore if the structure of the page changes.

To mitigate this, it is recommended to ask the client to place comment markers in the source code to make it easier for Funnelback to locate the fragments to extract. For example:

The inclusion can then be done with:

Because the Higher Education package comes with its own CSS, it will both impact the client header and footer, and be impacted by other styles imported by the client on their templates.

In some cases this is a good thing: If the client CSS defines a custom font and background color, the search page will inherit these automatically.

But in other cases, conflicts will arise: The client may have specified different sizes for the grid, or some of the Higher Education package classes override some of the client.