AutoList: Frequently Asked Questions

Although AutoList is aimed at professional web masters and LAN managers, we recognise that the flexibility AutoList offers may mean that even professionals are unaware of all of AutoList's various features, and how to use them. This page answers some of the questions you might have about the product.

You may also like to read our Introduction to AutoList.

AutoList: Frequently Asked Questions


Is AutoList easy to install?

Yes. AutoList is a collection of CGI scripts written using the popular scripting language perl 5, together with some JavaScript fragments generated by those scripts (which you don't have to worry about). There is nothing that makes the AutoList scripts any harder to install than any other CGI scripts. Your web hosting company will be familiar with the process and should be able to give you all the information you require.

In general, they will sort four things out for you.

  1. Your site must be equipped for running CGI scripts. Almost all web servers are capable of running CGI scripts, but some hosting companies won't let you install your own scripts, because badly written scripts can sometimes introduce security loopholes into their systems.

  2. When you copy a file onto a web server, it assigns certain default access rights. These tell the server who is allowed to use and/or overwrite the file. While you want people to use your scripts, you probably don't want total strangers overwriting or deleting them. In general (for UNIX servers) you need to "chmod" the access rights to "755", but BEWARE: some servers require 777. Good hosting companies may have a special web script that does this for you. You need to read their documentation.

  3. You have been supplied with files you can read inside Windows applications like NotePad. A perl 5 script is just a text file like any other, so you need to realise that UNIX and DOS have slightly different conventions for marking the end of a line in text files. Windows (which is based on DOS) uses two characters to mark line-endings, while UNIX uses only one. So you need to strip out carriage returns if you're uploading to a UNIX server. The easiest way to do this is to upload the scripts using a good FTP program like WS-FTP32 or FTP Explorer. If you tell the FTP program to transfer files in "ASCII Mode", it will normally perform the conversion for you automatically. Alternatively, good hosting companies will have a special web script which does the job for you.

  4. The first line of any perl script tells the server that it is a perl script. It does this by giving the path of the perl interpreter. For example, on most UNIX servers the interpreter has the filepath "/usr/bin/perl", so the script's first line says "#!/usr/bin/perl". The "#!" is perl's way of saying "my interpreter's filepath is the following". If your hosting company has installed the interpreter to a different location, you will need to change the specified path to match.

If you feel unsure about installing CGI scripts, and your hosting company doesn't seem able to help you, you may like to know that we can sometimes offer a script installation service (and if we don't think we can handle your server ourselves, we'll pass the request on to our network of friends and associates). Contact installation@noisefactory.co.uk for details.

Return to Top of Page


Do I need to customise the scripts for my site?

Yes. AutoList is a sophisticated system and you need to make a few very simple changes to the generic versions we supply you with.

The three main AutoList scripts [AutoList Lite and AutoList21 are supplied with only two of these scripts] share a lot of functionality, so to make things easier for you we've encapsulated this functionality as a library, called alcore.pl. The library uses a very small number of custom variables to help your system run as smoothly as possible. For example, when a client adds an entry to an AutoList, they can choose to have relevant information emailed to them automatically. However, the script can only do this if you tell the library your own email address (for replies). If you open alcore.pl in a text editor, you'll find the following section (or something very similar, depending on version) near the top.

#
# Do NOT edit this ID. Your clients won't be able to edit their entries.
#

$admin{OwnerId} = 'autolist demo';

# -----------------------------------------------------------------------------
# CHANGE THESE VARIABLES TO MATCH YOUR SETUP

$admin{OwnerEmail} = 'you@yoursite.com';
$admin{OwnerImage} = 'http://yoursite.com/yourpath/yourlogo.gif';
$admin{OwnerImageAlt} = 'Your company name';
$admin{Server} = 'http://yoursite.com';
$admin{DefaultList} = '/yourpath/autolist/index.html';
$admin{Script} = '/cgi-bin/autolist/autolist.cgi';
$admin{SendMailPath} = '/usr/sbin/sendmail -t';

# DON'T CHANGE ANYTHING BELOW THIS LINE
# -----------------------------------------------------------------------------
You have to change the entries to the right of the =-signs to match your own set-up. All of these values are enclosed by single quotes. If the text you want to specify also contains a single quote, write it with a backslash preceding it, like this: \'. For example: 'Mike\'s Site'. If you forget the backslash, running any of the scripts will typically generate an Internal Server Error. In addition, you need to customise the outward intercept page. When a visitor jumps to a listed URL by clicking its entry in the list, the jump is made indirectly via the intercept page. You can use this page to advertise your own, or other people's, sites preferentially. Users are given the option of continuing their original jump, or else visiting one of the preferentially advertised sites instead.

Return to Top of Page


How do clients call the script?

Inward referrals can be generated from any site on the Web. The inward-referral CGI call looks like this:

autolist.cgi?url=URL&page=PAGE

where PAGE is the relative address of the page containing the list that URL is listed in. If PAGE isn't specified, your default list will be used instead.

Because this CGI call can be tricky to remember, AutoList displays a copy of the relevant details whenever an entry is added, and emails them both to the client adding the entry, and to yourself as List Owner.

When you call a script from an HTML page, you need to tell the page how to find the script in question. Every AutoList comes equipped with some JavaScript code that handles the details of calling the scripts correctly, and passing the right parameters to the server. Consequently, you only need to add the script URL once per page, instead of once per form. If you open your Template page in a text editor, you'll see the following text at the top of the page.

    // CHANGE THESE TWO PATHS AS NECESSARY      

    var script  = 'autolist.cgi';
    var outward = 'outward.html';

You need to change the script variable to point to the actual "autolist.cgi" script on your server. The variable outward specifies the URL of the outward intercept page. You can have as many AutoLists as you want, provided you have no more than one per page, and you set the script and outward variables correctly for each of these pages.

Return to Top of Page


What scores does AutoList keep track of?

AutoList maintains a number of scores for each list entry. These currently include

In addition, AutoList maintains a record of each entry's ranking relative to the parameter you select as the basis for scoring entries.

Return to Top of Page


Can I use any of these values to re-order the list entries?

Yes. You can list entries according to the number of inward or outward referrals they've generated, how recently they generated an inward or outward referral, or even in ASCII (i.e., case-dependent alphabetical) order.

Return to Top of Page


How do I specify which block an entry belongs to?

This is handled by the Administration page and script. Decide first what value you want to use for generating entrys' scores, and whether you want to block-by-rank or block-by-value. For each block, you simply fill in range of values that belong to the block. For example, to arrange entries in alphabetical order (of their site details), you would score-by-description. If you select block-by-value and specify Block 1's boundaries to be "from Aardvark to Zebra", then every entry whose site details are between the strings "Aardvark" and "Zebra" alphabetically will appear in Block 1.

Note. If you decide to score entries alphabetically, please remember that the ordering is based on standard ASCII codes. In an ASCII dictionary, digits would come before letters, and uppercase letters before lowercase letters.

Return to Top of Page


What's the difference between block-by-rank and block-by-value?

AutoList always ranks entries according to their scores, but there are two ways to display these entries. With block-by-rank, you specify block membership in terms of rank. For example, you might say "block 1 contains all entries with ranks 1 to 5". In this case, the block can contain at most 5 entries. With block-by-value, you specify block membership in terms of scores. For example, you might declare Block 1 to contain all entries with scores between 100 and 200. The number of entries in the block will depend solely on how many entries have qualifying scores.

Return to Top of Page


Why do empty blocks sometimes appear on my page, and how can I fix this?

When you block-by-value, you sometimes find that no entries currently qualify for membership of a particular block. If there are any entries still undisplayed the block header will appear, but the block will appear to be empty.

This is not an error - it is very deliberate. Typically, when you block-by-value it is because you want to reward sites that generate a lot of referrals for you, and this reward takes the form of greater prominence. However, if an empty block is completely suppressed, clients won't be able to see what this extra prominence actually looks like on the displayed page. The header allows them to see what they're missing.

In general, if you want to use block-by-value, you should insert descriptive titles into the gaps just above each block to explain how entries qualify for block membership. See Cimmerian's demo site for a live example that uses block-by-value in this way [Note. The Cimmerian list page is a gateway to adult material. You should NOT access this link unless you are legally entitled to do so, and moreover regard adult material as inoffensive.].

Return to Top of Page


How do I put adverts between blocks?

The gap between one block and the next is very clearly marked in the HTML code for the AutoList. Any HTML that you insert into a gap will be preserved exactly as-is, so you can insert any valid HTML objects, including adverts, into any of the gaps.

Return to Top of Page


How many entries can a list hold?

There is currently no intrinsic limit to the number of entries that an AutoList can handle (subject to the limitations imposed by your own server, of course). You can, however, impose your own limits as to how many entries are actually displayed.

Return to Top of Page


How many blocks can the entries be split into?

To keep administration manageable, we've currently limited AutoList to five blocks. In fact this is probably the most you would want to include. Any more than this and a page becomes very confusing for clients trying to navigate it.

Return to Top of Page


My list is becoming very popular... how can I make it work for me more efficiently?

AutoList is streamlined for medium-length lists. All of the relevant entry data is held in the AutoList page itself - there are no log or data files.

Those details that are scheduled to be displayed cannot, by definition, be removed from the HTML page, so the main overhead comes from storage of entries that are currently undisplayed. The amount of room required to store such an entry is very low - a typical undisplayed entry introduces an overhead of around 150 bytes (the actual size depends on the length of the URL and site detail text). Even with today's modem speeds and bandwidth availability, you may find this overhead unacceptable once the number of undisplayed etnries climbs into the several-hundred region.

For medium-size lists this is not a problem, but if your list becomes overly popular, you might benefit by moving to a logfile-based version of AutoList instead. We are currently nearing completion of AutoList ver 2.0, which will offer you the option of logfile storage.

Return to Top of Page


How do I try out layout changes without overwriting the "live" list?

When you use the Adminsitration page you are asked whether or not you want to save your changes to a file. If you don't specify a filepath (and don't click the "save to default list" checkbox), your edits will be made on-the-fly, and the amended version of the page will be printed directly to the browser for you to inspect. Note. When a CGI script prints directly to a browser, the URL you see in the "location" bar is normally that of the CGI script itself. Consequently, you may find that hyperlinks to other files on your server don't work properly (including images). This is normal, and doesn't mean there's a problem with your page.

