Writing OSCAR Configuration Files

Purpose

The purpose of this document is to assist you in writing configuration files for the OSCAR "Configurator". The OSCAR Configurator allows a package maintainer to define options which a user can set. To present these options to the user, the Configurator uses a simple HTML Form. While the basics of writing HTML files and HTML forms are discussed in detail in many books and online tutorials, this document seeks to describe the HTML form tags available to a package maintainer and how to use those tags to get information from the user.

Many of the basic HTML tags are supported in the OSCAR Configurator, including:

There is also a decent assortment of HTML Form tags such as: All of the available tags are described in detail below.

There are some HTML tags that are NOT allowed in a configuration file. In particular, you may not use:

If any of these tags are present in your HTML document, they are removed prior to rendering so that your document will appear without the offending tags.


A Basic HTML Form Document

Since all of the configuration input from a user appears in an HTML Form, the minimum useful configuration file contains <form> and </form> tags. Between these two tags, the package maintainer adds <input> tags to get input from the user. For example, if all you want from the user is his name, your configuration file might be as follows:
           <form>
           Enter your name: <input name="username">
           </form>
The resulting output would look like this:

                    Enter your name:

If you are HTML savvy, you may notice a few things missing from this example. Specifically, we omitted the main <html>...</html> tags, and the <head></head> and <body></body> tags. For basic configuration files, these tags are optional. You may use them if you like (and some browsers would bonk if they were absent), but they are not required. Also, there are no attributes for the <form> tag. This is because the Configurator knows the action to take when the user saves the values, so no "action" label is needed. Also, there can be only one pair of <form></form> tags in the configuration file, so there is no need for the "name" label.


A More Complete HTML Form

A typical HTML document consists of at least two separate sections, a "head" and a "body". The most important element of the "head" is the <title>...</title> tag. This sets the title of the window and also acts as the text for the header of the configuration window. If you omit this tag or leave the value blank, it defaults to "Configuration".

The body is where the main part of the HTML document is stored. It includes both the Form and any other "standard" HTML elements you want to display. Many of these elements can appear inside or outside of the Form, so it is sometimes easiest to have a configuration form that looks like this:

           <html>
             <head>
               <title>The Title Of Your Configuration Form<title>
             </head>

             <body>
               <form>
                 All of your main HTML configuration goes here.
               </form>
             </body>
           </html>
In HTML files, whitespace (including carriage returns) are usually compacted to a single space. So in the above example, the indentation and line spacing are shown simply to make the example easier to read. We could just have easily put everything on a single line and the output would be the same. This is important to know since if you want a true line break (say between paragraphs), you have to explicitly tell HTML by using the <p> (paragraph) tag. Also, the case of the tags is unimportant, so you could also use all uppercase letters for your tags if you find that to me more readable.


Basic (non-form) HTML Tags

There are many HTML tags which can be displayed by the Configurator that don't need to be in the form, but will be useful anyway. The function of each of these tags are not listed here. There are plenty of HTML reference books and online tutorials available. Use your favorite search engine and do a search on "HTML tutorial" to get a big listing. A primer available at NCSA can be found at archive.ncsa.uiuc.edu/General/Internet/WWW/index.html.


HTML Form Tags

The main tags that you will need for your configuration file are <form> tags. These tags allow you do prompt the user for information to be entered via text boxes, check boxes, radio buttons, selection lists, etc. This section describes each tag in detail and provides examples.

Note that all of these tags must appear between a <form>...</form> tag pair. Otherwise your values will not get submitted correctly.