|
|
Introduction to APGen |
|
See Also: |
This topic assumes you are an intermediate Active Server Pages (ASP) developer. If you are not an ASP developer, begin with the topics APG Scripts and Executing APG Scripts.
Active Page Generator (APGen) is used to programmatically generate files and content. APGen is a useful tool for:
In order to develop APGen solutions, you need basic programming skills, web development skills and the ability to program in VBScript and/or JScript.
ASP programmers will find the APGen programming model easy to master. APGen uses a similar script file format to ASP, the same scripting languages as ASP, and the same editors and debuggers as ASP. See a Comparison of ASP to APGen for more similarities.
We'll start with a simple ASP page that you, as an ASP developer, already understand. Then, we'll show you how to apply your existing skills to the APGen programming model.
This tutorial is intended to introduce ASP developers to APGen programming, by showing how an ASP file can be converted to an APG script. In this example, APGen provides overlapping functionality with ASP. This tutorial does not discuss the complete scope of APGen use - there are numerous uses for APGen where ASP is not viable. Similarly, there are many situations where ASP is a much better choice than APGen. This tutorial uses the area of overlap for instructional purposes. For more complete APGen solutions, see the examples and the APGen Examples topic.
Following is a simple ASP file that queries data from an Access database, and displays the data to a web page. If you have the NT Option Pack installed, you can perform the following steps to run this ASP file:
aw_equip.mdb is correct in the cn.Open line.
The Access database used in this example is installed with the "Adventure Works Examples" portion of APGen setup.
<%
' -------------- test.asp ----------------------
' Display a table showing all products in the
' Adventure Works Equipment database
'
Option Explicit
Dim cn, rsProducts, strSQL
' Open the ADO connection
Set cn = Server.CreateObject("ADODB.Connection")
cn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\APGen\Examples\awe_asp\db\aw_equip.mdb;"
' Query for all the products
strSQL = "SELECT ProductCode, ProductType, " & _
"ProductName, UnitPrice FROM Products " & _
"ORDER BY ProductType, ProductName"
Set rsProducts = cn.Execute(strSQL)
%>
<HTML><BODY>
<H3>Product List</H3>
<TABLE border=1 cellpadding=3 cellspacing=0>
<COLGROUP><COL><COL><COL><COL>
<TR>
<TD align=center><B>Product Code</B></TD>
<TD align=center><B>Product Type</B></TD>
<TD align=center><B>Product Name</B></TD>
<TD align=center><B>Unit Price</B></TD>
</TR>
<%
' Loop through all the products
Do While Not rsProducts.EOF
' Write out a table row
%>
<TR>
<TD><%= rsProducts("ProductCode") %></TD>
<TD><%= rsProducts("ProductType") %></TD>
<TD><%= rsProducts("ProductName") %></TD>
<TD align=right>
<%=
FormatCurrency(rsProducts("UnitPrice")) %>
</TD>
</TR>
<%
rsProducts.MoveNext
Loop
%>
</TABLE>
</BODY></HTML>
Viewing this example in your browser, you'll see:
This example runs fine. Why convert it to APGen?
There are two significant reasons why you might want to use APGen for this specific page:
Before we continue the example, let's discuss these reasons in more detail.
One of the optimization techniques using APGen involves improving performance by posting a static page to the web server. Static pages perform far better than completely dynamic pages. APGen can also generate dynamic pages that perform better than the original dynamic page - this is called Two-Phase Content Generation. For more information see Static Page Generation and Two-Phase Content Generation. For this example, we will use Static Page Generation.
The performance gains that can be realized by using APGen are dependent on page functionality: In some cases, no gains can be achieved; in other cases, gains of 100 times can be achieved. For a thorough discussion of when and where to use APGen refer to Web Site Optimization Techniques.
If you want to view data in a web page, but you do not have (or do not want to use) an ASP web server, you can not use dynamic pages. APGen can publish data to static pages. APGen is the perfect solution for:
For example, this APGen documentation was generated using APGen. This sort of documentation must be static, because no web server lives in HTML Help. However, it is desirable for maintenance reasons to make pages programmable and data-driven - thus APGen is used to generate the header, footer, and "See Also" links from an XML file.
Let's return to the example. We will now convert the ASP file to an APG script.
There are several steps in converting an ASP file to an APG script:
The ASPToAPG Example can be used to automatically perform this conversion for individual ASP files, or for directories containing ASP files. For this tutorial, we will convert the file manually to illustrate the similarities between ASP and APG.
For details on APG script tags, see APG Script Syntax Reference. For the intrinsic objects available to an APG script, see APG Script Intrinsic Objects.
A standard APG script, run outside of IIS, does not have access to the ASP intrinsic objects. There is no request, response, or cookies, because the script is being run outside of a web server. APG scripts that are run in ASP pages can use the ASP objects - see Executing APG Scripts in Active Server Pages.
ASP terms can be converted to APG terms as follows:
Figure 2: ASP to APG Conversion
| ASP Term | Convert To |
| <% | <%# |
| %> | #%> |
| <SCRIPT Language= "VBScript" RUNAT= Server> | <SCRIPT Language= "VBScript" RUNAT= APGen> |
| <!-- #include file="file.inc" --> | <!-- #include apg="file.inc" --> |
| Response.Write | Output.Write |
| Response.BinaryWrite | Output.BinaryWrite |
| Response.Buffer | Output.Buffer |
| Response.Clear | Output.ClearBuffer() |
| Response.Flush | Output.FlushBuffer() |
| Response.AppendToLog | Log.Write |
| Response.End | Script.Abort |
| Server.CreateObject() | Script.CreateObject() |
| Server.HTMLEncode | Util.HTMLEncode |
| Server.URLEncode | Util.URLEncode |
| Application(key)* | APGen(key)* |
| Session(key)* | APGen(key)* |
| Request(key)* | Script(key)* |
| Request.QueryString(key)* | Script(key)* |
| Request.Form(key)* | Script(key)* |
| Server.MapPath(path)* | Util.ConcatPath(Script.Dir, path)* |
To generate an entirely static page, use the table above to convert all ASP terms to the equivalent APG script terms.
Many pages can not be converted to 100% APG script: For example, if an ASP page uses the ASP Session object, Request.Form object, or ObjectContext object, you may not be able to convert all ASP script blocks to APG script blocks. APGen gives you the ability to perform some of the page rendering using APGen, and the rest of the page rendering using ASP - this is called Two-Phase Content Generation. While generating static pages provides the best performance, using Two-Phase Content Generation can result in performance gains of 50% to 100 times.
Converting an ASP script block to an APG script block is easy to do: Just insert the # character inside the ASP script delimiters. If the block contains references to ASP objects, convert the terms shown in Figure 2 to the APG equivalent. If the block contains references to ASP object methods and an APG equivalent is not available (the ASP term is not listed in Figure 2), that is an indication that it may need to remain as an ASP script block.
To convert the test.asp example file to an APG script:
APG scripts are normally run to generate content, and that content is usually placed in a file. You need to specify where you want to send the content. This should be done before any content is generated. For more information, see When to Open the Output Stream.
For the example script, this task is handled by adding this line to the beginning of the script:
<%#
...
Output.Filename = "test.htm"
...
This single line of script says, "create the file 'test.htm', and send all of the generated content to this file."
After finishing the 3 steps above, test.apg looks like this:
<%#
' -------------- test.apg ----------------------
' Display a table showing all products in the
' Adventure Works Equipment database.
' Creates file test.htm.
'
Option Explicit
Output.Filename = "test.htm"
Dim cn, rsProducts, strSQL
' Open the ADO connection
Set cn = Script.CreateObject("ADODB.Connection")
cn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\APGen\Examples\awe_asp\db\aw_equip.mdb;"
' Query for all the products
strSQL = "SELECT ProductCode, ProductType, " & _
"ProductName, UnitPrice FROM Products " & _
"ORDER BY ProductType, ProductName"
Set rsProducts = cn.Execute(strSQL)
#%>
<HTML><BODY>
<H3>Product List</H3>
<TABLE border=1 cellpadding=3 cellspacing=0>
<COLGROUP><COL><COL><COL><COL>
<TR>
<TD align=center><B>Product Code</B></TD>
<TD align=center><B>Product Type</B></TD>
<TD align=center><B>Product Name</B></TD>
<TD align=center><B>Unit Price</B></TD>
</TR>
<%#
' Loop through all the products
Do While Not rsProducts.EOF
' Write out a table row
#%>
<TR>
<TD><%#= rsProducts("ProductCode") #%></TD>
<TD><%#= rsProducts("ProductType") #%></TD>
<TD><%#= rsProducts("ProductName") #%></TD>
<TD align=right>
<%#=
FormatCurrency(rsProducts("UnitPrice")) #%>
</TD>
</TR>
<%#
rsProducts.MoveNext
Loop
#%>
</TABLE>
</BODY></HTML>
Running an APG script is as easy as double clicking the file within Windows Explorer. Or, you can right click on the file and choose "Run" from
the context menu. Or, you can run the script by typing the file name at
the command prompt. If you are following along with the example, then go
ahead and run test.apg.
APG scripts can also be run programmatically. APGen exposes a series of COM interfaces for running APG scripts, so the scripts can be run from VB, ASP, SQL Triggers, VBA, VJ++, C++, Delphi, Windows Scripting Host, .NET applications, or other APG scripts. For more information, see Programmatic Execution.
The script test.apg renders a snapshot of the product database into a static HTML file. This is a great solution until changes are made to the database. When the product database changes, the script test.apg needs to be run to keep the output file current. This step can be automated in several ways:
This step does require additional effort, but this is a simple tradeoff to experience large performance gains. If your data changes constantly, or the page does not receive much traffic, then ASP may be a better solution. If performance is important, and your data changes less frequently than it is viewed, then APGen may be the best choice for data publishing.
If you have installed Visual InterDev 6 or the NT Option Pack Script Debugger, then you are ready to debug APG scripts. Visual InterDev 6 is the preferred editor and debugger for APG scripts. The NT Option Pack Script Debugger is an acceptable alternative and is free.
To begin, insert a VBScript stop statement in a script block, and then run the script. When the stop statement is executed, you will be prompted to debug the script. If you select yes, the debugger will be run, and execution will be halted at the stop statement. Now you can set breakpoints, examine variables, execute code in the immediate window, and step through the script.
Run-time errors in the script code will also trigger just-in-time debugging. When a run-time error is encountered, a dialog box is opened. This dialog box describes the error and asks you if you would like to open the debugger.
For more information on debugging, see Debugging APG Scripts.
To view the example output page, point your browser to http://localhost/<same virtual root path as before>/test.htm. It looks like this:
APGen is a great tool for data publishing, and an even better tool for building web sites. APGen scripts can be used to design and build web sites to simplify site creation and site maintenance. See Automating Web Page Authoring for more information.
For more information on using APGen to improve the performance of ASP sites, see Web Site Optimization Techniques.
A good way to learn to use Active Page Generator is to investigate the examples that are (normally) installed at \Program Files\APGen\Examples. Review the readme.htm files, and run the example APG scripts. Review the code by right clicking on the APG script and choosing "Edit". For the best understanding of each example, use a script debugger and step through the script. See the Debugging section above for more details.
To learn more about APGen, read these topics: