This is a work in progress! For the latest updates from the HTML WG, possibly including important bug fixes, please look at the editor's draft instead. There may also be a more up-to-date Working Draft with changes based on resolution of Last Call issues.

4 The elements of HTML – Table of contents – 4.4 Sections

1. 1. 4.3 Scripting
      1. 4.3.1 The script element
         1. 4.3.1.1 Scripting languages
         2. 4.3.1.2 Restrictions for contents of script elements
         3. 4.3.1.3 Inline documentation for external scripts
         4. 4.3.1.4 Interaction of script elements and XSLT
      2. 4.3.2 The noscript element

A script element has several associated pieces of state.

The first is a flag indicating whether or not the script block has been "already started" . Initially, script elements must have this flag unset (script blocks, when created, are not "already started"). When a script element is cloned, the "already started" flag, if set, must be propagated to the clone when it is created.

The second is a flag indicating whether the element was "parser-inserted" . Initially, script elements must have this flag unset. It is set by the HTML parser and the XML parser on script elements they insert and affects the processing of those elements.

The third is a flag indicating whether the element will "force-async" . Initially, script elements must have this flag set. It is unset by the HTML parser and the XML parser on script elements they insert. In addition, whenever a script element whose "force-async" flag is set has a async content attribute added, the element's "force-async" flag must be unset.

The fourth is a flag indicating whether or not the script block is "ready to be parser-executed" . Initially, script elements must have this flag unset (script blocks, when created, are not "ready to be parser-executed"). This flag is used only for elements that are also "parser-inserted", to let the parser know when to execute the script.

The last few pieces of state are the script block's type , the script block's character encoding , and the script block's fallback character encoding . They are determined when the script is prepared, based on the attributes on the element at that time, and the Document of the script element.

When a script element that is not marked as being "parser-inserted" experiences one of the events listed in the following list, the user agent must synchronously prepare the script element:

• The script element gets inserted into a document.
• The script element is in a Document and its child nodes are changed.
• The script element is in a Document and has a src attribute set where previously the element had no such attribute.

To prepare a script , the user agent must act as follows:

1. If the script element is marked as having "already started", then the user agent must abort these steps at this point. The script is not executed.

2. If the element has its "parser-inserted" flag set, then set was-parser-inserted to true and unset the element's "parser-inserted" flag. Otherwise, set was-parser-inserted to false.

   This is done so that if parser-inserted script elements fail to run when the parser tries to run them, e.g. because they are empty or specify an unsupported scripting language, another script can later mutate them and cause them to run again.

3. If was-parser-inserted is true and the element does not have an async attribute, then set the element's "force-async" flag to true.

   This is done so that if a parser-inserted script element fails to run when the parser tries to run it, but it is later executed after a script dynamically updates it, it will execute asynchronously even if the async attribute isn't set.

4. If the element has no src attribute, and its child nodes, if any, consist only of comment nodes and empty text nodes, then the user agent must abort these steps at this point. The script is not executed.

5. If the element is not in a Document, then the user agent must abort these steps at this point. The script is not executed.

6. If either:

   • the script element has a type attribute and its value is the empty string, or
   • the script element has no type attribute but it has a language attribute and that attribute's value is the empty string, or
   • the script element has neither a type attribute nor a language attribute, then

   ...let the script block's type for this script element be "text/javascript".

   Otherwise, if the script element has a type attribute, let the script block's type for this script element be the value of that attribute with any leading or trailing sequences of space characters removed.

   Otherwise, the element has a non-empty language attribute; let the script block's type for this script element be the concatenation of the string "text/" followed by the value of the language attribute.

   The language attribute is never conforming, and is always ignored if there is a type attribute present.

7. If the user agent does not support the scripting language given by the script block's type for this script element, then the user agent must abort these steps at this point. The script is not executed.

8. If was-parser-inserted is true, then flag the element as "parser-inserted" again, and set the element's "force-async" flag to false.

9. The user agent must set the element's "already started" flag.

   The state of the element at this moment is later used to determine the script source.

10. If the element is flagged as "parser-inserted", but the element's Document is not the Document of the parser that created the element, then abort these steps.

