dynamic content, forms, programming:
"command-line" arguments

What are command-line arguments?

The term command-line argument can be informally defined as any parameter that is typed after the name of a program in a command interpreter (such as a DOS box or Unix shell). For example, if you typed the command

dir *.txt

Web pages are programs.

If you stretch your imagination a bit, you can think of a web page as a program. The capabilities of web page "programs," of course, are limited mostly to displaying text in your browser -- but they are still programs none the less. Pushing this analogy further, it is not unreasonable to think of your web browser's location bar a 'command interpreter,' because it is here that you enter the name of the program (i.e., the URL) you wish to run (display). When you push enter in the location bar, the browser interprets the request you have typed and performs the appropriate action.

So, if web pages are programs, does it make sense to talk about command-line arguments for web pages? Actually, it does. The next time you fill out a web form that uses the GET method (such as Yahoo!^TM's search engine), take a look at the URL shown in the location bar. There, you will see that the name of the program (i.e., the web page address) is followed by a question mark and then by a whole bunch of extra, URL-encoded characters. A URL-encoded string that appears after the question mark in a URL is called a search string. Search strings can be thought of as command-line parameters for web pages.

JavaScript programs can access search strings.

Most useful programming languages provide mechanisms for accessing command-line parameters. Although JavaScript is no exception to this rule, JavaScript's support for command-line arguments is at best very difficult to understand and use.

To make things easier, I have developed a script, called args.js, that makes accessing search string parameters a breeze. It is given in the edit box below in case you want to cut and paste it into your favorite text editor.

/******************************************************************************* 'args.js', by Charlton Rose Permission is granted to use and modify this script for any purpose, provided that this credit header is retained, unmodified, in the script. *******************************************************************************/ // This function is included to overcome a bug in Netscape's implementation // of the escape () function: function myunescape (str) { str = '' + str; while (true) { var i = str . indexOf ('+'); if (i < 0) break; str = str . substring (0, i) + ' ' + str . substring (i + 1, str . length); } return unescape (str); } // This function creates the args [] array and populates it with data // found in the URL's search string: function args_init () { args = new Array (); var argstring = window . location . search; if (argstring . charAt (0) != '?') return; argstring = argstring . substring (1, argstring . length); var argarray = argstring . split ('&'); var i; var singlearg; for (i = 0; i < argarray . length; ++ i) { singlearg = argarray [i] . split ('='); if (singlearg . length != 2) continue; var key = myunescape (singlearg [0]); var value = myunescape (singlearg [1]); args [key] = value; } } // Call the args_init () function to set up the args [] array: args_init ();

To use the script, save it in a file called 'args.js', and then activate it in your web pages using the following "include tags":

<script src="args.js"></script>

Note: If you have a question about what these tags mean, please see article #12, Importing Scripts From Other Files."

The script in args.js generates a text-associative array, called args [], from which you can read the URL's search parameters. For args.js to work, the search string parameters must be appended to the URL in the form of

http://www.mysite.com/mypage.html?param₁=value₁&param₂=value₂&...&param_n=value_n .

For example, if the URL used to load your web page is

http://www.mysite.com/mypage.html?name=Charlie+Brown&password=snoopy ,

args ['name']

args ['password']

On the other hand, if you try to access an element of args [] that doesn't exist, such as args ['telephone'], then the result will be a special JavaScript value called undefined, because no "telephone" parameter appears in the URL's search string.

Tip: For more information about JavaScript's undefined value, please see article #45, undefined vs. null.

a simple example

I have prepared a simple product ordering script to demonstrate the use of args []. When you click on the button below, a new window will appear showing blanks for "item," "price," and "quantity." Fill the blanks in with anything you want and then push the submit button (don't worry, it's just pretend :-). As you experiment with different numbers to change the results, pay special attention to the location bar and watch how it changes each time you enter new data.

Don't forget to study the source so you can see how it works.

Charlton Rose
June 11, 1997