Most often the ASP pages are HTML pages with embedded VBScript or JScript. By default ALP assumes that the pages contain HTML, but there is no problem to implement ASP pages that generate plain text, XML or any other textual content. It is possible, of course, certain ASP page to contain only script and no static non-script content at all. This is especially useful when the application implements techniques such as page templates and all the content is dynamically generated, or when the generated content is not textual. Special attention deserves the non-textual content - for example pages that generate images, documents for certain applications and so on.

By default the script embeddings in the ASP pages are assumed to be in VBScript, but they can be also in JScript. The defaults can be changed on application, page and even global level. However in each particular ASP page there is one default language, if the developer wants to mix code in other languages this code must be escaped more specifically and its language must be specified in-place (see <SCRIPT RUNAT=SERVER tag below). ALP is pre-configured to support VBScript and JScript, but the developers who want to use other languages can add configuration settings to enable support for them.

Thus the ASP pages structure allows the static and dynamic content to be mixed easily and the static content becomes integral part of the page - it can be repeated, shown conditionally, modified and so on. This saves coding efforts and also makes the page source easy to read from the both points of view - as document (for instance perceived as HTML page with some dynamically generated elements) and as a program (perceived as a program that outputs the non-script elements).   

Page elements

The following embeddings can be placed in a regular ASP page:

• Script code in <% %> and <%= %> tags
• Script code in <SCRIPT RUNAT=SERVER ... > tags
• Directive
• File include statement
• OBJECT RUNAT=SERVER tags

Script code in <% %> and <%= %> tags

There are two script embedding tags <% %> and <%= %>.

• <% %> There is no requirement about tags placement. The important rules are

  - No nesting is allowed
  - Every opening tag <% must have corresponding closing tag %>
  - Tags cannot be mixed with other tag types i.e. Directives and File include
  - Tags must not break unbreakable script language constructions.

<% %> contain script code written according to the used script language syntax. The content of the <% %> tags is executed "as is" without modification. The code is expected to be written in the default page language. 

• <%= %> Are modification of the <% %> tags intended to simplify the coding of the output constructions. Content of the <%= %> tag is translated into an output statement using the default scripting language. This means that such a tag must contain an expression that returns value which can be represented as a string and must be written in the default page language. It is especially useful to generate some dynamic values in non-script parts of the page.

Here is one example:

<%
  For I = 1 To 7
    %>
        <FONT SIZE="<%= I %>">Hello world (font size=<%= I %>)</FONT><BR>
    <%
  Next
%>

The example will output 7 lines of text with growing font size. Obviously it is convenient to use plain HTML to code the output HTML code that will be repeated, but we need to set different font size for each iteration, thus we use <%= I %> to insert the current size into the HTML code each time it is repeated.

In VBScript <%= x %> construction is equivalent of the <% Response.Write x %> and in the JScript to <% Response.Write(x) %>.

One helpful configuration setting is (int)ViewSource. Value of 2 instructs the ASP page processor to show the resulting source of the page if an error occurs and error line is colored in red.

Script code in <SCRIPT RUNAT=SERVER ... > tags 

These tags play a role very similar to the <% %> tags but allow the developer put also code in scripting language different then the default scripting language of the page. The syntax is:

<SCRIPT RUNAT="SERVER" LANGUAGE="languagename" ID="idname">
... script code ...
... script code ...
</SCRIPT>

The rules are the same as for the <% %> tags (see above). The parameters are as follows:
RUNAT=SERVER is required for it gives the ALP ability to distinguish these scripts from the client side scripts in HTML which use similar syntax.
LANGUAGE="languagename" is required. The languagename must specify the key name of the language in which the script in the tag is written. For example it can be VBScript or JScript. Note that ALP is punctual and will treat JScript and Javascript as different languages no matter that in Windows they are aliases for a single language. Make sure you use the same language name across the application.
ID="idname" is optional. It may help you find an error when developing the application. It is listed with the error text when an error occurs in your script and allows you find the <SCRIPT> tag in which it has occurred..

The scripts in RUNAT=SERVER tags may output only by using Response.Write/BinaryWrite. They cannot use <%= %> or another similar technique. However it is recommended to use such script to implement mostly utility routines that are called from the default script language for the page wherever they are needed. This is so because these scripts are initialized before or after the default page script is executed depending on the page settings (see the directives below) and any output made during their initialization will not appear in the place where you may expect it.

For example if you want to implement something in JScript, but use it from ASP pages where the default language is VBScript:

<SCRIPT RANAT=SERVER LANGUGE="JScript">
  function MyJScriptFunction(x) {
    return (x * 3);
  }
</SCRIPT>
<% For I = 1 To 5 %>
  <FONT SIZE="<%= I %>">JScript returned: <%= MyJScriptFunction(I) %></FONT><BR>
<% Next %>

See also the order of execution below. 

Directives

The general syntax of the directives is:

<% @Language=JScript %>
or
<% @Language="JScript" %>

