Search Module Installation Guide

Server Requirements

The Search Module requires PHP between 5.6 and 8.2 to be installed on the webserver that will host the site (refer to Release Notes to confirm which version of the module supports which version of PHP), and on the staging server (if this is a separate server) and ctype, Curl, tokenizer, XMLReader, and mbstring extensions need to be enabled.

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/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 Program Search module
  
  • Configure the Program Search configuration Content Type
• Displaying the Program 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 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
    • 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 Typephar

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

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:

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

Content Layouts

Alternatively

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.

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:

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:

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 "search-source.phar" file to the "PHP Search" Category and select PHAR as the Media Type:

Content Type: Program Search Configuration

Create the Content Type as follows:

*Only required if Program Compare is included

Content Layouts

Create the following Content Layouts on your Content Type (only if Autocomplete is required):

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:

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.

Create a Generate File Navigation Object:

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):

Site Structure: Content Items

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

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 will always publish the file by going to Administration > Set up 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/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:

Content Type: Program Search View

Basic Configuration:

Elements:

Content Layouts

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

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

*Used to pull in the required JavaScript in the page

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

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

Updating the Section

After you create the Content Type you will need to update the Search Section to allow the Program Search View content type.

Add an instance of the view to the Search Section

Add another to create the sidebar

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: JavaScripte

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

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

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

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:

Content Layouts

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

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.

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):

Site Structure: Content Items

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