11. If scripting is disabled for the script element, then the user agent must abort these steps at this point. The script is not executed.

    The definition of scripting is disabled means that, amongst others, the following scripts will not execute: scripts in XMLHttpRequest's responseXML documents, scripts in DOMParser-created documents, scripts in documents created by XSLTProcessor's transformToDocument feature, and scripts that are first inserted by a script into a Document that was created using the createDocument() API. [XHR] [DOMPARSER] [DOMCORE]

12. If the script element has an event attribute and a for attribute, then run these substeps:

    1. Let for be the value of the for attribute.

    2. Let event be the value of the event attribute.

    3. Strip leading and trailing whitespace from event and for.

    4. If for is not an ASCII case-insensitive match for the string "window", then the user agent must abort these steps at this point. The script is not executed.

    5. If event is not an ASCII case-insensitive match for either the string "onload" or the string "onload()", then the user agent must abort these steps at this point. The script is not executed.

13. If the script element has a charset attribute, then let the script block's character encoding for this script element be the encoding given by the charset attribute.

    Otherwise, let the script block's fallback character encoding for this script element be the same as the encoding of the document itself.

    Only one of these two pieces of state is set.

14. If the element has a src attribute whose value is not the empty string, then the value of that attribute must be resolved relative to the element, and if that is successful, the specified resource must then be fetched, from the origin of the element's Document.

    If the src attribute's value is the empty string or if it could not be resolved, then the user agent must queue a task to fire a simple event named error at the element, and abort these steps.

    For historical reasons, if the URL is a javascript: URL, then the user agent must not, despite the requirements in the definition of the fetching algorithm, actually execute the script in the URL; instead the user agent must act as if it had received an empty HTTP 400 response.

    For performance reasons, user agents may start fetching the script as soon as the attribute is set, instead, in the hope that the element will be inserted into the document. Either way, once the element is inserted into the document, the load must have started. If the UA performs such prefetching, but the element is never inserted in the document, or the src attribute is dynamically changed, then the user agent will not execute the script, and the fetching process will have been effectively wasted.

15. Then, the first of the following options that describes the situation must be followed:

    If the element has a src attribute, and the element has a defer attribute, and the element has been flagged as "parser-inserted", and the element does not have an async attribute

    The element must be added to the end of the list of scripts that will execute when the document has finished parsing associated with the Document of the parser that created the element.

    The task that the networking task source places on the task queue once the fetching algorithm has completed must set the element's "ready to be parser-executed" flag. The parser will handle executing the script.

    If the element has a src attribute, and the element has been flagged as "parser-inserted", and the element does not have an async attribute

    The element is the pending parsing-blocking script of the Document of the parser that created the element. (There can only be one such script per Document at a time.)

    The task that the networking task source places on the task queue once the fetching algorithm has completed must set the element's "ready to be parser-executed" flag. The parser will handle executing the script.

    If the element does not have a src attribute, and the element has been flagged as "parser-inserted", and the Document of the HTML parser or XML parser that created the script element has a style sheet that is blocking scripts

    The element is the pending parsing-blocking script of the Document of the parser that created the element. (There can only be one such script per Document at a time.)

    Set the element's "ready to be parser-executed" flag. The parser will handle executing the script.

    If the element has a src attribute, does not have an async attribute, and does not have the "force-async" flag set

    The element must be added to the end of the list of scripts that will execute in order as soon as possible associated with the Document of the script element at the time the prepare a script algorithm started.

    The task that the networking task source places on the task queue once the fetching algorithm has completed must run the following steps:

    1. If the element is not now the first element in the list of scripts that will execute in order as soon as possible to which it was added above, then mark the element as ready but abort these steps without executing the script yet.

    2. Execution: Execute the script block corresponding to the first script element in this list of scripts that will execute in order as soon as possible.

    3. Remove the first element from this list of scripts that will execute in order as soon as possible.

    4. If this list of scripts that will execute in order as soon as possible is still not empty and the first entry has already been marked as ready, then jump back to the step labeled execution.

    If the element has a src attribute

    The element must be added to the set of scripts that will execute as soon as possible of the Document of the script element at the time the prepare a script algorithm started.

    The task that the networking task source places on the task queue once the fetching algorithm has completed must execute the script block and then remove the element from the set of scripts that will execute as soon as possible.

    Otherwise

    The user agent must immediately execute the script block, even if other scripts are already executing.