The above example line must be in the beginning of the page - on the first non-empty line. Another requirement is that <% %> tags containing a directive are not be mixed with a script code:

<% @Language=JScript
var i =5;
%>

is illegal! Correct syntax will be:

<% @Language=JScript %>
<%
  var i =5;
%>

When you need to put more than one directive you put them comma separated - for example:

<% @Language="JScript", CODEPAGE=1252, EXECUTEORDER=REVERSE %>

The directive names are not case sensitive as their values. However you should tend to specify the values with the correct case in order to avoid any future incompatibilities.

The supported directives:

Language directive specifies what scripting language is used in the page by default (in all the <% %> and the <%= %> tags). If the directive is not present default language is used from the configuration setting (string)DefaultLanguage. The factory default states VBScript as default language.

CODEPAGE specifies the code page used by ALP to read from the file (and any include files referred in it). This concerns the literal strings and the HTML, text and other non-script content as well. This may look unimportant, but it is recommended to set the directive. For the list of the code page codes you can search the Internet or MSDN or also look in the ActiveX Pack1 constants for some of the most popular ones. By default the code page used is the machine's code page as set in the regional settings. In general all the European languages may do without need to specify this option, but for far-east and other multibyte character sets it is vital to specify the correct code page here. Specifying the code page is a good practice because it guarantees the way the page will be processed no matter what the local machine settings are. In ALP it is more important than the similar setting in IIS, because ALP is designed to work on all the Windows versions including those which do not support UNICODE natively.

EXECUTEORDER is ALP specific directive that allows you to reverse the order in which the scripts written in different languages are executed. The values allowed are REVERSE and NORMAL (in fact any other value then REVERSE will set normal execution order but you should use the keyword NORMAL to avoid incompatibilities with future extensions). If omitted the order is normal (see the execution order below).

File includes

File include statement uses the HTML comment syntax but can be used in other textual documents without a problem (for example in plain text or RTF documents). Samples:

<!-- #include virtual="/includes/file.inc" -->
<!-- #include file="addons/file.inc" -->

If the first word in the <!-- --> HTML comment statement is #include the parser marks the comment statement as an include directive and searches for named values - pairs: name="string". Two keywords are recognized:

• virtual - the value given is a file path relative to the root of the current Virtual ALP site. Must begin with "/". See ALP URL for more information about the how the virtual sites are defined.
• file - the value given is a relative path. The path is relative to the location of the file in which it is found.

The include file must be composed as ASP page. Include directives must be placed outside any <% %> or <%= %> tags. Include file should not contain @ directives. For wider compatibility there must be spaces between the comment open and before the comment close tags and the text of the directive in them. An included file may include other files and so forth. 

<OBJECT RUNAT=SERVER ... > tags

Creates an object and and makes it available to the page under the ID specified. The attributes supported are:

<OBJECT
  RUNAT=SERVER
  PROGID="programID"
  CLASSID="classID"
  ID="name"
></OBJECT>

RUNAT=SERVER is required. If not specified the object will be skipped and ALP will leave the element "as is" for further processing by the viewer/browser.

PROGID or CLASSID - Only one of the both must be specified. If PROGID is used you need to specify the program ID for the object, and if CLASSID is used you must specify the ClassID - {xxxx-....} for the object (autorun applications should use ClassIDs or take care to define own COM aliases in their configuration).

ID="name" specifies a variable name for the object. It is then accessible for the page under this name. This parameter is required (for without it the object would remain inaccessible).

Remarks: Unlike the global.asa file in the regular ASP pages there is no SCOPE parameter. The objects created with this tag in regular ASP pages are available only to the page where they were created. Their lifetime matches the page lifetime.

The execution order

For developer convenience ALP matches the IIS execution order by default. However ALP allows a bit more control over it. In classic ASP the script written in the default script language for the page (i.e. the language assumed for the <% %> tags) is executed second - e.g. all the script code in <% %> tags is initialized after all the <SCRIPT RUNAT=SERVER ...> scripts. ALP supports the EXECUTEORDER directive (see above) that allows you to reverse the order and execute first the default script language parts and then the foreign scripts in the page.

Aside of that the page execution order is as follows:

1. All the file include statements are resolved and the entire ASP page is composed in the memory where the contents of the included files replaces the include statements. The included files are just textually included in the place where the directive is found. So they do not change anything in the execution order.

2. The directives are read and applied.

3. If your page contains <OBJECT RUNAT=SERVER ... > they are resolved before any script is executed no matter where these statements appear. So, by using them you have the objects specified there created from the very beginning of the page execution. As like the objects created through the Server.CreateObject method the objects created with the <OBJECT RUNAT=SERVER ... > tags are allowed to access the ASP objects directly if they support OnStartPage method (event). 

4. All the script placed in <SCRIPT RUNAT=SERVER ...> tags are executed.

5. The page is processed from the top to the bottom and all the script elements in <% %> and <%= %> tags are executed in the order in which they appear.