Knowledge Base

Search Module Installation Guide

Last Modified:
25 Jun 2021
User Level:
Administrator +

This step by step guide will help you get up and running with the Search Module to build up a facetted search of your content. In this example, we'll set up and configure a Program Search.

You can download the Search Module here(authentication required).

Server Requirements:

The Search Module requires PHP 5.5, 5.6, 7.0, 7.1 or 7.2+ to be installed on the webserver that will host the site, and on the staging server (if this is a separate server).

Users should not be able to view or download the PHAR file via the browser. To prevent this, add the following lines to the httpd.conf file or wherever your server configuration is handled.

Order allow,deny 
Deny from all
mbstring.so
XMLReader

Installation Steps:

Let's get started with the installation. The following instructions are broken up into these steps:

Overview

  • Result Sources:
    • For the purposes of this installation guide, the source will be content generated by a Content Type in Terminalfour
    • The content will be published as a JSON file which is used by the Program Search as a source of data
  • PHP:
  • Required Content Types
    • Program
      • Source JSON can be fed by multiple Content Types e.g. UG Programs, PG Programs etc.
    • Program Search Configuration
      • Add the main configuration file
      • Add source file
    • Program Search View
      • Displays a user-defined view of the Program search
      • The Program Search is made up of multiple instances of this Content Type

  1.PHP Search Configuration (Non visual Content type) 2.PHP Search View (Sidebar oriented in this case) 3.PHP Search View (Main search input) 4.PHP Search View (Main Result view)

  1. Program Search Configuration (Not visible)
  2. Program Search View (Sidebar oriented in this case)
  3. Program Search View (Main search input)
  4. Program Search View (Main Result view)

1. PHP Search View 2.Program content type 3.Program Compare Functionality

  1. Program Search View (Sidebar oriented – Linked to main search page)
  2. Program Content Type (text/html or text/fulltext of program content)
  3. Program Compare Functionality (Available with Advanced Program Search implementation)

Setting Up The Program Sources

A search needs results, so let's start by setting up the result sources. Once we have a source ready, we'll tackle the module installation itself, starting with its configuration and then the design.

In the following installation guide, we are going to create a Program Content Type from scratch but if you already have an Program Content Type, you can update the Content Elements as below to preserve functionality.

Terminalfour Programs

The Program Search can handle Terminalfour programs, using a specific Content Type(s) to provide the programs displayed in the module.

  • File Extensions: PHP
    • To display the Program Search, your Channel or Microsite must publish PHP files. Therefore if you haven't already, set up PHP as a file extension and enable the extension on your Channel.
    • See here for more information on file extensions

List: Departments (or similar Faculties/Campus/Program Type)

These lists will be the basis of the filters or facets on the Program Search

This is used by the Program Content Type and it will contain all of your programs associated department, examples are shown below, though anything may be used:

Entry NameEntry ValueSub List NameDefault
Biology Biology Optional Sublists available  
Chemistry Chemistry    
Classics Classics    
Computer Science Computer Science    
English English    
Genetics Genetics    
Geophysics Geophysics    
History History    
Mathematics Mathematics    
Medicine Medicine    
Music Music    
Physics Physics    
Psychology Psychology    
Sociology Sociology    
Film Film    
Food and Catering Food and Catering    

Content Type: Program

Create a "Program" Content Type using the following as an example (anything not mentioned may be left at default). Feel free to customize this for your program content and structure, but remember that you'll need to update and customize each of the layouts to match your Content Type.