Fetching an external script must delay the load event of the element's document until the task that is queued by the networking task source once the resource has been fetched (defined above) has been run.

The pending parsing-blocking script of a Document is used by the Document's parser(s).

If a script element that blocks a parser gets moved to another Document before it would normally have stopped blocking that parser, it nonetheless continues blocking that parser until the condition that causes it to be blocking the parser no longer applies (e.g. if the script is a pending parsing-blocking script because there was a style sheet that is blocking scripts when it was parsed, but then the script is moved to another Document before the style sheet loads, the script still blocks the parser until the style sheets are all loaded, at which time the script executes and the parser is unblocked).

When the user agent is required to execute a script block , it must run the following steps:

1. If the element is flagged as "parser-inserted", but the element's Document is not the Document of the parser that created the element, then abort these steps.

2. Jump to the appropriate set of steps from the list below:

   If the load resulted in an error (for example a DNS error, or an HTTP 404 error)

   Executing the script block must just consist of firing a simple event named error at the element.

   If the load was successful

   Executing the script block must consist of running the following steps. For the purposes of these steps, the script is considered to be from an external file if, while the prepare a script algorithm above was running for this script, the script element had a src attribute specified.

   1. Initialize the script block's source as follows:

      If the script is from an external file and the script block's type is a text-based language

      The contents of that file, interpreted as string of Unicode characters, are the script source.

      To obtain the string of Unicode characters, the user agent run the following steps:

      1. If the resource's Content Type metadata, if any, specifies a character encoding, and the user agent supports that encoding, then let character encoding be that encoding, and jump to the bottom step in this series of steps.

      2. If the algorithm above set the script block's character encoding, then let character encoding be that encoding, and jump to the bottom step in this series of steps.

      3. For each of the rows in the following table, starting with the first one and going down, if the file has as many or more bytes available than the number of bytes in the first column, and the first bytes of the file match the bytes given in the first column, then set character encoding to the encoding given in the cell in the second column of that row, and jump to the bottom step in this series of steps:

         Bytes in Hexadecimal	Encoding
         FE FF	Big-endian UTF-16
         FF FE	Little-endian UTF-16
         EF BB BF	UTF-8

         This step looks for Unicode Byte Order Marks (BOMs).

      4. Let character encoding be the script block's fallback character encoding.

      5. Convert the file to Unicode using character encoding, following the rules for doing so given by the specification for the script block's type.

      If the script is from an external file and the script block's type is an XML-based language

      The external file is the script source. When it is later executed, it must be interpreted in a manner consistent with the specification defining the language given by the script block's type.

      If the script is inline and the script block's type is a text-based language

      The value of the text IDL attribute at the time the element's "already started" flag was last set is the script source.

      If the script is inline and the script block's type is an XML-based language

      The child nodes of the script element at the time the element's "already started" flag was last set are the script source.

   2. If the script is from an external file, then increment the ignore-destructive-writes counter of the script element's Document. Let neutralized doc be that Document.

   3. Create a script from the script element node, using the script block's source and the script block's type.

      This is where the script is compiled and actually executed.

   4. Decrement the ignore-destructive-writes counter of neutralized doc, if it was incremented in the earlier step.

   5. If the script is from an external file, fire a simple event named load at the script element.

      Otherwise, the script is internal; queue a task to fire a simple event named load at the script element.

The IDL attributes src , type , charset , and defer , each must reflect the respective content attributes of the same name.

The async IDL attribute controls whether the element will execute asynchronously or not. If the element's "force-async" flag is set, then, on getting, the async IDL attribute must return true, and on setting, the "force-async" flag must first be unset, and then the content attribute must be removed if the IDL attribute's new value is false, and must be set to the empty string if the IDL attribute's new value is true. If the element's "force-async" flag is not set, the IDL attribute must reflect the async content attribute.

In this example, two script elements are used. One embeds an external script, and the other includes some data.

