In This Article

• In This Article
• Overview
• Basic System Requirements
• Installing PageFilter
• License Key
• Opening a Site with PageFilter
  • Importing Legacy Configurations
• Configuration
  • Recommendations
    • Debugging
    • Debug Mode
• Adding and Editing Rules
  • Conditions
  • Actions
• Conditions
  • Request URL
    • Options
  • HTTP Header
    • Options
  • HTTP Method
    • Options
• Actions
  • Inject File
    • Options
  • Find and Replace
    • Options
  • Regex Find and Replace
    • Options
  • URL Redirect
    • Options
• Removing PageFilter From a Site
  • Manually Removing PageFilter
• Troubleshooting
  • My changes are not showing up on my site!
  • My site appears broken.
  • My site has a yellow bar at the top with a PageFilter warning.
  • I have a problem that is not listed here.
• Release Notes

Overview

PageFilter is an add-on product to your RiSE or custom website that enables easy-to-configure text replacement and JavaScript /CSS injection. It allows you to customize or remove elements that would not normally be editable via the site's standard configuration screens. 

Basic System Requirements

The following system specifications are required to successfully run PageFilter:

• Windows 7 or higher
• Windows Server 2008 or higher
• An ASP.NET website with the following:
  • Running on IIS 7 or higher (IIS 6 is not supported)
  • Running under the Microsoft .NET Framework 4.0 or higher

Installing PageFilter

Note: It is best practice for all users to be on the same version of PageFilter.

1. Download PageFilter from https://customer.csiinc.com to your workstation.
   • You will need your CSI Website User Name and password. If you do not have this information contact support@csiinc.com
2. Unzip the folder, and navigate to the unzipped folder.
3. Right mouse click on the Setup.exe and run as Administrator
4. You will be prompted, asking if you want to allow the program to make changes to your computer. Click Yes
5. The Setup Wizard will open. Click Next.
6. The license Agreement will display. Select "I accept..." and Click Next.
7. Verify the default installation folder. Click Install.
8. A screen will then show, displaying the progress of the install.
9. A screen will confirm that PageFilter has been successfully installed. Click Finish.

License Key

PageFilter is licensed per domain. The license key you receive from CSI contains one or multiple domains on which Page Filter is authorized to run (i.e. "mysite.org", "mysite.net", and "mysite.com" as well as subdomains such as "shop.mysite.org" and "members.mysite.org").

If you enable PageFilter on a site with a domain that is not licensed, a warning message will appear at the top of each page if you have the "Enable Licensing Warnings on Website" box checked. If you own the domain you are trying to run PageFilter on, and you receive the license warning on your site, please contact CSI and we will issue you a new license key with the new domain included.

If you are unsure if you have an expired key, underneath the "License Key" field, there is a "License status" feature that allows you to see if the key is active, expired, or about to expire.
Note: Any site accessed via localhost or 127.0.0.1 suppresses the domain check. PageFilter will always run "licensed" when the site is accessed via localhost/127.0.0.1.

Opening a Site with PageFilter

1. Navigate to Start > All Programs > CSI Programs and click "PageFilter".

   PageFilter must be installed per-site in order for it to work. Each site has its own separate configuration. Your PageFilter license covers unlimited sub-sites/configurations as long as the base domain matches (i.e. "myorganization.org"). Contact CSI if you would like to add additional domains to your license key.

   To open a new or existing site in PageFilter, you will need to locate the site's web.config file. 

2. In PageFilter, click Open.
3. Select your web.config file (i.e. C:\Program Files (x86)\ASI\IMIS20APP\Net\web.config)
   1. If this is the first time you have opened this site with PageFilter…
      1. A prompt will appear asking if you would like to make changes to the web.config. Click Yes to install PageFilter onto this site.

      2. PageFilter should show a message saying that the installation was successful. You are now ready to configure PageFilter for your site.

         To learn more about what PageFilter does during the installation process, see Uninstalling PageFilter. 

   2. If this is not the first time you have opened this site with PageFilter…

   1. PageFilter should automatically load the configuration for that site.

Importing Legacy Configurations

PageFilter 2 allows you to import your PageFilter version 1.x configuration files. Some items to note about the import/conversion process… 

• Each "rule" or "line" from PageFilter 1.x will be imported as a separate group in PageFilter 2. 
  • i.e.: You have 40 lines/rules in PageFilter 1.x. After importing this configuration file, you will have 40 tab groups in PageFilter 2. 
• Each tab is labeled "Legacy Rule 1", "Legacy Rule 2", and so on. This is because PageFilter 1.x did not allow the naming of rules. It is highly recommended that, after importing the configuration file, you name each group something meaningful. 
• Rules that are imported from PageFilter 1.x may contain commonalities that can be optimized in PageFilter 2. For example, if rules 1-10 all act on the same page on your site, (i.e. "_Content_About.aspx", you may choose to combine all of the rules for that page, so that your end result is a single condition (which matches that page) and 10 rules that will be applied to that page). 
• Any "stored procedure" actions will not be imported. PageFiler 2 does not contain functionality to call a stored procedure. These rules will be ignored if they exist in 1.x configuration file. 