Elements
Element NameDescriptionTypeLengthRequired
Program Name Enter the name of this Program Plain Text 500 characters  Yes 
Program Location Choose a location from a predefined list Select Box [Locations]  N/A  Yes 
Program Campus Enter the campus this Program takes place on Multi-select List [Program Campus]  N/A  No 
Program Image Select an image to use on the Program page Media  N/A  No 
Program Type Choose undergrad, post-grad, short Program etc Select Box [Program Type]  N/A  Yes 
Program Term Choose the term in which this Program is taking place Check Box [Program Term]  N/A  No 
Program Code Enter the Program code for this Program Plain Text  40 characters  Yes 
Program Duration Choose whether it’s a 1 year Program, 2 year Program etc Select Box [Program Duration]  N/A  Yes 
Program overview A brief introduction to the Program Plain Text  5000 characters  Yes 
Application Link Enter a link where the student can apply for the Program Section/Content Link  N/A  No 
Starting dates Choose the months when this Program starts Multi-select List [Months]  N/A  Yes 
Entry Requirements Enter the prerequisite requirements for applying for this Program HTML  2000 characters  No 
Related Programs Enter some other Programs that are related to this one HTML  2000 characters  No 
Department Choose which department this Program relates to Multi-select List [Departments]  N/A  No 
Faculty Choose which faculty this Program relates to Multi-select List [Faculties]  N/A  No 
Cost Enter the cost of this Program Plain Text  10 characters  No 
Start Date Enter the date the Program starts Date N/A  No 
Credit Requirement Choose the Credit Requirement for this Program Plain Text  80 characters  No 
Content Layouts
DetailValue
Name text/course-json
File extension Default
Syntax JavaScript
Content Layout Processor JavaScript Content
Content Layout Code

In Zip: \php-search\frontend-files\program-search\content-types\course\course-json.java

The code inside course-json.java can be customized. While you should avoid deleting elements, you can add as many as necessary. 

 

DetailValue
Name Default Channel layout e.g. (text/html)
File extension Default
Syntax HTML/XML
Content Layout Processor T4 Standard Content
Content Layout Code Standard T4 tag based HTML for Program Front end

Alternatively

DetailValue
Name Default Channel fulltext layout e.g. (text/fulltext)
File extension Default
Syntax HTML/XML
Content Layout Processor T4 Standard Content
Content Layout Code Standard T4 tag based HTML for Program Front end

Programs Section

This Section will contain all of your Programs. Alternatively, each program would have its own section beneath the “Programs” Parent section.

Program section example

Or

Programs Branch example

"Programs" Contents

Once the "Programs" Section is created add some content to test the functionality.

Required Navigation Object for JSON

PHP Search: Get JSON Version from Program

When Content Items are added that use the Program Content Type, we will need a Navigation Object to output the JSON version of those programs just created. For this, we'll use a Publish to One File navigation object.

Set up options are in the table below. Unlisted options should be left at their default values:

DetailValue
Name Program Search: Get JSON Version from Program
Content type name - Your Program Content type -
Start Section

Use a specific section

Specify Section Select your Programs Branch *
(Check show hidden sections, if applicable) 
Number of levels to recurse 2/3 (Or more if applicable)
Date element Use current content
Before HTML {"programs": [
After HTML ]}
Section Name Unchecked
Surrounding Page Layout None
Alternate Content Layout text/course-json
* PTOF Start Section needs to be one section above the content you want to retrieve. For example:

Section Branch
    Program 1
    Program 2
    Program 3

You need to choose "Section Branch" to retrieve Program 1,2 and 3.

Copy the T4 tag. You're going to need it later. 

Verifying the Program Content Type

So far, we've created a Program Content Type with a Navigation Object that outputs the JSON file with all program Content Items.

Create a local file called progam.json (or similar) and paste the Navigation object into this file. 

<t4 type="navigation" name=" Get JSON Version from Program " id="x" />

Uplaod this file to the media library, ensuring you use a JavaScript media type, to ensure the T4 Tag for the Naivgation Object is parsed. 

This may require an update the the JavaScript Media Type, so as to add JSON to the allowable file extensions.  

This is a good point to test what we've done so far. To verify the steps above in a hidden Section, or in the Program Section just created, add the following code in a Code Content Type and publish the section:

