FrameIt 5.13
Advanced Link Redirector

ReadMe File
Updated 04/28/2000

Please visit http://www.verysimple.com/scripts/ for the most current version of this document.

Support:

Installation Instructions:

How to use FrameIt:

Security Issues:

Misc.:


Support: Frequently Asked Questions

  1. Q. I installed the script, but get a 500 server error when I try to run it.
    A. This happens when the script crashed for an unknown reason. The most common cause of this is the script was transferred in Binary mode instead of ASCII mode. Try transferring the file again, using ASCII mode.

  2. Q. I want to make a custom footer, but still have the "Back" link. How do I do it?
    A. New in version 5.13 is an example custom footer FrameIt.custom.html that uses JavaScript to read the FrameIt variables. See the section about customizing the footer for more info.

  3. Q. I ran setup and got a "404 File Not Found" error. Whats up with that?
    A. There was a minor bug with FrameIt 5.12 setup program. Download the most recent version.

  4. Q. I'm getting "Permission Denied" errors and/or having trouble with file permission?
    A. Check out this page.

  5. Q. I'm having trouble installing/using FrameIt. Where can I go for help?
    A. Post a message in the Technical Support Forum.
Support: Known Issues

Upgrading From Version 5.10 or higher

If you are upgrading from version 5.10 or higher, you don't need to replace all the files or go through the setup again. Simply replace FrameIt.cgi and FrameIt.setup.cgi with the new versions. You do not need to re-run setup, though. All of your previous settings will be retained. As a precaution, you should backup your old version before overwriting it. (Note, if you don't keep FrameIt.cfg in the same directory as FrameIt.cgi, then you'll need to edit the script again to point to the correct directory)

Versions prior to 5.10 will need to run the full setup. FrameIt is backwards compatible with earlier versions, meaning you do not need to re-do your links.

Server Requirements

