Knowledge Base

Search Module Installation Guide

Last Modified:
22 Dec 2020
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

Installation Steps:

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

  • Overview
    • Result/Program Sources: The sources that are supported by the PHP Search
    • Required Content Types: A description of the Content Types required by the PHP Search
  • Setting up result/program sources
    • This guide will deal with the use of Terminalfour created sources.
  • Configuration of the PHP Search module
    • Configure the PHP Search configuration Content Type
  • Displaying the PHP Search
    • Now the configuration is complete, we need to display some results.
    • Introducing the concept of views
  • Finishing up
    • Set up the JavaScript for Ajax functionality, add the content in the sidebar and the canonical links

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 PHP 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.
    • PHP Search Configuration
      • Add the main configuration file
      • Add source file
    • PHP Search View
      • Displays a user-defined view of the PHP search
      • The PHP 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. PHP Search Configuration (Not visible)
  2. PHP Search View (Sidebar oriented in this case)
  3. PHP Search View (Main search input)
  4. PHP Search View (Main Result view)

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

  1. PHP 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.

Terminalfour Programs

The PHP 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 PHP 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 PHP 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

 

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.

Navigation Object

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 Top Content Navigation Object.

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

DetailValue
Name PHP Search: Get JSON Version from Program
Fetch Method Use Branch
Select Section Select your Programs section
Channel Program (Or All Content Types if more than one applicable)
Content dates Channel where search is publishing
Date element Use current content
Ignore date ordering Start Date
Number of pieces of content to display 99999
Which piece of content to start at? 0
Content Layouts? Use alternate content layout
Alternate Content Layout text/course-json
Before HTML  
After HTML  

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.

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:

{"programs": {"program": [<t4 type="navigation" name=" Get JSON Version from Program " id="x"]}}

 If the Program Content Type is working, a Section that contains the above code will output 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.

When we create the PHP Search Configuration Content Type we will place the piece of code in the PHP Search Configuration Content Type.

Configuring the PHP Search Module

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

The PHP 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 PHP 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 PHP 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 PHP 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 "PHP Search" Category and select PHAR as the Media Type:

Add PHAR file to the media library

Content Type: PHP Search Configuration

Basic Configuration:

Create a Section Details Navigation Object:

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

Create a Content Type as follows:

Element NameDescriptionTypeLengthRequired
JSON File Choose Course JSON from Media library Media N/A  Yes 
PHP 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 
Course Compare Link* Output Link to Course Compare section Section/Content Link N/A  No 

*Only required if Course Compare is included

Content Layouts

Create the following Content Layouts on your Content Type:

DetailValue
Name text/autocomplete
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/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"  


*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: PHP Search: Create Config.php

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

Create a Generate File Navigation Object:

DetailValue
Name PHP Search: Create Config.php
File name config
File extension php
Output Directory Use the current directory
Content Layout text/config  
Navigation Object: PHP Search: create autocomplete.php

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

Create a Generate File Navigation Object:

DetailValue
Name PHP Search: create autocomplete.php
File name autocomplete
File extension php
Output Directory Use the current directory
Content Layout text/autocomplete


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
PHP Search View   Yes No  No
PHP Search Configuration   No  Yes No

Site Structure: Content Items

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

DetailValue
Content Type PHP Search Configuration
Name Search Configuration
JSON FIle Link to the file in the media library
PHP 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 PHP Search Configuration, we will need to create the Content Type that displays the module called PHP 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: PHP Search View Positions

This List is used by the PHP 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: PHP Search View

Basic Configuration:

DetailValue
Name PHP 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 PHP Search Configuration  Section/Content Link default Yes
Position in the page Select position in the page  Select Box (PHP 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 "PHP Search Views" Content Types in that Section.

Add an instance of the view to the Search Section

DetailValue
Content Type PHP Search View
Name Search Results view
PHP Program Search Config Link Link to the section where the PHP 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 PHP Search View
Name Search Results view
PHP Program Search Config Link Link to the section where the PHP 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 PHP 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 PHP 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 PHP search installed with the following features:

  • The full PHP 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 PHP Search.

The Program Compare configuration is quite similar to that of the PHP 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 PHP 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 PHP 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
PHP 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 PHP 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
PHP 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
PHP 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