<a href="<t4 type="media" id="x" formatter="path/*" />">Programs JSON File</a>

 If the Program Content Type is working, a Section that contains the above code will output a link to something like the following:

{
  "programs": [{
    "programType": "Postgraduate",
    "programCode": "MS-HCI",
    "programCost": "$24000",
    "contentID": "4727",
    "programURL": "/program-hub/postgraduate-programs/ms-in-human-computer-interaction-hci/",
    "programName": "M.S. in Human-Computer Interaction (HCI)",
    "programLocation": "Los Angeles",
    "startingDates": "August",
    "programDuration": "1 Year",
    "programDepartments": "Computer Science, Mathematics, Psychology",
    "programOverview": "Course Overview Content.",
    "startDate": "Fri, 08 Nov 2019 11:44:00 EST",
    "programFaculties": "Engineering, Humanities & Sciences"
  }]
}

Before continuing the installation ensure that all Program Content Items are present in the JSON File, to ensure the content is outputting correctly.

If it’s not working re-check the above steps to identify the problem.

If you see no output from the Navigation Object and it looks right, check the Programmable Layout.

Once you've verified the JSON is outputting correctly, delete the code Content Item or remove the code from the Page Layout. This was added only for testing purposes.

Configuring the Program Search Module

Once you’ve set up the JSON source, the next step is to display your programs.

The Program Search uses two different Content Types:

  • one that’s used to display the front end, called views
  • another used to define the basic configuration that the views will use.

File Extensions: PHP

You can skip this step if you’ve already done this.

In order to display the Program Search Module, your Channel or Microsite must publish PHP files. If you haven't already, enable the extension on your Channel or Microsite.

Media Layout: path/*

The Program Search Module must output the file path to files like the PHAR File (PHP Archive). To do this, create a Media Layout for the Media Content Type.

Go to Assets > Content Types and search for the Media System Content Type. If it does not already exist, add a Content Layout named "path/*". In the Content Layout code field add the following:

<t4 type="content" name="Media" output="file" />

Media Type: PHAR File

Create a Media Type to upload the PHAR file to the Media Library.

Create a PHAR Media Type and associate the "path/*" Content Layout with it:

Media Type - PHAR File

PHAR File

The Program Search Module uses a PHP library in the PHAR file. The PHAR file contains all the PHP code necessary to make the Search work.

Upload the "php-search-source.phar" file to the "Program Search" Category and select PHAR as the Media Type:

Add PHAR file to the media library

Content Type: Program Search Configuration

Basic Configuration:

Create a Section Details Navigation Object:

DetailValue
Name Program Search: Get JSON Version from Program
Fetch Method Use Branch
Select Section Select your Programs section

Create the Content Type as follows:

Element NameDescriptionTypeLengthRequired
JSON File Choose Course JSON from Media library Media N/A  Yes 
Search Library Choose PHP Main Library PHAR file Media N/A  Yes 
Max Results per Page Number out results to output before pagination Whole Number  3 Characters  Yes 
Program Compare Link* Output Link to Program Compare section Section/Content Link N/A  No 

*Only required if Program Compare is included

Content Layouts

Create the following Content Layouts on your Content Type:

DetailValue
Name text/autocomplete
File Extension Default
Syntax PHP
Content Layout Processor T4 Standard Content
Content Layout Code

In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-configuration/autocomplete.php" 

*Only if Autocomplete is required

DetailValue
Name text/config
Fetch Method Default
Select Section PHP
Channel T4 Standard Content
Content dates In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-configuration/config.php"  
DetailValue
Name text/html (must match the Type set on the Channel)
Fetch Method PHP (.php)
Select Section PHP
Channel T4 Standard Content
Content dates

In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-configuration/html.php"

In general this will only contain the text/autocomplete and text/config Generate File Navigation object.  


*This Content Layout contains two Navigation Objects. We'll modify these later.

DetailValue
Name text/php-head
Fetch Method Default
Select Section PHP
Channel T4 Standard Content
Content dates In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-configuration/head.php"  

Navigation Object: Program Search: Create Config.php

The Program Search Configuration generates a "config.php" file that is called in each Program Search View and defines the settings in the Content Type.

Create a Generate File Navigation Object:

DetailValue
Name Program Search: Create Config.php
File name config
File extension php
Output Directory Use the current directory
Content Layout text/config  
Copy this navigation object and place it in the text/html content layout of the Program Search Configuration
Navigation Object: Program Search: create autocomplete.php

The Program Search Configuration generates an "autocomplete.php" file that is called in each Program Search View if the Autocomplete function is needed.Generate File Navigation Object

Create a Generate File Navigation Object:

DetailValue
Name Program Search: create autocomplete.php
File name autocomplete
File extension php
Output Directory Use the current directory
Content Layout text/autocomplete
Copy this navigation object and place it in the text/html content layout of the Program Search Configuration


Site Structure: Search Section

After creating the Content Type we'll add the single Sections.

Create a Section in the Site Structure that will contain the Search. Depending on how your page is configured to retrieve page elements, e.g., the sidebar, it may require additional Sub-Sections to be created.

Program Hub section example

Enable the following Content Types (either on the Branch or the Section, depending on your requirements):

Content TypeGroupBranchSectionDisabled
Program Search Configuration   No  Yes No

Site Structure: Content Items

Add Content using the Program Search Configuration Content Type as follows:

DetailValue
Content Type Program Search Configuration
Name Search Configuration
JSON FIle Link to the file in the media library
Program Search Library Link to the file in the media library
Max Results per Page Whole number (e.g. 10) for pagination

Verifying the Steps So Far

Publish the Search Section you've just created to verify that:

  1. The Section is published as a PHP file
  2. The Section contains a config.php file that it is blank
  3. The Media library has published "filename.json" that contains the JSON file created for the Programs
  4. In the Media Library, ensure the PHAR File is correctly published

If one of the above items is missing go back and check the steps so far.

Displaying the Search Module

After creating the Program Search Configuration, we will need to create the Content Type that displays the module called Program Search View.

Media Type: PHP File

The Search Module uses the PHP file that contains the view. These files are added to the Media Library. First, check that you have a Media Type for PHP.

Go to System Administration > System Settings > Media Library and, in the Media Types tab, we will add a Media Type.

Create a PHP Media Type and associate the "path/*" Content Layout with it:

Configure The Media Publish On The Channel

Once the Media Type is created, we have to ensure that the Channel willalways publish the file by going to System administration > Setup sites & Channels > Channels, edit the Channel settings and go to Publish Options.

Views Files

In the unzipped "php-search.zip," the "Media Library" directory contains the following files that will be uploaded to the Media Library.

They can be found in /php-search/frontend-files/program-search/content-types/program-search-view/

These can be uploaded to anywhere in the Media Library.

List: Program Search View Positions

This List is used by the Program Search View Content Type and defines where the view will appear in the Page Layout. In the sample site, the General View uses the default Content Layout (text/html) and the sidebar uses another (text/sidebar).

Your List name and values should refer to the Content Layouts included on your page.

The default value is the main Channel Content Layout (e.g. text/html).

Create a List as follows:

NameValueSelectedSublist
Default text/html  Yes  
Sidebar text/sidebar     

Content Type: Program Search View

Basic Configuration:

DetailValue
Name Program Search Configuration
Description Search Configuration
Minimum user level Link to the file in the media library

Elements:

Element NameDescriptionTypeLengthRequired
PHP Program Search Config Link Specify the section where is the Program Search Configuration  Section/Content Link default Yes
Position in the page Select position in the page  Select Box (Program Search View Positions) default Yes
View Select the view file in the Media Library  Media default Yes

Content Layouts

DetailValue
Name text/home
File extension Default
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-view/home.php" 

*Example can be used to display a search box on a homepage for example.

DetailValue
Name text/html
File extension Default
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-view/ html.php"  

*Example to display views in the default area of the page.

DetailValue
Name text/scripts
File extension Default
Syntax type Default
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-view/scripts.php"   

*Used to pull in the required JavaScript in the page

DetailValue
Name text/sidebar
File extension Default
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-view/sidebar.php"   

*Example to display views in the sidebar area of the page.

DetailValue
Name text/styles
File extension Default
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in "php-search/frontend-files/program-search/content-types/program-search-view/styles.php"    

*Example to pull in the required styling, if in a separate file.

Updating the Section

After creating the Content Type you will need to update the Search Section created when the Section was created and allowed the "Program Search Views" Content Types in that Section.

Add an instance of the view to the Search Section

DetailValue
Content Type Program Search View
Name Search Results view
PHP Program Search Config Link Link to the section where the Program Search Configuration content exists
Position in the page Default
View Link to the relevant View file in the Media Library
In “php-search.zip”, use the code in “/php-search/frontend-files/media-library/program-search/views/PSearch-Main.php”

Add another to create the sidebar

DetailValue
Content Type Program Search View
Name Search Results view
PHP Program Search Config Link Link to the section where the Program Search Configuration content exists
Position in the page Sidebar
View Link to the relevant View file in the media library
In “php-search.zip”, use the code in “/php-search/frontend-files/media-library/program-search/views/PSearch-Sidebar.php”

Publish the section and check that results and facets are now appearing, based on the content within the JSON file.

Finishing Up

When the Program Search module is working, we need to set up the JS for the AJAX live-reload functionality

The first step is to add the JS File for the AJAX functionality:

Media Type: JavaScript

If a JavaScript Media Type doesn't exist, create one and associate the "javascript/*" Content Layout with it:

Add JavaScript Media Type

Media Layout: JavaScript Content Layout

If it does not already exist, add another Content Layout to the Media System Content Type named "javascript/*". In the Content Layout code field add the following:

<script type="text/javascript" src="<t4 type="content" name="Media" output="file" />"></script>

JavaScript File 

The "php-search.js" file can be uploaded to any Media Category. Select JavaScript as the Media Type.

Navigation Object: Return Scripts to current section

DetailValue
Name Return Scripts to current section
Fetch Method Use current
Content Layouts Use alternate Content Layout
Content Layout text/scripts

Page Layout

Any Page Layout can use the Program Search. In the one used in the Search Section add the following:

  • the Navigation Object for text/php-head (at the top of the page, before <!DOCTYPE html>)
  • the Navigation Object for text/sidebar
  • the Navigation Object for text/scripts (at the bottom of the page (generally))

Final Verification

Once you have followed the whole installation guide you should have now the Program search installed with the following features:

  • The full Program Search
  • Searchable programs with AJAX (Live reload) functionality
  • Filter facets in the sidebar with AJAX functionality

Once you've completed this step, you can customize the design of the single views file and the configuration settings.

Program Compare Module

Program Compare allows end-users to compare chosen courses side by side. As a user navigates the site they can choose to 'Save Courses' they are interested in. They can then 'View Saved Courses' and choose up to 3 courses at a time to compare side by side. This gives them a visual overview of useful portions of the courses. The course compare is typically integrated as part of our Program Search.

The Program Compare configuration is quite similar to that of the Program Search and relies on its PHAR file to operate.

Overview

Result Sources:

  • For the purposes of this installation guide, the source will be content generated by a Content Type within Terminalfour
  • They should be published as a JSON file which is used by the Program Search as a source of data

PHP:

  • The PHAR file, a PHP Main Library archive, and the list of views are managed within the Media Library.
  • Server Requirements (See Above)

Required Content Types

  • Program
    1. Source JSON can be fed by multiple Content Types e.g. UG Programs, PG Programs etc.
  • Program Compare Configuration
    1. Add main configuration file
    2. Add source file
  • Program Compare View
    1. Displays a user-defined view of the Program search
    2. The Program Compare is made up of multiple instances of this Content Type

Program Compare - Buttons and display

  1. Program Compare Sidebar (Displays chosen programs)
  2. Program Compare Save Toggle
  3. Link to Compare Programs page

Program Compare - Comparison display

  1. Program Compare Sidebar (Toggles choices)
  2. Program Compare Main View

Setting Up The Program Sources

See Setting up the program sources

Configuring the Program Compare Module

Once you’ve set up the JSON source, the next step is to compare your programs.

The Program Compare uses two different Content Types, one that’s used to display the front end, called views and another used to define the basic configuration that the views will use.

File Extensions: PHP

See above - File Extensions - PHP

Media Layout: path/*

See above - Media Layout: path/*

Media Type: PHAR File

See above - Media Type: PHAR File

PHAR File

See above - PHAR File

Content Type: Program Compare Configuration

Basic Configuration:

DetailValue
Name Program Compare Configuration
Description Program Compare Configuration Content Type
Minimum user level Administrator

 

Element NameDescriptionTypeLengthRequired
JSON File Choose Course JSON from Media library  Media default Yes
Program Search Library Choose PHP Main Library PHAR file  Media default Yes
Max Results per Page Number out results to output before pagination Whole Number 3 chars Yes
Program Compare Link Output Link to Course Compare section Section/Content Link default Yes
Min Results to Select Choose a number Whole Number 2 chars Yes
Max Results to Select Choose a number Whole Number 2 chars Yes

Content Layouts

DetailValue
Name text/config
File extension Default
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in "php-search/frontend-files/program-compare/content-types/program-compare-configuration/config.php" 

 

DetailValue
Name text/html (must match the Type set on the Channel)
File extension PHP (.php)
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in " php-search/frontend-files/program-compare/content-types/program-compare-configuration/html.php"  

*This Content Layout contains Navigation Objects. We'll modify these later.

DetailValue
Name text/php-head
File extension Default
Syntax type PHP
Content Layout Processor T4 Standard Content
Content Layout Code In "php-search.zip", use the code in " php-search/frontend-files/program-compare/content-types/program-compare-configuration/head.php"   

Navigation Object: Program Compare: Create Config.php

The Program Compare Configuration generates a "config.php" file that is called in each Program Search View and defines the settings in the Content Type.

DetailValue
Name Program Compare : Create Config.php
File name config
File extension php
Output Directory Use the current directory
Content Layout text/config 

Site Structure: Compare Section

After creating the Content Type we'll add the single Sections.

Create a Section in the Site Structure that will contain the Search. Depending on how your page is configured to retrieve page elements, e.g., the sidebar, it may require additional Sub-Sections to be created.

Program Compare Section

Enable the following Content Types (either on the Branch or the Section, depending on your requirements):

Content TypeGroupBranchSectionDisabled
Program Compare View   Yes No No
Program Compare Configuration   No Yes No

Site Structure: Content Items

Add two content items to the "Program Compare" section as follows:

DetailValue
Content Type Program Compare Configuration
Name Program Compare Configuration
JSON FIle Link to the file in the media library
Program Search Library Link to the file in the media library
Program Search Link Link to section with the Main Program Search 
Max Results per Page Whole number (e.g. 5) 
Min Results to Select Whole number (e.g. 2)
Max Results to Select Whole number (e.g. 3) 

 

DetailValue
Content Type Program Compare View
Name Program Compare Results view
JSON FIle Link to the section where the Program Compare Configuration content exists
Program Search Library Default/Main
View Link to the relevant View file in the media library
In “php-search.zip”, use the code in “/php-search/frontend-files/media-library/program-compare /views/PCompare-Main.php”
Back to top