# 18 Scripts

Contents

1. Introduction to scripts
2. Designing documents for user agents that support scripting
   1. The `SCRIPT` element
   2. Specifying the scripting language
      - The default scripting language
      - Local declaration of a scripting language
      - References to HTML elements from a script
   3. Intrinsic events
   4. Dynamic modification of documents
3. Designing documents for user agents that don't support scripting
   1. The `NOSCRIPT` element
   2. Hiding script data from user agents

## 18.1 Introduction to scripts

A client-side script is a program that may accompany an HTML document or be embedded directly in it. The program executes on the client's machine when the document loads, or at some other time such as when a link is activated. HTML's support for scripts is independent of the scripting language.

Scripts offer authors a means to extend HTML documents in highly active and interactive ways. For example:

- Scripts may be evaluated as a document loads to modify the contents of the document dynamically.
- Scripts may accompany a form to process input as it is entered. Designers may dynamically fill out parts of a form based on the values of other fields. They may also ensure that input data conforms to predetermined ranges of values, that fields are mutually consistent, etc.
- Scripts may be triggered by events that affect the document, such as loading, unloading, element focus, mouse movement, etc.
- Scripts may be linked to form controls (e.g., buttons) to produce graphical user interface elements.

There are two types of scripts authors may attach to an HTML document:

- Those that are executed one time when the document is loaded by the user agent. Scripts that appear within a `SCRIPT` element are executed when the document is loaded. For user agents that cannot or will not handle scripts, authors may include alternate content via the `NOSCRIPT` element.
- Those that are executed every time a specific event occurs. These scripts may be assigned to a number of elements via the intrinsic event attributes.

Note. This specification includes more detailed information about scripting in sections on script macros.

## 18.2 Designing documents for user agents that support scripting

The following sections discuss issues that concern user agents that support scripting.

### 18.2.1 The `SCRIPT` element

    <!ELEMENT SCRIPT - - %Script;          -- script statements -->
    <!ATTLIST SCRIPT
      charset     %Charset;      #IMPLIED  -- char encoding of linked resource --
      type        %ContentType;  #REQUIRED -- content type of script language --
      src         %URI;          #IMPLIED  -- URI for an external script --
      defer       (defer)        #IMPLIED  -- UA may defer execution of script --
      >

Start tag: required, End tag: required

Attribute definitions

`src` = uri [CT]
  This attribute specifies the location of an external script.
`type` = content-type [CI]
  This attribute specifies the scripting language of the element's contents and overrides the default scripting language. The scripting language is specified as a content type (e.g., "text/javascript"). Authors must supply a value for this attribute. There is no default value for this attribute.
`language` = cdata [CI]
  Deprecated. This attribute specifies the scripting language of the contents of this element. Its value is an identifier for the language, but since these identifiers are not standard, this attribute has been deprecated in favor of `type`.
`defer` [CI]
  When set, this boolean attribute provides a hint to the user agent that the script is not going to generate any document content (e.g., no "document.write" in javascript) and thus, the user agent can continue parsing and rendering.

Attributes defined elsewhere

- `charset`(character encodings)

The `SCRIPT` element places a script within a document. This element may appear any number of times in the `HEAD` or `BODY` of an HTML document.

The script may be defined within the contents of the `SCRIPT` element or in an external file. If the `src` attribute is not set, user agents must interpret the contents of the element as the script. If the `src` has a URI value, user agents must ignore the element's contents and retrieve the script via the URI. Note that the `charset` attribute refers to the character encoding of the script designated by the `src` attribute; it does not concern the content of the `SCRIPT` element.

Scripts are evaluated by script engines that must be known to a user agent.

The syntax of script data depends on the scripting language.

### 18.2.2 Specifying the scripting language

As HTML does not rely on a specific scripting language, document authors must explicitly tell user agents the language of each script. This may be done either through a default declaration or a local declaration.

#### The default scripting language

Authors should specify the default scripting language for all scripts in a document by including the following `META` declaration in the `HEAD`:

    <META http-equiv="Content-Script-Type" content="type">

