PageFilter
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.
- 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
- Unzip the folder, and navigate to the unzipped folder.
- Right mouse click on the Setup.exe and run as Administrator
- You will be prompted, asking if you want to allow the program to make changes to your computer. Click Yes
- The Setup Wizard will open. Click Next.
- The license Agreement will display. Select "I accept..." and Click Next.
- Verify the default installation folder. Click Install.
- A screen will then show, displaying the progress of the install.
- 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
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.
- In PageFilter, click Open.
- Select your web.config file (i.e. C:\Program Files (x86)\ASI\IMIS20APP\Net\web.config)
- If this is the first time you have opened this site with PageFilter…
- A prompt will appear asking if you would like to make changes to the web.config. Click Yes to install PageFilter onto this site.
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.
If this is not the first time you have opened this site with PageFilter…
PageFilter should automatically load the configuration for that site.
- If this is the first time you have opened this site with PageFilter…
If you have recently updated PageFilter to a new version, when you open a site in PageFilter, it will automatically update your PageFilter module DLL in your site with the new version.
The Recent… menu provides quick access to the five most recent web.config files that were opened with PageFilter. To quickly open a recent file, click Recent, then select the file you would like to open.
Now you are ready to configure PageFilter rules and options.
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:
- Configuration file area
- Open…: Allows you to browse for a site (web.config file) and open it in PageFilter
- Recent…: Allows you to view and open a list of recently accessed sites
- Close File: Closes the file you have open
- Rules Editor
- Add Rule: Adds a new rule to the site (see Adding and Editing Rules)
- Edit: Edits the currently selected rule
Delete: Deletes the currently selected rule.
Warning: This cannot be undone!
Clone: Creates a copy of the currently selected rule.
- Debugging: Allows you to enable or disable debugging, and choose the debugging mode. See Debugging for more information.
- Caching: Allows you to enable or disable configuration caching. The configuration is stored in the Cache object of the webserver.
- 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.
- 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.
Making changes to items 3, 4, or 5 above requires you to press Save Options in order to save the configuration.
You do not need to press this button after making changes to any rules – these changes save and take effect immediately.
Recommendations
Caching should be enabled on a production site if the PageFilter rules on that site are not actively being edited.
Caching and Debugging will not work at the same time. Debugging overrides caching, so if both are enabled, debugging will work, but caching will not work until debugging is disabled.
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…
- Click + Add Rule.
- The Rule Editor window will appear. Give your rule a name in the Rule Name field
- 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.
By default, all conditions must match ("AND" logic) before the rules will be processed.
If you check the "Match on Any" checkbox, if any one condition is true ("OR" logic), the rules will be processed.
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.
RiSE Note
iMIS RiSE makes heavy use of URL aliasing. The URL in your browser is likely not the "real" URL.
To get the correct URL that PageFilter will use, enable HTML debugging and check the debug information printed in the source of the page. See the Troubleshooting for more information.
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.
IMPORTANT!
This action works on the entire page, including the HTML source! If you find and replace a simple word such as "Value", and your page stops functioning, it is likely you have replaced some unwanted HTML or Javascript code. Try narrowing down your "Find" text to just what you want on the page, and be sure that there are no other instances of that text on the page anywhere else (View the source, and find/Ctrl+F for the text you for which you are searching. Ensure there are no other instances of the text that you do not want to find/replace.)
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.
No other actions should be used with a URL redirect. They will not have any effect on the page. Because the page is being redirected to a new page, the old page is discarded / not used, therefore any operations on it will not be seen.
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:
- "Open" the site in PageFilter
- 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.
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:
- Locate your web.config file of the site where you would like to remove PageFilter.
- 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.
- Delete your web.config file (or rename it to something like "web.config.withpagefilter").
- Rename "web.config.pfbackup" to "web.config".
- Navigate to the /bin/ folder.
- Find "PageFilterModule.dll" and delete it, or rename it so that it does not have a ".dll" extension (i.e. "PageFilter.dll.old").
- 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
Version | Date | Notes |
---|---|---|
2.0.900 | 3/23/2017 | Added scroll bars to actions and conditions controls. (CW 66546) |
2.0.872 | 10/26/2015 | Added warning about website impact when debugging is enabled. |
2.0.866 | 4/22/2015 | Improved PageFilter rules when dealing with certain content types |
2.0.864 | 3/9/2015 | Fixed an issue where PageFilter was mistakenly acting on certain content types |
2.0.862 | 2/20/2015 | Allowed PageFilter to run unlicensed from the "localhost" domain |
2.0.830 | 2/4/2015 |
|
2.0.791 | 1/27/2015 |
|
2.0.750 | 12/11/2014 | Added product icon |
2.0.737 | 11/11/2014 | Added Recent menu |
2.0.730 | 11/4/2014 | Initial release of PageFilter |