Search Module Installation Guide
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:
- 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
- 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
- Program
- PHP Search Configuration (Not visible)
- PHP Search View (Sidebar oriented in this case)
- PHP Search View (Main search input)
- PHP Search View (Main Result view)
- PHP Search View (Sidebar oriented – Linked to main search page)
- Program Content Type (text/html or text/fulltext of program content)
- 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 Name | Entry Value | Sub List Name | Default |
---|---|---|---|
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 Name | Description | Type | Length | Required |
---|---|---|---|---|
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
Detail | Value |
---|---|
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 |
Detail | Value |
---|---|
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
Detail | Value |
---|---|
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.
Or
"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:
Detail | Value |
---|---|
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:
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:
Content Type: PHP Search Configuration
Basic Configuration:
Create a Section Details Navigation Object:
Detail | Value |
---|---|
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 Name | Description | Type | Length | Required |
---|---|---|---|---|
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:
Detail | Value |
---|---|
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
Detail | Value |
---|---|
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" |
Detail | Value |
---|---|
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.
Detail | Value |
---|---|
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:
Detail | Value |
---|---|
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:
Detail | Value |
---|---|
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.
Enable the following Content Types (either on the Branch or the Section, depending on your requirements):
Content Type | Group | Branch | Section | Disabled |
---|---|---|---|---|
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:
Detail | Value |
---|---|
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:
- The Section is published as a PHP file
- The Section contains a config.php file that it is blank
- The Media library has published "filename.json" that contains the JSON file created for the Programs
- 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:
Name | Value | Selected | Sublist |
---|---|---|---|
Default | text/html | Yes | |
Sidebar | text/sidebar |
Content Type: PHP Search View
Basic Configuration:
Detail | Value |
---|---|
Name | PHP Search Configuration |
Description | Search Configuration |
Minimum user level | Link to the file in the media library |
Elements:
Element Name | Description | Type | Length | Required |
---|---|---|---|---|
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
Detail | Value |
---|---|
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.
Detail | Value |
---|---|
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.
Detail | Value |
---|---|
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
Detail | Value |
---|---|
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.
Detail | Value |
---|---|
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
Detail | Value |
---|---|
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
Detail | Value |
---|---|
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:
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
Detail | Value |
---|---|
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
- Source JSON can be fed by multiple Content Types e.g. UG Programs, PG Programs etc.
- Program Compare Configuration
- Add main configuration file
- Add source file
- Program Compare View
- Displays a user-defined view of the PHP search
- The Program Compare is made up of multiple instances of this Content Type
- Program Compare Sidebar (Displays chosen programs)
- Program Compare Save Toggle
- Link to Compare Programs page
- Program Compare Sidebar (Toggles choices)
- 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:
Detail | Value |
---|---|
Name | Program Compare Configuration |
Description | Program Compare Configuration Content Type |
Minimum user level | Administrator |
Element Name | Description | Type | Length | Required |
---|---|---|---|---|
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
Detail | Value |
---|---|
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" |
Detail | Value |
---|---|
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.
Detail | Value |
---|---|
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.
Detail | Value |
---|---|
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.
Enable the following Content Types (either on the Branch or the Section, depending on your requirements):
Content Type | Group | Branch | Section | Disabled |
---|---|---|---|---|
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:
Detail | Value |
---|---|
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) |
Detail | Value |
---|---|
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” |