where "type" is an content type naming the scripting language. Examples of values include "text/tcl", "text/javascript", "text/vbscript".

In the absence of a `META` declaration, the default can be set by a "Content-Script-Type" HTTP header.

        Content-Script-Type: type

where "type" is again an content type naming the scripting language.

User agents should determine the default scripting language for a document according to the following steps (highest to lowest priority):

1. If any `META` declarations specify the "Content-Script-Type", the last one in the character stream determines the default scripting language.
2. Otherwise, if any HTTP headers specify the "Content-Script-Type", the last one in the character stream determines the default scripting language.

Documents that do not specify a default scripting language information and that contain elements that specify an intrinsic event script are incorrect. User agents may still attempt to interpret incorrectly specified scripts but are not required to. Authoring tools should generate default scripting language information to help authors avoid creating incorrect documents.

#### Local declaration of a scripting language

The `type` attribute must be specified for each `SCRIPT` element instance in a document. The value of the `type` attribute for a `SCRIPT` element overrides the default scripting language for that element.

In this example, we declare the default scripting language to be "text/tcl". We include one `SCRIPT` in the header, whose script is located in an external file and is in the scripting language "text/vbscript". We also include one `SCRIPT` in the body, which contains its own script written in "text/javascript".

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"
         "http://www.w3.org/TR/REC-html40/strict.dtd">
    <HTML>
    <HEAD>
    <TITLE>A document with SCRIPT</TITLE>
    <META http-equiv="Content-Script-Type" content="text/tcl">
    <SCRIPT type="text/vbscript" src="http://someplace.com/progs/vbcalc">
    </SCRIPT>
    </HEAD>
    <BODY>
    <SCRIPT type="text/javascript">
    ...some JavaScript...
    </SCRIPT>
    </BODY>
    </HTML>

#### References to HTML elements from a script

Each scripting language has its own conventions for referring to HTML objects from within a script. This specification does not define a standard mechanism for referring to HTML objects.

However, scripts should refer to an element according to its assigned name. Scripting engines should observe the following precedence rules when identifying an element: a `name` attribute takes precedence over an `id` if both are set. Otherwise, one or the other may be used.

### 18.2.3 Intrinsic events