<script src="game-engine.js"></script>
<script type="text/x-game-map">
........U.........e
o............A....e
.....A.....AAA....e
.A..AAA...AAAAA...e
</script>

The data in this case might be used by the script to generate the map of a video game. The data doesn't have to be used that way, though; maybe the map data is actually embedded in other parts of the page's markup, and the data block here is just used by the site's search engine to help users who are looking for particular features in their game maps.

The following sample shows how a script element can be used to define a function that is then used by other parts of the document. It also shows how a script element can be used to invoke script while the document is being parsed, in this case to initialize the form's output.

<script>
 function calculate(form) {
   var price = 52000;
   if (form.elements.brakes.checked)
     price += 1000;
   if (form.elements.radio.checked)
     price += 2500;
   if (form.elements.turbo.checked)
     price += 5000;
   if (form.elements.sticker.checked)
     price += 250;
   form.elements.result.value = price;
 }
</script>
<form name="pricecalc" onsubmit="return false" onchange="calculate(this)">
 <fieldset>
  <legend>Work out the price of your car</legend>
  <p>Base cost: £52000.</p>
  <p>Select additional options:</p>
  <ul>
   <li><label><input type=checkbox name=brakes> Ceramic brakes (£1000)</label></li>
   <li><label><input type=checkbox name=radio> Satellite radio (£2500)</label></li>
   <li><label><input type=checkbox name=turbo> Turbo charger (£5000)</label></li>
   <li><label><input type=checkbox name=sticker> "XZ" sticker (£250)</label></li>
  </ul>
  <p>Total: £<output name=result></output></p>
 </fieldset>
 <script>
  calculate(document.forms.pricecalc);
 </script>
</form>

User agents may support other MIME types and other languages.

When examining types to determine if they support the language, user agents must not ignore unknown MIME parameters — types with unknown parameters must be assumed to be unsupported. The charset parameter must be treated as an unknown parameter for the purpose of comparing MIME types here.

script        = data1 *( escape [ script-start data3 ] "-->" data1 ) [ escape ]
escape        = "<!--" data2 *( script-start data3 script-end data2 )
data1         = <any string that doesn't contain a substring that matches not-data1>
not-data1     = "<!--"
data2         = <any string that doesn't contain a substring that matches not-data2>
not-data2     = script-start / "-->"
data3         = <any string that doesn't contain a substring that matches not-data3>
not-data3     = script-end / "-->"
script-start  = lt       s c r i p t tag-end
script-end    = lt slash s c r i p t tag-end
lt            =  %x003C ; U+003C LESS-THAN SIGN character (<)
slash         =  %x002F ; U+002F SOLIDUS character (/)
s             =  %x0053 ; U+0053 LATIN CAPITAL LETTER S
s             =/ %x0073 ; U+0073 LATIN SMALL LETTER S
c             =  %x0043 ; U+0043 LATIN CAPITAL LETTER C
c             =/ %x0063 ; U+0063 LATIN SMALL LETTER C
r             =  %x0052 ; U+0052 LATIN CAPITAL LETTER R
r             =/ %x0072 ; U+0072 LATIN SMALL LETTER R
i             =  %x0049 ; U+0049 LATIN CAPITAL LETTER I
i             =/ %x0069 ; U+0069 LATIN SMALL LETTER I
p             =  %x0050 ; U+0050 LATIN CAPITAL LETTER P
p             =/ %x0070 ; U+0070 LATIN SMALL LETTER P
t             =  %x0054 ; U+0054 LATIN CAPITAL LETTER T
t             =/ %x0074 ; U+0074 LATIN SMALL LETTER T
tag-end       =  %x0009 ; U+0009 CHARACTER TABULATION (tab)
tag-end       =/ %x000A ; U+000A LINE FEED (LF)
tag-end       =/ %x000C ; U+000C FORM FEED (FF)
tag-end       =/ %x0020 ; U+0020 SPACE
tag-end       =/ %x002F ; U+002F SOLIDUS (/)
tag-end       =/ %x003E ; U+003E GREATER-THAN SIGN (>)

