Help Center

Menu

Using remote includes

The remote includes feature only applies when using Freemarker templates to format your search results.

The remote include function (<@fb.IncludeUrl>) allows the user to replicate external web designs by including remote content from the user’s website, effectively embedding HTML from another page into the current design.

A common use case of <@fb.IncludeUrl> is to dynamically fetch the site header, footer or menu. It allows the web designer to change search result design (via CSS, JS) without making direct changes to the search templates.

To facilitate this the source page should include comment tags that clearly indicate where an intended include starts and finishes. e.g. wrap the header include in a <!--start_header--> and <!--end_header-->. The IncludeUrl function is then configured to fetch the code that appears between these comments and insert them into the generated page.

Advantages

  • Includes are dynamically updated which provides more control for the user over search designs.

Disadvantages

  • Requires more effort to set up.

  • May result in CSS and JavaScript conflicts.

  • Content is cached to avoid firing HTTP requests to fetch the includes each time search results are returned. It is good practice to set the expiry to a sensible value such as 1 day (86400 seconds) to minimise the Funnelback response time. A dedicated search result template URL that is used solely for the purpose of styling search results is also recommended.

IncludeUrl macro parameters

  • url: URL to request. This parameter is mandatory.

  • expiry: cache time in seconds (default = 3600). Please note the value is to be specified without quotes: expiry=3600. If the remote content does not change frequently (e.g. multiple times each day), it is recommended to set this to expiry=86400 (24 hours), to save server resources.

    The expiry should not be set to a small value as this will have an impact on search response times as Funnelback will need to make the request every time the cache expires and the time to request and cache the page is added to the response time for the query.

  • start: regular expression pattern (Java) marking the beginning of the content to include. Double quotes must be escaped: start="start \"pattern\"".

  • end: regular expression pattern (Java) marking the end of the content to include. Double quotes must be escaped: end="end \"pattern\"".

  • username: username if the remote server requires authentication.

  • password: password if the remote server requires authentication.

  • useragent: User-Agent string to use.

  • timeout: time to wait, in seconds, for the remote content to be returned.

  • convertRelative: boolean, whether relative links in the included content should be converted to absolute ones.

  • convertRelativeRequiresSpace: boolean, while attempting to convert relative links, if true, requires there is a space between HTML attributes in the link. By default, true.

  • cssSelector: CSS selector to use to select the HTML which should be included. The selected element will be the first one to match the selector. The HTML returned will include the element and its attributes. When this option is enabled the document may be slightly modified to be a valid HTML document before the cssSelector is applied this includes wrapping in <html> tags and <body> tags.

  • removeByCssSelectors: A list of CSS selectors which match elements to be removed from the included HTML. This is run after cssSelector. If cssSelector is used, the CSS selectors must be relative to the previously selected element. If cssSelector is not used the HTML may be slightly modified to be a valid HTML document before elements are removed.

IncludeUrl only supports CSS selectors as used with Jsoup. When CSS selectors are used the document will be modified by Jsoup. For example when given: 
<div>
  <p>foo</p>
</div>

Jsoup will transform that to:

<html>
  <head></head>
  <body>
    <div>
      <p>foo</p>
    </div>
  </body>
</html>

Usage example

<@fb.IncludeUrl url="https://www.mysite.com/search-template" expiry=86400 start="<!--start_header-->" end="<!--end_header-->" convertRelative=true />

<@fb.IncludeUrl url="https://www.mysite.com/search-template" expiry=86400 start="<div id=\"header\"></div>" end="<!--end_header-->" convertRelative=true />

<@fb.IncludeUrl url="https://www.mysite.com/search-template" expiry=86400 cssSelector="#header" convertRelative=true />

<@fb.IncludeUrl url="https://www.mysite.com/search-template" expiry=86400 cssSelector="#header" convertRelative=true convertRelativeRequiresSpace="true" />

See also