Note. Authors of HTML documents are advised that changes are likely to occur in realm of intrinsic events (e.g., how scripts are bound to events). Research in this realm is carried on by members of the W3C Document Object Model Working Group (see the W3C Web Site at http://www.w3.org/ for more information).

Attribute definitions

`onload` = script [CT]
  The `onload` event occurs when the user agent finishes loading a window or all frames within a `FRAMESET`. This attribute may be used with `BODY` and `FRAMESET` elements.
`onunload` = script [CT]
  The `onunload` event occurs when the user agent removes a document from a window or frame. This attribute may be used with `BODY` and `FRAMESET` elements.
`onclick` = script [CT]
  The `onclick` event occurs when the pointing device button is clicked over an element. This attribute may be used with most elements.
`ondblclick` = script [CT]
  The `ondblclick` event occurs when the pointing device button is double clicked over an element. This attribute may be used with most elements.
`onmousedown` = script [CT]
  The `onmousedown` event occurs when the pointing device button is pressed over an element. This attribute may be used with most elements.
`onmouseup` = script [CT]
  The `onmouseup` event occurs when the pointing device button is released over an element. This attribute may be used with most elements.
`onmouseover` = script [CT]
  The `onmouseover` event occurs when the pointing device is moved onto an element. This attribute may be used with most elements.
`onmousemove` = script [CT]
  The `onmousemove` event occurs when the pointing device is moved while it is over an element. This attribute may be used with most elements.
`onmouseout` = script [CT]
  The `onmouseout` event occurs when the pointing device is moved away from an element. This attribute may be used with most elements.
`onfocus` = script [CT]
  The `onfocus` event occurs when an element receives focus either by the pointing device or by tabbing navigation. This attribute may be used with the following elements: `LABEL`, `INPUT`, `SELECT`, `TEXTAREA`, and `BUTTON`.
`onblur` = script [CT]
  The `onblur` event occurs when an element loses focus either by the pointing device or by tabbing navigation. It may be used with the same elements as `onfocus`.
`onkeypress` = script [CT]
  The `onkeypress` event occurs when a key is pressed and released over an element. This attribute may be used with most elements.
`onkeydown` = script [CT]
  The `onkeydown` event occurs when a key is pressed down over an element. This attribute may be used with most elements.
`onkeyup` = script [CT]
  The `onkeyup` event occurs when a key is released over an element. This attribute may be used with most elements.
`onsubmit` = script [CT]
  The `onsubmit` event occurs when a form is submitted. It only applies to the `FORM` element.
`onreset` = script [CT]
  The `onreset` event occurs when a form is reset. It only applies to the `FORM` element.
`onselect` = script [CT]
  The `onselect` event occurs when a user selects some text in a text field. This attribute may be used with the `INPUT` and `TEXTAREA` elements.
`onchange` = script [CT]
  The `onchange` event occurs when a control loses the input focus and its value has been modified since gaining focus. This attribute applies to the following elements: `INPUT`, `SELECT`, and `TEXTAREA`.

It is possible to associate an action with a certain number of events that occur when a user interacts with a user agent. Each of the "intrinsic events" listed above takes a value that is a script. The script is executed whenever the event occurs for that element. The syntax of script data depends on the scripting language.

Control elements such as `INPUT`, `SELECT`, `BUTTON`, `TEXTAREA`, and `LABEL` all respond to certain intrinsic events. When these elements do not appear within a form, they may be used to augment the graphical user interface of the document.

For instance, authors may want to include press buttons in their documents that do not submit a form but still communicate with a server when they are activated.

The following examples show some possible control and user interface behavior based on intrinsic events.

In the following example, userName is a required text field. When a user attempts to leave the field, the `onblur` event calls a JavaScript function to confirm that userName has an acceptable value.

    <INPUT NAME="userName" onblur="validUserName(this.value)">

Here is another JavaScript example:

    <INPUT NAME="num"
        onchange="if (!checkNum(this.value, 1, 10))
            {this.focus();this.select();} else {thanks()}"
        VALUE="0">

Here is a VBScript example of an event handler for a text field:

        <INPUT name="edit1" size="50">
        <SCRIPT type="text/vbscript">
          Sub edit1_changed()
            If edit1.value = "abc" Then
              button1.enabled = True
            Else
              button1.enabled = False
            End If
          End Sub
        </SCRIPT>

Here is the same example using Tcl:

        <INPUT name="edit1" size="50">
        <SCRIPT type="text/tcl">
          proc edit1_changed {} {
            if {[edit value] == abc} {
              button1 enable 1
            } else {
              button1 enable 0
            }
          }
          edit1 onChange edit1_changed
        </SCRIPT>

Here is a JavaScript example for event binding within a script. First, here's a simple click handler:

    <BUTTON type="button" name="mybutton" value="10">
    <SCRIPT type="text/javascript">
          function my_onclick() {
             . . .
          }
        document.form.mybutton.onclick = my_onclick
     </SCRIPT>
     </BUTTON>

Here's a more interesting window handler:

    <SCRIPT type="text/javascript">
          function my_onload() {
             . . .
          }

          var win = window.open("some/other/URI")
          if (win) win.onload = my_onload
    </SCRIPT>

In Tcl this looks like:

     <SCRIPT type="text/tcl">
         proc my_onload {} {
           . . .
         }
         set win [window open "some/other/URI"]
         if {$win != ""} {
             $win onload my_onload
         }
     </SCRIPT>

Note that "document.write" or equivalent statements in intrinsic event handlers create and write to a new document rather than modifying the current one.

### 18.2.4 Dynamic modification of documents

Scripts that are executed when a document is loaded may be able to modify the document's contents dynamically. The ability to do so depends on the scripting language itself (e.g., the "document.write" statement in the HTML object model supported by some vendors).

The dynamic modification of a document may be modeled as follows:

1. All `SCRIPT` elements are evaluated in order as the document is loaded.
2. All script constructs within a given `SCRIPT` element that generate SGML CDATA are evaluated. Their combined generated text is inserted in the document in place of the `SCRIPT` element.
3. The generated CDATA is re-evaluated.

HTML documents are constrained to conform to the HTML DTD both before and after processing any `SCRIPT` elements.

The following example illustrates how scripts may modify a document dynamically. The following script:

     <TITLE>Test Document</TITLE>
     <SCRIPT type="text/javascript">
         document.write("<p><b>Hello World!<\/b>")
     </SCRIPT>

Has the same effect as this HTML markup:

     <TITLE>Test Document</TITLE>
     <P><B>Hello World!</B>

## 18.3 Designing documents for user agents that don't support scripting

The following sections discuss how authors may create documents that work for user agents that don't support scripting.

### 18.3.1 The `NOSCRIPT` element

    <!ELEMENT NOSCRIPT - - (%block;)+
      -- alternate content container for non script-based rendering -->
    <!ATTLIST NOSCRIPT
      %attrs;                              -- %coreattrs, %i18n, %events --
      >

Start tag: required, End tag: required

The `NOSCRIPT` element allows authors to provide alternate content when a script is not executed. The content of a `NOSCRIPT` element should only rendered by a script-aware user agent in the following cases:

- The user agent is configured not to evaluate scripts.
- The user agent doesn't support a scripting language invoked by a `SCRIPT` element earlier in the document.

User agents that do not support client-side scripts must render this element's contents.

In the following example, a user agent that executes the `SCRIPT` will include some dynamically created data in the document. If the user agent doesn't support scripts, the user may still retrieve the data through a link.

    <SCRIPT type="text/tcl">
     ...some Tcl script to insert data...
    </SCRIPT>
    <NOSCRIPT>
     <P>Access the <A href="http://someplace.com/data">data.</A>
    </NOSCRIPT>

### 18.3.2 Hiding script data from user agents

User agents that don't recognize the `SCRIPT` element will likely render that element's contents as text. Some scripting engines, including those for languages JavaScript, VBScript, and Tcl allow the script statements to be enclosed in an SGML comment. User agents that don't recognize the `SCRIPT` element will thus ignore the comment while smart scripting engines will understand that the script in comments should be executed.

Another solution to the problem is to keep scripts in external documents and refer to them with the `src` attribute.

Commenting scripts in JavaScript
The JavaScript engine allows the string "<!--" to occur at the start of a SCRIPT element, and ignores further characters until the end of the line. JavaScript interprets "//" as starting a comment extending to the end of the current line. This is needed to hide the string "-->" from the JavaScript parser.

    <SCRIPT type="text/javascript">
    <!--  to hide script contents from old browsers
      function square(i) {
        document.write("The call passed ", i ," to the function.","<BR>")
        return i * i
      }
      document.write("The function returned ",square(5),".")
    // end hiding contents from old browsers  -->
    </SCRIPT>

Commenting scripts in VBScript
In VBScript, a single quote character causes the rest of the current line to be treated as a comment. It can therefore be used to hide the string "-->" from VBScript, for instance:

       <SCRIPT type="text/vbscript">
         <!--
           Sub foo()
            ...
           End Sub
         ' -->
        </SCRIPT>

Commenting scripts in TCL
In Tcl, the "#" character comments out the rest of the line:

    <SCRIPT type="text/tcl">
    <!--  to hide script contents from old browsers
      proc square {i} {
        document write "The call passed $i to the function.<BR>"
        return [expr $i * $i]
      }
      document write "The function returned [square 5]."
    # end hiding contents from old browsers  -->
    </SCRIPT>

Note. Some browsers close comments on the first ">" character, so to hide script content from such browsers, you can transpose operands for relational and shift operators (e.g., use "y < x" rather than "x > y") or use scripting language-dependent escapes for ">".