ASPCompiler CTS Types
ASP Compiler 1.1 documentation is under development. See also the examples.

Compile Time Scripts are two general types:

Embedded - Using the <SCRIPT RUNAT=Compiler ...> tag they like the other embedded scripts - DHTML and ASP, but are executed during the compilation of the file. As you know client side (DHTML) scripts and ASP scripts have different behaviours, the CTS likes a bit the DHTML (client side) scripts. This means it works with an page object model (POM) of the file. In contrast of the DHTML this object model is simple.

Embedded scripts are able to interact with each other and with the file attached scripts if needed. They include support for SRC attribute that points a script file to be loaded. The script can be moved outside the page in a text file that is more convenient for you. Also this could be combined with the script inside the SCRIPT tag - file from the SRC attribute is loaded first and then the script from the tag. This allows reuse of parts of the code.

File attached scripts - reside in text files in the project or the global CTS directory and are attached to the entire files. They are notified when the file is loaded, parsed, created and may perform much more complex tasks. File attached scripts are able to access the page object model (POM) available for the embedded scripts too, but they are also able to control the entire processing of the file and invoke multiply processing operations of the file and produce many files from it. This may include different settings for each operation, cooperation with the embedded scripts found in the file and so on.

File attached scripts could be also packed as CTS packages and redistributed to other machines, enriched with configuration and help dialogs. Because they have almost full control over the file processing, different scenarios could be programmed and organized in easy to use again form.

The page object model of the processed files is the same for the both types, but the script object model and APIs are different in details. The differences are caused by the fact - the embedded script has their location in the page and the file attached script works with the entire file and accesses the page object model from outside. Other difference is that embedded scripts are executed sequentially - when found in the file, while the file attached scripts must provide certain routines called by the ASPC to inform them for the current operation and allow them to perform their tasks and alter the operation if needed.

Details and samples

Embedded. The following code represents the traditional "Hello World" example:

  <SCRIPT RUNAT=Compiler Language=VBScript>
    node("Class") = "Text"
    node("Content") = "<H2>Hello World!</H2>"

It will produce the "Hello World!" output in H2 tags in the place where the script resides in the file. While this example looks dummy accessing a compiler variable defined for the file makes it more reasonable:

  <SCRIPT RUNAT=Compiler Language=VBScript>
    node("Class") = "Text"
    node("Content") = Variables("MyVariable")

This will place the value of the compiler variable instead of just "Hello World!" and thus will make possible to alter the output from the ASPC GUI (See also the Compiler Variables). If we change the line dealing with the variables to:

node("Content") = GlobalVariables("MyVariable")

The code will use the content of the global "MyVariable" defined for the entire project. Imagine you want to build set of static HTML pages but you need to compile them in few different forms with some texts changed - then this makes sense.

In the embedded code you can create ActiveX objects and thus access DB, files on the hard drive and anything else. A little example:

Let this code is in the file db.vbs in the same directory where the compiled file resides:

Dim db, rst
Set db = CreateObject("ADODB.Connection")
Set rst = db.Execute("SELECT * FROM MyTable WHERE Name='" & Variable("Name") & "'")
node("Class") = "Text"
node("Content") = "<TABLE>"
While Not rst.EOF
  node("Content") = node("Content") + _
        "<TR>" & _
        "  <TD>" & rst("Name") & "</TD>" & _
        "  <TD>" & rst("Age") & "</TD>" & _
        "</TR>" & vbCrLf

Then we can put in the file the following:

<SCRIPT RUNAT=Compiler Language=VBScript SRC="db.vbs"></SCRIPT>

And this will be replaced by the results of the query. The variable "Name" from the file options will adjust the query thus including this line in different files can produce different results depending on the value of the variable defined for the file.

In the preceding example code file was specified as SRC="db.vbs" and it has been loaded from the current directory. If the project has more complex structure it may contain several directories and you may want to use this db.vbs file in HTML files from different directories. You can do that by using for example SRC="../scripts/db.vbs" - a relative virtual path, but if you need to move this file to the root directory of the project, for example, you will need to change it to SRC="scripts/db.vbs". There is a better method - full virtual path: SRC="/scripts/db.vbs" this will load the file from the scripts subdirectory of the project's source directory tree. Thus moving the file across the project will not require file modification.

What if you want to use it in many projects? Then you could use the same SCRIPT tag but place the db.vbs in the global CTS directory. It is in the ASPC install location (usually program files\newObejcts\ASPC\scripts). You will need to create subdirectory scripts (program files\newObejcts\ASPC\scripts\scripts) and place the file there. Then if the compiler cannot find the file in the project tree it will search for it in the global directory and the script will be available for all the projects on the machine. The setup creates a shortcut to the CTS global directory in the ASPC program group.

Except Variables and GlobalVariables there are some more objects available for the CTS:

Project - hierarchical collection of the project and files' settings. Most important parts of it are already available for the script through more convenient namespaces - ProcessedFile, Variables and GlobalVariables, but if the script needs to access some other data stored in the project it can use this namespace to read it. Writing to the collection is possible but not recommended. However if you need this technique note that changes will not be saved - they will be available to the end of the current build.

Compiler - The Compiler object provides methods for Error, Warning and other reports. Reports are collected in the output window together with the other compiler messages. Thus if the script requires something the user forgot to do (such as variable) it is able to show the requirement as an error or warning message.

ProcessedFile - Points the file settings in the project file.

Node - This is the node the script occupies. E.g. this is the representation of the own SCRIPT tag in the page object model. The above samples replaced it with something else and thus they produced output in the page.

Tree - If the script wants to access another nodes of the page object model they use this collection to search for the node. It contains the script node (above) in the corresponding place. Current version of ASPC serves here a linear collection. It is not tree in fact, but name "Tree" was used to mark that future evolution will extend the page object model.

Script - collection of all the SCRIPT RUNAT=Compiler nodes from the Tree. The embedded script is able to find them and call a sub or function from another script. But please note the order is important - thus a script defined under another will be able to call it but the preceding script will not! To avoid need of keeping the order of the scripts it is recommended to do such tricks from file attached scripts instead.

Custom - collection of all the <CUSTOM> tags in the page. They are also listed in the Tree.

Variables and GlobalVariables - point to the file compiler variables and to the project's compiler variables respectively.

File attached. These scripts are a bit different from the embedded CTS. As you can see above, the embedded scripts are executed directly. In contrast file attached scripts will do nothing when loaded they will initialize and wait for ASPC to fire events to them. What will like a "Hello world!" example written as file attached script?

 ( ... continues ... ) Copyright 2001-2006 newObjects [ ]