Knowledge Base

Redirect Module Installation Guide

Last Modified:
13 May 2020
User Level:
Administrator +

This step by step guide will help you get up and running with the Redirect Module. The Redirect Module (also referred to as the Smart 404 Page) is code that is added at the top of the 404 page to handle redirects.

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

Server Requirements

The Redirect Module requires PHP 5.3+ to be installed on the webserver that will host the site, and on the staging server (if this is a separate server). Also, the following extensions should be enabled:

You will also need to configure your webserver for a 404 page if it hasn't already been done.

Create the 404 Page

To use the Redirect Module, your 404 page needs to be a page that is generated by Terminalfour CMS. The easiest way to do this is to create a normal page on your site, which publishes to /404 and configure Apache / IIS to use this page as the 404 page.

Create the Section

If it doesn't already exist, create a Section to manage your 404 page.

You may show/hide Sections from navigation as desired, but it would normally be hidden from navigation.

Name

404

Show in navigation

No

Content Types Tab

Enable the relevant Content Types on the Section.

Page Layouts Tab

Apply the relevant Page Layout for the page.

Add Content

Add content to your 404 page, explaining that the user has entered a URL that doesn't exist. Consider adding links to commonly requested pages, a search box, etc.

Publish and Test

Publish your channel and go to /404 and check that your page has published and looks correct.

Configure IIS / Apache

Ensure that Apache / IIS on your web server is configured for your 404 page to be the URL that you've created. For example:

ErrorDocument 404 /404/

If Terminalfour hosts your servers for you, contact your support team and they will configure Apache / IIS for you!

If you have a staging site, it is useful to do the same configuration on the staging server too.

To check that this is working correctly, navigate to a URL on your website that doesn't exist, and ensure that your 404 page is displayed.

Required Assets

You must enable the following in your installation. Further details on each asset are provided if required.

File Extensions

This file extension must be allowed on the Channel with which you’re using the Redirect Module.

Extension Description
PHP Required to run the Redirect Module scripts.

Media Types

PHP Media Type must be created if it does not already exist and must be set to always publish on the Channel with which you’re the Redirect Module.

TypeDescription
PHP Required for PHP file 

Media Files

The required files can be downloaded from the Terminalfour Community Site which requires authentication through the product.

TypeDescription
PHP Main Library The main PHP library file

Lists

TypeDescription
Yes This will be used by the Redirect Module and Redirect Content Types to configure some options.

Navigation Objects 

NameDescription
get PHP Head A Related Content Navigation Object used to retrieve the PHP CSV Redirects Module PHP Code.
PHP Redirects: create CSV Lines A Generate File Navigation Object used to create the CSV file
Only required if you are managing your redirects by adding individual Content Items for each redirect (as opposed to uploading a CSV file).
PHP Redirects: get CSV Lines A Publish to one File Navigation Object used to create a CSV file from Redirects for the CSV Redirect PHP code.
Only required if you are managing your redirects by adding individual Content Items for each redirect (as opposed to uploading a CSV file)

Content Types

NameDescription

CSV Redirect Module

Stores the code and configuration for the Redirect Module

Redirect

If you are managing your redirects by adding individual Content Items for each redirect (as opposed to uploading a CSV file), then create a Content Type for the Redirects. 

Section

NameDescription
404

Contains the Redirect Module (including the CSV of redirects), and individual redirects (if using content items to create redirects)

Page Layout

No specific Page Layout is required. It will be necessary to edit the header of the Page Layout used for the 404 Page, adding the Related Content Navigation Object for Redirect Module PHP Code.

Create Required Assets

File Extensions: PHP

If you haven't already, set up PHP as a file extension and enable the extension on your Channel.

Name PHP
Description This is a PHP file extension
Extension php

Remember to enable the Channel to Publish this file extension and rebuild the cache.

Media Layouts

Path Content Layout

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 input field add the following:

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

Screenshot of the Content Layout Code for Media System Content Type

Media Type

When the Content Layout has been created, go to System Administration > System Settings > Media Library and, in the Media Types tab, add the following Media Type:

PHP File

If it does not already exist, create a PHP Media Type and associate the "path/*" Content Layout with it:

Screenshot of the PHP Media File with associated Content Layout

Name PHP File
Permitted file extensions php
Maximum file size 0
Media type options Parse for T4 tags
Media Content Layout path/* (default)

Media Files

Main PHP File

In the downloaded zip, in the media-library directory, you will find a file named Smart_404_as_Content_Layout.php. This should be uploaded into your Terminalfour Media Library, selecting the Media Type as PHP File.

Media Type PHP File

Lists

If it does not already exist, create a List with one List item named "Yes".

List Name: Yes

List Items

NameValueSelectedSublist
Yes yes No   

Content Types

The following Content Types should be created. Associated Content Layouts are also listed.

Redirect Module

Create a "Redirect Module" Content Type using the following General options (anything not mentioned may be left at default):

Name: Redirect Module

Description: Content to handle the Redirect Module Smart 404 PHP Code

NameDescriptionTypeMax SizeRequired

Main Library

Link to the Main Library PHP File

Media

100 Yes

CSV File

Selects the CSV file.

  • The first column contains the URL that is redirecting (From URL)
  • the second column is the URL that the redirect goes to (To URL)

This element is only required if you are managing your redirects in a CSV File. If you are adding individual redirects using the Redirect Content Type, this element can be removed.

File

99999 Yes

Ignore Query

In the From URL always ignore the variable passed via the query

Check Box (Yes)

80 No

Exact Match

If selected it will only redirect with an exact match, otherwise, it will check if the From URL is 85% close one of the URLs in the List of From URLs provided

Check Box (Yes)

80 No

text/php-head Content Layout

Name

text/php-head

File extension

PHP (.php)

Syntax type

PHP

Content layout code

In the downloaded zip, use the code in with-redirect-content-type/content-types/php-csv-redirects-module/php-head.php

text/html (Main Channel Layout) Content Layout

This layout is only required if you are managing your redirects in a CSV File. If you are adding individual redirects using the Redirect Content Type, this layout can be ignored.

This is the default layout that is used by the channel - most often this is text/html but that may vary based on your Channel settings.

Name

text/html

File extension

Default

Syntax type

HTML/XML

Content layout code

In the downloaded zip, use the code in with-redirect-content-type/content-types/php-csv-redirects-module/html.html
This content layout contains a Navigation Object. For the moment leave it as it is. It will be replaced by the T4 Tag for the PHP Redirects: create CSV File Navigation Object.

text/csv-ptof Content Layout

This layout is only required if you are managing your redirects in a CSV File. If you are adding individual redirects using the Redirect Content Type, this layout can be ignored.

Name

text/html

File extension

Default

Syntax type

HTML/XML

Content layout code

In the downloaded zip, use the code in with-redirect-content-type/content-types/php-csv-redirects-module/csv-ptof.csv
This content layout contains a Navigation Object. For the moment leave it as it is. It will be replaced by the T4 Tag for the PHP Redirects: get CSV Lines Navigation Object.

Redirect Content Type

If you are managing your redirects by adding individual Content Items for each redirect (as opposed to uploading a CSV file), then create a Content Type for the Redirects.

Name: Redirect

Description: Create a redirect from a URL to another Section/Content Item on the site.

NameDescriptionTypeMax SizeRequired
Enter the short/original URL URL that requires to be redirected (do not include the domain) Plain text 200 Yes
Include Branch for original URL If checked, all URLs that start with the short/original URL will follow this redirect rule. If left unchecked, only the URL specified will redirect. CheckBox (Yes) 80 No
Select the target Section/Content   Section/Content link 200 Yes
Include Branch for target If checked, and there is a wildcard on the “from URL”, the redirect will consider the pattern of the “from URL” and append that to the target URL. Check Box (Yes) 80 No

Content Layout

This layout is used by the PHP Redirects: get CSV Lines Navigation Object, to create a CSV file of the redirects.

Name

text/csv-line

File extension

Default

Syntax type

HTML/XML

Content layout code

In the downloaded zip, use the code in with-redirect-content-type/content-types/redirect/csv-line.php

Navigation Objects

get php Head

A Related Content Navigation Object is used to get the PHP Code and place in the header of the Page Layout

Name

get PHP Head

Fetch method

Use current

Content layouts

Use alternate content layout

Content layout

text/php-head

Go to the Page Layout used for your 404 Page and add the Navigation Object in the header before anything else in your Page Layout.

PHP Redirects: create CSV File

If you are managing your redirects by adding individual Content Items for each redirect (as opposed to uploading a CSV file), then create a Generate File Navigation Object that is used to create the CSV file.

Name

PHP Redirects: create CSV File

File name

redirects

File extension

csv

Output directory

Use the current directory

Content layout

text/csv-ptof

Update the Navigation Object ID in the Redirect Module Content Type's text/html layout.

PHP Redirects: get CSV Lines

If you are managing your redirects by adding individual Content Items for each redirect (as opposed to uploading a CSV file), then create a Publish to one File Navigation Object that is used to create a CSV file from Redirects content for the CSV Redirect PHP code.

Name

PHP Redirects: get CSV Lines

Content Type Names

Redirect

Start Section

Use current Section

Number of levels to recurse

1

Show Hidden Sections?

Yes [X]

Surrounding Page Layout

(No Page Layout)

Use Alternate Content Layout?

Yes [X]

Content layout

text/csv-line

Update the Navigation Object ID in the Redirect Module Content Type's text/csv-ptof layout.

Create the CSV File of Redirects

If you are using a CSV file for the redirects, create a CSV File. This is structured as two columns, one for the From URL and one for the To URL. This may look similar to:

/business/,/school-of-business/
/about/,/about-us/
/2020/,/news/news-archive/2020/

Wildcard Characters

It is possible to use a wildcard character in the From URL, To URL, or Both URLs (although specifying it in the To URL without specifying in the From URL will be nonsensical).

The following scenarios illustrate the functionality of wildcards within the redirects (where * is used as the wildcard):

From URLTo URLUser VisitsUser Redirected To
/school-of-business/* /business/* /school-of-business/about/this/school/ /business/about/this/school/
/school-of-business/about/* /business/* /school-of-business/about/this/school/ /business/this/school/
/school-of-business/about/* /business/more/about/* /school-of-business/about/this/school/ /business/more/about/this/school/
/school-of-business/* /business/ /school-of-business/about/this/school/ /business/
/school-of-business/ /business/ /school-of-business/about/this/school/ The 404 page
/school-of-business/ /business/ /school-of-business/ /business/
/school-of-business/ /business/* /school-of-business/ /business/  (if there is a wildcard at the end of the From URL but not the To URL, it is ignored on the To URL, since that wouldn't make sense)
/school-of-business/ /business/* /school-of-business/about/this/school/ The 404 page  (the page being requested by the visitor does not match the From URL)
*/school-of-business/* */business/* /schools/school-of-business/about/this/school/ /schools/business/about/this/school/
*/school-of-business/ */business/ /schools/school-of-business/about/this/school/ The 404 page (the page being requested by the visitor does not match the From URL)
*/school-of-business/* */business/ /schools/school-of-business/about/this/school/ /schools/business/
*/school-of-business/*.html */school-of-business/*.php /schools/school-of-business/about/mark.html /schools/school-of-business/about/mark.php

Create Content

Enable the Content Type

Enable the Redirect Module Content Type on your 404 Section:

Content TypeBranchGroupSection Disabled
Redirect Module   No Yes No

Create Content Item

Add content to the 404 Section as follows:

Content Type

Redirect Module

Name

Redirect Module

Main Library

Select the PHP file that was uploaded to the Media Library

CSV file

Select the CSV File of redirects

Ignore query

Select whether you would like to ignore the variable passed via the query
For example, if the From URL is /events and a user navigates to /events?page=1, should the user be redirected?
If yes, check this option to Ignore query.
If not, leave this option unchecked.

Exact Match

If selected it will only redirect with an exact match, otherwise, it will check if the From URL is 85% close one of the URLs in the list of From URLs provided.
For example, if there is a From URL of /about-us and a user navigates to /aboutus, if this option is checked, the user will be redirected to the relevant To URL. If unchecked, the user will not be redirected, since it is not an exact match.

If you are creating redirects using the Redirect Content Type, create a test redirect in the 404 Section:

Content Type

Redirect

Name

Test Redirect

Enter the short/original URL

/testingredirect

Include Branch for original URL

Unchecked

Select the target Section/Content

Select a Section within the same channel

Include Branch for target

Unchecked

Publish and Test

Publish your channel and navigate to a page that doesn't exist on your site - ensure that you can see your 404 page.

If using the CSV file to configure redirects, navigate to one of the From URLs specified in your CSV file, and ensure that you are redirected to the appropriate To URL. Or, if using the Redirect Content Type, navigate to /testingredirect and ensure that you are redirected to the Section that was selected as the target Section.

Back to top