documentation = *( *( space / tab / comment ) [ line-comment ] newline )
comment       = slash star *( not-star / star not-slash ) 1*star slash
line-comment  = slash slash *not-newline
; characters
tab           = %x0009 ; U+0009 CHARACTER TABULATION (tab)
newline       = %x000A ; U+000A LINE FEED (LF)
space         = %x0020 ; U+0020 SPACE
star          = %x002A ; U+002A ASTERISK (*)
slash         = %x002F ; U+002F SOLIDUS (/)
not-newline   = %x0000-0009 / %x000B-10FFFF
                ; a Unicode character other than U+000A LINE FEED (LF)
not-star      = %x0000-0029 / %x002B-10FFFF
                ; a Unicode character other than U+002A ASTERISK (*)
not-slash     = %x0000-002E / %x0030-10FFFF
                ; a Unicode character other than U+002F SOLIDUS (/)

This allows authors to include documentation, such as license information or API information, inside their documents while still referring to external script files. The syntax is constrained so that authors don't accidentally include what looks like valid script while also providing a src attribute.

<script src="cool-effects.js">
 // create new instances using:
 //    var e = new Effect();
 // start the effect using .play, stop using .stop:
 //    e.play();
 //    e.stop();
</script>

4.3.1.4 Interaction of script elements and XSLT

This section is non-normative.

This specification does not define how XSLT interacts with the script element (or, indeed, how XSLT processing triggers the stop parsing steps, how it interacts with the navigation algorithm, or how it fits in with the event loop). However, in the absence of another specification actually defining this, here are some guidelines for implementors, based on existing implementations:

• When an XSLT transformation program is triggered by an <?xml-stylesheet?> processing instruction and the browser implements a direct-to-DOM transformation, script elements created by the XSLT processor need to be marked "parser-inserted" and run in document order (modulo scripts marked defer or async), asynchronously while the transformation is occurring.

• The XSLTProcessor.transformToDocument() method adds elements to a Document that is not in a browsing context, and, accordingly, any script elements they create need to have their "already started" flag set in the prepare a script algorithm and never get executed (scripting is disabled). Such script elements still need to be marked "parser-inserted", though, such that their async IDL attribute will return false in the absence of an async content attribute.

• The XSLTProcessor.transformToFragment() method needs to create a fragment that is equivalent to one built manually by creating the elements using document.createElementNS(). For instance, it needs to create script elements that aren't "parser-inserted" and that don't have their "already started" flag set, so that they will execute when the fragment is inserted into a document.

The main distinction between the first two cases and the last case is that the first two operate on Documents and the last operates on a fragment.

In the following example, a noscript element is used to provide fallback for a script.

<form action="calcSquare.php">
 <p>
  <label for=x>Number</label>:
  <input id="x" name="x" type="number">
 </p>
 <script>
  var x = document.getElementById('x');
  var output = document.createElement('p');
  output.textContent = 'Type a number; it will be squared right then!';
  x.form.appendChild(output);
  x.form.onsubmit = function () { return false; }
  x.oninput = function () {
    var v = x.valueAsNumber;
    output.textContent = v + ' squared is ' + v * v;
  };
 </script>
 <noscript>
  <input type=submit value="Calculate Square">
 </noscript>
</form>

When script is disabled, a button appears to do the calculation on the server side. When script is enabled, the value is computed on-the-fly instead.

The noscript element is a blunt instrument. Sometimes, scripts might be enabled, but for some reason the page's script might fail. For this reason, it's generally better to avoid using noscript, and to instead design the script to change the page from being a scriptless page to a scripted page on the fly, as in the next example:

<form action="calcSquare.php">
 <p>
  <label for=x>Number</label>:
  <input id="x" name="x" type="number">
 </p>
 <input id="submit" type=submit value="Calculate Square">
 <script>
  var x = document.getElementById('x');
  var output = document.createElement('p');
  output.textContent = 'Type a number; it will be squared right then!';
  x.form.appendChild(output);
  x.form.onsubmit = function () { return false; }
  x.oninput = function () {
    var v = x.valueAsNumber;
    output.textContent = v + ' squared is ' + v * v;
  };
  var submit = document.getElementById('submit');
  submit.parentNode.removeChild(submit);
 </script>
</form>

The above technique is also useful in XHTML, since noscript is not supported in the XHTML syntax.