Rules imported from PageFilter 1.x, when edited, may contain a "[Legacy]" label, and a note as pictured below: 

In this case, PageFilter 2 contains new/updated logic which processes that particular rule or action more efficiently, so converting to the new rule is strongly recommended. Replacement rules are named the same as their legacy counterparts, so you should upgrade from "[Legacy] Request URL" to "Request URL", and "[Legacy] Find and Replace" to "Find and Replace" and etc. 

Configuration

The PageFilter configuration screen is comprised of the following options:

1. Configuration file area
   1. Open…: Allows you to browse for a site (web.config file) and open it in PageFilter
   2. Recent…: Allows you to view and open a list of recently accessed sites
   3. Close File: Closes the file you have open
2. Rules Editor
   1.  Add Rule: Adds a new rule to the site (see Adding and Editing Rules)
   2.  Edit: Edits the currently selected rule

   3.  Delete: Deletes the currently selected rule.

      Warning: This cannot be undone!

   4.  Clone: Creates a copy of the currently selected rule.

3. Debugging: Allows you to enable or disable debugging, and choose the debugging mode. See Debugging for more information.
4. Caching: Allows you to enable or disable configuration caching. The configuration is stored in the Cache object of the webserver.
   1. Cache Lifetime: The amount of minutes allotted to cache the configuration. After this time has passed, the configuration is re-read from disk. The value here must be between 0 and 1000.
5. Licensing: This area is only expanded if there is no license key entered. The license key text area is where you paste your license key obtained from CSI upon purchase of PageFilter (or upgrade from PageFilter 1). When you check the "Enable Licensing Warnings on Website" box, when your PageFilter license expires, you will see a warning on your affected pages.

Recommendations

Caching should be enabled on a production site if the PageFilter rules on that site are not actively being edited.

Debugging

Debugging should be enabled only when developing a site or creating new rules. Before enabling debugging, please be sure to read through this entire section.

Debug Mode

HTML: Prints out an HTML comment at the top of every page with PageFilter debugging information.

Headers: Prints out minimal debugging information into a special HTTP header called X-PageFilter-Debug. This can be viewed in the "Network" tab of the web inspector of a browser. To read this value, take the contents of the header, and replace ";" with a newline character in a text editor.

When you activate debugging, there will be a warning, such as the one below, displayed in the Options section.

Enabling debug mode can have adverse side effects on your website, and on the iMIS desktop. The reason for this is because it injects HTML comments into the response sent to the browser which are designed to print out useful information when working with PageFilter. Unfortunately, there comments can cause some components and dynamic scripts to stop working.

We have noticed the following issues when debug mode is enabled:

• iMIS desktop plus icons ("+") not expanding the menu
• RiSE panels (such as the Address panel on a profile) not being populated correctly due to the way the content is loaded (it is loaded asynchronously via Javascript).

It is strongly recommended that, unless you are actively working to create or edit rules in PageFilter, that you disable debugging.  

Adding and Editing Rules

Rules are displayed as tabs in the main configuration window.

To create a new rule…

1. Click + Add Rule.
2. The Rule Editor window will appear. Give your rule a name in the Rule Name field
3. Next, determine whether or not you want this rule to be enabled or not using the Is Enabled checkbox. You can always change this later.

Conditions

Next, add one or more conditions to your rule. Click + Add Condition to define a condition.

See the Conditions for details about each condition type.

Use the Edit and Delete icons to edit and delete conditions, respectively.

Actions

To add one or more actions to your rule, click + Add Action.

See the Actions for details about each action type.

Use the Edit and Delete icons to edit and delete actions, respectively. 

Finally, click OK to save your new rule. The rule will appear in the tab list on the main configuration window.

Conditions

PageFilter conditions check various properties of an incoming HTTP request to see if one or more conditions match.

Request URL

This condition checks the requested URL of the page.

This condition acts on the relative URL of the page. Relative URLs are everything after the domain and before any special characters (i.e. "?", "#"). Each starts with a leading forward slash ("/"). 

For example, with this URL:

http://myorganization.org/Pages/MyAccount.aspx?ID=24#account-details

The relative URL that PageFilter checks is:

/Pages/MyAccount.aspx 

Options

Is Exactly

Must match the requested relative URL exactly.

Starts With

Matches if the requested URL of the page starts with what is entered. This works well for matching entire folders or areas of sites, like "/MembersOnly/". Note: 

Matches Expression

Matches if the requested URL matches the specified regular expression.

HTTP Header

This condition checks the incoming HTTP request headers.

Options

Exists

Checks to see if the specified header exists in the request.

Does Not Exist

Checks to see if the specified header does not exist, or is empty/blank.

Is Exactly

Checks to see if the specified header matches the value entered exactly. This operation is case-insensitive. If you check Negate, the meaning of the condition changes such that it will match on all values except the one entered (i.e. "Is anything except the entered value").

Matches Regular Expression

Checks to see if the header matches the specified regular expression. 

