HeliPlug: http://www.helical-library.net/coded/plugboard.asp
------------------------------------------------------------

Thank you for downloading HeliPlug! Please follow these instructions and you should soon have a fully-functioning ASP-based 'plugboard'.

------------------------------------------------------------

Server Requirements

 - Support for ASP 3.0.
 - Access to the server's file system via FileSystemObject. This is a standard function of ASP but is disabled by some free hosting services, so if you're using a free ASP host, please check its FAQ.

------------------------------------------------------------

Files Included in this Download

 - plug_config.asp
 - plug_login.asp
 - plug_edit.asp
 - plug_code.asp
 - plugboard.asp
 - plugboard.css
 - plugboard.txt
 - banned.txt

------------------------------------------------------------

Installing HeliPlug

1. Unzip all of the plugboard files.

2. Open plug_config.asp in a text editor. This file contains script variables that you can edit in order to customise your plugboard. 

   The variables strName and strPassword hold a username and password for logging into the plugboard's editing panel. The default for both is "Admin". Change the values of strName and strPassword to something personal to you.

   Next in plug_config.asp are four variables used to configure the plugboard:

   - inNoButtons is the number of plugs you want to be displayed on the plugboard. The default is 12 (making three by four rows of buttons). Choose an even number to create a square or rectangular button wall.

   - intButtonWidth is the width (in pixels) of the buttons that will be plugged. The default is 88.

   - intButtonHeight is the height (in pixels) of the buttons that will be plugged. The default is 31. If you want e.g. a plugboard of 50 by 50 pixel buttons, change both intButtonWidth and intButtonHeight to 50.

   - blnNewWindows is a Boolean (true or false) variable that controls whether plugged sites will be opened in a new browser window. The default is False. If this variable is set to True, the script will put a 'target' attribute in the links to the plugged sites. Since the target attribute is deprecated in Strict forms of HTML, leave blnNewWindows set to False if you wish to follow the strict standard.

3. Upload all of the files to a directory on your Web server. Choose the directory containing the page on which you want the plugboard to appear, and make sure that all of the plugboard files are in the same directory.

4. Now edit whichever page on your site is going to display the plugboard. This page must have the file extension .asp. (If your existing pages have different extensions and you don't want to rename them, you could create an .asp page simply for the plugboard and then load that page into your main site using a frame.)

   Add this code to the <head> section of your page: 
    <!--#include file="plug_code.asp" -->
   
   Then add this code wherever on the page you want the plugboard to appear:
    <!--#include file="plugboard.asp" -->

5. The style sheet file plugboard.css contains style rules that are vital for controlling the appearance of the plugboard. Either link this file directly to your plugboard page (<link rel="stylesheet" type="text/css" href="plugboard.css" />), or copy and paste the key CSS rules into your existing style sheet.

  The important CSS rules for formatting the plugboard are #plugboard, #plugboard li, fieldset, img and label. (The other, more general rules in plugboard.css have been included to make the admin pages look prettier.)

6. Upload the completed plugboard page to your server and then pay it a visit with your browser. If all has gone well, you should see an arrangement of 'HeliPlug' buttons and a form. (If you set the number of plugs in plug_config.asp to a number higher than 12, there may be fewer buttons than the number you specified. This isn't a problem. The default data file contains only a limited number of placeholder entries, but the plugboard will expand to the specified size as your visitors add their buttons.)

   Enter a test plug to check that the board is working correctly.

--------------------------------------------------------------------

Editing the Plugboard

Sometimes you will want to remove a broken link or to delete a plug for some other reason. HeliPlug offers a means of editing which basically involves going into the raw source of the data file, deleting what needs to be deleted and then writing the altered file back to the server.

1. Browse to plug_login.asp, where you will be prompted for a username and password. Enter the name and password that you recorded in plug_config.asp.

2. After logging in, you will be taken to plug_edit.asp, where there is a form textarea displaying the current contents of the data file. Any deletions can be made within the textarea and then submitted. Some notes on how best to do this are on the page itself.

   When full, the data file will hold two entries more than your specified size for the plugboard. This is to provide a fallback if you delete one or two entries - an older plug can come back on to the board and prevent the board from looking uneven.

---------------------------------------------------------------------

Banning sites

If, because of spamming or any other reason, you wish to block particular sites from being plugged, you can create a list of blocked URLs in the file banned.txt. Open banned.txt in a text editor, type in the URL of the banned site, and re-upload to your server. If you enter more than one URL, type each on a new line. For example:

bannedsite.com
bannedsite2.net
bannedsite3.org

The script searches *inside* the URL submitted by a plugger for any matches with an entry in banned.txt. This means that if you list your entries in the form of core URLS like 'bannedsite.com' (without the 'www' or a trailing slash), you don't have to worry about matching exactly what the user enters - 'bannedsite.com', 'www.bannedsite.com' and 'bannedsite.com/index.html' will automatically be matched. The disadvantage of this is that e.g. 'hostee.bannedsite.com' will also be matched, so exercise caution in banning a domain.

---------------------------------------------------------------------

Other Notes

All of the HTML code for creating the plugboard links - the URLs of the sites and the buttons, the image height and width attributes etc. - is hard-written into the data file when each plug is made. Because of this, the configuration of the links can't be changed dynamically. E.g. if you decide mid-way to change the board from using 88 by 31 buttons to using 100 by 35 buttons, editing the relevant variables in plug_config.asp, only the buttons plugged after the edit will display in the new size. The older buttons will remain at 88 by 31 until either they're pushed off the board or you go in to edit them manually. (Another way to speed their removal is to reset intNoButtons to a small number for a while.)

---------------------------------------------------------------------

Feedback

Please send any comments to gemma@helical-library.net.