Return to Top of Page


How many different AutoLists can I run at the same time?

You can run as many AutoLists as you want, provided

Return to Top of Page


How do I create a new AutoList?

A dedicated script exists for constructing new AutoList pages, but we no longer normally ship it, because streamlining of our JavaScript fragments means that you can now create a new AutoList page simply by copying the template page. Having edited the page and updated the associated JavaScript variables, you should never try to adjust the table's formatting manually. Always use the Admin utility.

Return to Top of Page


Why is there JavaScript on my AutoList page?

For several reasons. When a client adds a new entry to your list, they are asked to choose an ID and a Password, in case they ever need to amend the details later. We use JavaScript to check client-side that they've entered sensible values. This saves both time and bandwidth.

Similarly, we use JavaScript to construct the "Confirm Redirection" page on-the-fly when a user jumps to a selected entry. The alternative would be to invoke a server-side script, which would again increase both time and bandwidth overheads unnecessarily.

Return to Top of Page


How can I intercept clients when they jump to a listed URL?

AutoList does it for you. First of all, create an outward intercept page for your list. This page will be displayed when an outward referral is generated by the list. Note. Users dislike huge numbers of windows being forced upon them, so we've arranged for the same window to be used for every outward interception. A good use for the intercept page would be displaying adverts that you want users to know about. When the intercept page is displayed, a JavaScript box opens asking the user if they really want to continue to the URL they originally chose. It is possible that impulse-browsers will have forgotten why they chose the URL, and will opt for one of the advertised sites instead. In this way you can honour your obligation to allow outward referrals from the list, while at the same time giving selected sites preferential advertising.

Return to Top of Page


Copyright© 2000 Mike Stannett (NoiseFactory). All rights reserved.