HTTP Method

This condition checks the HTTP request method type. The two most familiar method types are "GET" and "POST".

Options

HTTP Method

Select the HTTP method verb to match on.

Negate

Will match on all other method types except the one selected.

Actions

If all conditions (or any condition if "Match on Any" is checked) are true, all actions will be run on the page. Actions typically modify the HTML output of the page in some way or another.

Inject File

This action injects a CSS or Javascript file dynamically into the page at a specified point.

Options

Source file

The path of the file to inject. This can be a relative or absolute path. This is used directly in the injected <script> or <link> tag.

File type

The type of file to inject. Currently, CSS files and Javascript files are supported.

Location

Where in the page to inject the file. Since order matters with CSS and Javascript files, the location of the injected file can make a difference. Currently, the following self-explanatory options are included:

• Beginning of Head
• End of Head
• Beginning of Body
• End of Body

Find and Replace

This action finds and removes/replaces/inserts text on the page.

Options

Text to find

The text to find on the page.

Remove

Removes the text entirely (replaces it with a blank value).

Replace

Replaces the find text with this text.

Insert Before

Keeps the find text, and inserts the specified text before it.

Insert After

Keeps the find text, and inserts the specified text after it.

Regex Find and Replace

This action is functionally equivalent to the "Find and Replace" feature, except it allows for regular expression matching and replacement.

Options

Find

The regular expression for which to search.

Replace

The regular expression that will be replaced. Replacement characters ($1, $2, etc.) are supported.

Replace with nothing (blank)

Removes the text that was found, and replaces it with a blank value.

Regex Options

• Case sensitive: Makes the find operation case-sensitive. By default it is case-insensitive.
• Singleline: (Advanced option) A regex option which changes the meaning of the "." character to include matching on line breaks.

URL Redirect

This action redirects the user to the specified destination page.

Options

Redirect URL
The URL to redirect to. Can be a relative URL (i.e. "MyOtherPage.aspx"), a relative URL to the site (i.e. "/OtherArea/OtherPage.aspx"), or a full URL (i.e. "http://google.com/").
Permanent Redirect
This option sends an HTTP 301 code as the redirect. This tells search engines that the redirect is permanent (i.e. the old page should be ignored for the foreseeable future).
Temporary Redirect
This option sends an HTTP 302 code as the redirect. This tells search engines that the redirect is temporary (i.e. an "Under Construction" page), and that the old page should not be forgotten about.

Removing PageFilter From a Site

If you are simply trying to remove PageFilter from a specific site, follow the steps below:

1. "Open" the site in PageFilter
2. Click on the ? button and select "Remove PageFilter from this site…"
   • This will undo the changes from the web.config file and remove the DLL from the /bin/folder.

3. You will receive a prompt, asking if you would like to create another web.config backup.

   A backup is created when PageFilter is installed, so clicking "Yes" would result in two backups. You also have the option to remove both backups. 

Manually Removing PageFilter

If the above process for your site does not work, follow these steps:

To uninstall PageFilter from a site: 

1. Locate your web.config file of the site where you would like to remove PageFilter.
2. There should be a "web.config.pfbackup" file in the same location as your web.config file. This file was created by PageFilter when it installed itself onto the site. It is a snapshot / backup of your web.config file before PageFilter modified it.
3. Delete your web.config file (or rename it to something like "web.config.withpagefilter").
4. Rename "web.config.pfbackup" to "web.config".
5. Navigate to the /bin/ folder.
6. Find "PageFilterModule.dll" and delete it, or rename it so that it does not have a ".dll" extension (i.e. "PageFilter.dll.old").
7. PageFilter is now uninstalled from your site. 

Troubleshooting

My changes are not showing up on my site!

Verify that caching is not enabled. Even if caching was enabled and you disable it, you must wait the entire cache time (in minutes) before the configuration file will be read/reloaded again.
If caching is not enabled, enable HTML debugging and view the source of the page. Ensure that your rule is listed under the "Matching rules for this page" section. If it is listed under that section, that means your conditions are set up correctly, but your "find text" in one or more of your rules is likely incorrect.

My site appears broken.

Disable your rules, one at a time, until your site starts working again. The rule you just disabled is your culprit rule and is causing your site to break. Check to make sure it isn't finding and replacing some HTML or script text.
If all of your rules are disabled and your site is still not working, please contact CSI and submit a ticket. Be sure to include the site's URL and a screenshot of the About window in PageFilter. (Click the ? icon in the upper-left, and select "About PageFilter". Press Alt+Prt Scr to take a screenshot of this window. Include this screenshot in your e-mail).

My site has a yellow bar at the top with a PageFilter warning.

This typically indicates that PageFilter is not licensed for this particular site/domain, or the license expired. Contact CSI, include the exact warning text, and we will issue you a replacement license key to remove the warning from your site.

I have a problem that is not listed here.

If you have any other issues with PageFilter, please contact CSI Support at support@csiinc.com. Tickets are normally responded to within 1 to 2 business days after they are submitted.

Release Notes