Installation Instructions: UNIX

  1. Unzip the file FrameIt.zip to a temporary location
  2. Using a text editor, modify the top line of FrameIt.cgi and FrameIt.setup.cgi to specify the location of Perl on your server. ("which perl" at the UNIX prompt may tell you)
  3. Transfer/FTP all the files to your cgi-bin directory using ASCII mode.
  4. Set the following file permissions (Click here for help with file permissions):
    • FrameIt.cgi and FrameIt.setup must be readable/executable by the web browser
    • FrameIt.cfg and FrameIt.log must be set to readable/writable by the web browser
    • All other files must be readable by the web browser
  5. Using your web browser, run FrameIt.setup.cgi (ie, open http://www.yourdomain.com/cgi-bin/FrameIt.setup.cgi) The setup program will walk you through the configuration of the script.
Installation Instructions: Windows NT

  1. Unzip the file FrameIt.zip to a temporary location
  2. Depending on your server configuration, you might need to rename the files FrameIt.cgi and FrameIt.setup.cgi to FrameIt.pl and FrameIt.setup.pl If this is the case, then you will also need to edit the configuration variable in FrameIt.cgi, and use Advanced setup mode)
  3. Transfer/FTP all the files to your cgi-bin or scripts directory using ASCII mode.
  4. Set the following file permissions (Click here for help with file permissions):
    • FrameIt.cgi and FrameIt.setup must be readable/executable by the web browser
    • FrameIt.cfg and FrameIt.log must be set to readable/writable by the web browser
    • All other files must be readable by the web browser
  5. Using your web browser, run FrameIt.setup.cgi (ie, open http://www.yourdomain.com/cgi-bin/FrameIt.setup.cgi) The setup program will walk you through the configuration of the script. NOTE: if you renamed FrameIt.cgi and FrameIt.setup.cgi to FrameIt.pl, FrameIt.setup.pl, then you will need to select advanced setup mode when prompted.
Installation Instructions: Windows 95/98 Personal Web Server

FrameIt does not seem to run on Personal Web Server at this time. See Known Issues for more information.

Creating basic links using default settings

To create your first link, direct your browser to FrameIt.cgi. Unless you specified otherwise during setup, you should see the URL Wizard. The first four fields are those that you would typically use when making a link. The only required field is Url.

Fill in the TextForLink (this is the text or image that will be used for the link), Url (this is the page that will appear in the main body), Text (This is the text that will appear in the footer frame) and the Title (this is the title that will appear in the Browser, above the toolbar)

Any field that you do not fill in will default to whatever you specified in the configuration file during setup.

Click on Test Link to see how your link will look. Use the Back button on your browser to return to the URL wizard. When you are happy with the link, click on Generate Link Code. This will give you the HTML code that you can paste on your page.

Customizing the framed page using the URL Wizard

All of the FrameIt features are available on the URL Wizard. Any field that you leave blank will default to the setting you specified in the configuration file during setup.

All of the variables are pretty much self-explainitory. The following might require a bit of explanation:

Link allows you to specify that the return link go to a different page than the referring URL. For instance, if you have a page of links, however when they click the "Back" it takes them to your main page instead of to the links page.

BodyFrame, FooterFrame and LinkTarget allow you to specify the frameset names and the link target in the footer. This is useful if your site already uses frames and you want FrameIt to work inside your current frame structure.

FooterLocation is straightforward, however there is an option to use "Redirect (no frames)." This allows you to use FrameIt as a regular link re-director. In combination with the logging feature, this can be useful for seeing what links are most popular on your page.

FooterUrl allows you to override the automatic footer and specify your own custom design. To use this, design a custom footer, upload it to your site, then enter the URL of your custom footer.

ConfigFile allows you to specify an additional config file (See section below for instructions) to use for all the settings. This is really useful if you have specified a lot of different variables for your site and you have a lot of links. Instead of creating a lot of really long URLs, you can simply create a custom Config file with the setting that you want, and use that for you links. Another use is to create separate log files for different sections of your site. You can specify a different log file for each config file.

Creating a custom footer

FrameIt allows you to create a custom footer in the event that the regular settings are just not enough for you. One popular reason to do this is to display a banner ad in the footer frame. This can increase your ad stats if provide a lot of links.

Creating the custom footer requires 2 steps.

First, you must design the footer frame. This is just a regular HTML page designed however you like. Upload the footer to your server. For this example: http://www.yoursite.com/footer.html New in FrameIt 5.13 is a example custom footer file (FrameIt.custom.html) that uses JavaScript to read the FrameIt variables.

Next, using the URL wizard, use the FooterUrl field to specify the full URL to your footer page. Using the example above, you would specify http://www.yoursite.com/footer.html as the FooterUrl.

There is one problem that you may run into. That is, when you design your custom footer, you loose some of the features that the FrameIt footer provides. These include the "Back" link, the "Remove Frame" link, etc. To solve this problem, there is an Example Footer included with the script: FrameIt.custom.html. This page uses JavaScript to read the FrameIt variables and display the "Back" link on your custom page. The only catch is that JavaScript enabled browser is required.

Creating a customized config file

To create a custom config file, you will use the FrameIt.setup.cgi script. When prompted, select the "Advanced" setup option. At the next screen, when prompted for the location of the config file, change the name to something new, for example: FrameIt.custom.cfg.

After you click continue, setup will inform you that FrameIt.custom.cfg is not installed. What you need to do is merely create a blank file called FrameIt.custom.cfg and move it to your cgi-bin. FrameIt.setup does not have the capability to create files on your server, so this step must be done manually.

You can proceed with the rest of the setup as normal. If you want, each config file can have it's own log file. This way you can track clicks from different sections of your site in separate log files.

After setup has written to the config file, you can begin using it in your links. Simply enter the filename of the config file in the ConfigFile field on the URL Wizard.

Logging usage and analyzing results

FrameIt can optionally log all click that go through the script. This is not enabled by default, but you can do so by going through the "Advanced" setup.

The logfiles are stored in standard HTTP logfile format, so you can use any program that you like to generate a report. I use a program called Analog, which is quite powerful, but can be tricky to install and use. Many web hosts already have this program, or another similar program installed. You can also find CGI-based log analyzers at CGI-Resources.com

Offering FrameIt as a service to your visitors

FrameIt is written to allow you to use the script privately on your site by default. However, you may decide that you want to offer FrameIt as a service to your web visitors, clients or customers. Using the Advanced setup, you can do this by specifying that you wish to "AllowUnauthorizedd Users."

Additionally, you can specify thatUnauthorizedd users have certain restrictions, or have a mandatory advertisement appear in the footer. This way you can get something in return for the bandwidth and server resources you are donating. The features that are restricted are listed at the bottom of the URL Wizard. (Basically, they are all the features that would allow someone to remove your Ad).

Please read the security section if you intend to do this, as there are certain issues that arise when you enableunauthorizedd users.

Security: Setup and Config file issues

The FrameIt.setup.cgi script is used to modify the configuration file FrameIt.cfg. Since it is possible for you to rename the configuration file, the setup script could be used to overwrite any file on your server that is writable by the web browser. FrameIt.setup.cgi doesn't check the contents of a file before it overwrites. For that reason, it is not a good idea to allow web visitors to run the setup program, even if you have changed the file permission for FrameIt.cfg. A malicious visitor could try to overwrite some of your files, thus causing you to loose data.

The FrameIt.cfg file must be writable by the web browser during the setup process. After you are finished with setup, it is important to change the file permissions so that it is only readable. Neglecting to do this leaves your configuration file vulnerable for other people to change.

Security: Use/Abuse Issues

FrameIt has a lot of setup options to allow you to use it for your personal site, or to allow others to use it on your site. If you use the default setup mode, then it is configured so that only the domains that you specified as "authorized" can use the script. This is the safest way to use the script.

If you decide to provide your script as a "service" to other webmasters and allow "unauthorized" users to use the script, there are some things to be aware of. The primary abuse that I have seen is that a site will use FrameIt on your site to "spoof" another site into thinking that the link came from you and not them. This can be used to rip off advertising banner campaign sites and such.

There are some security measures that you can take to prevent this abuse. The most important is that you enable logging and run a statistical report on the logfile from time-to-time. If you examine the referrers, you will be able to see if any one site is sending a large amount of traffic through the script. If this is the case and you find that they are abusing your script, you can add them to the list of "banned domains"

Version History


© 2000, Jason M. Hinkle