Part 4: Creating New Pages

Automating Creating New Pages

If you plan on creating many new page scripts that use RenderPreContent and RenderPostContent, then you should automate the process of creating them. This is the the focus of this example. Once again, we will use the data in site.xml.

When we are finished, this will be the process for adding new pages to the site:

Add webpage entries for all new pages to site.xml. Make sure the written attribute is false.
Run the script BuildNewPages.apg. This creates new starter pages.
Edit the starter pages as needed. Once a page is edited, its written attribute in site.xml should be set to true.
Run build.apg to rebuild the site.

New page scripts will be generated for each webpage element in site.xml with written = False.

This is a little complicated, because we are using an APG script to generate one or more APG scripts. But, anything to save work.

Trial Run

To make this example easier to understand, we will go through a trial run so that you can follow what happens. Then, we will discuss the code in detail.

First, let's add a webpage item to site.xml for a new page, logflags.htm. The copy of site.xml in the aut_auth\NewPages\ directory already has this entry:

Note that we set the webpage title attribute to "Log.Flags (r/w)", the fname attribute to "logflags.htm" (the filename for the page in our final site), and we set written to false.

Next, run BuildNewPages.apg by double-clicking the script file. You see that a new APG script is created, logflags.apg. Logflags.apg looks like this:

<%#
' ----------------------------------------------------------
'     logflags.apg
'
'     Creates the file logflags.htm, using formatting from
'     template.apg.
'
'     This file was created by NewPageTemplate.apg
' ----------------------------------------------------------

Output.Filename = "logflags.htm"

RenderPreContent "Log.Flags (r/w)"
#%>
Insert Body Text Here
<%#
RenderPostContent

#%>

Notice that logflags.apg is similar to hello.apg, which was written in Example 1. Logflags.apg will create logflags.htm, and will use the formatting from template.apg (also discussed in Example 1 ).

Next, run the new logflags.apg script. File logflags.htm is created, which looks like this:

We have really reduced the amount of work required to add a new page to the site! This is especially worthwhile if you plan on adding many pages.

Notice that we have not added any body text to the page. After you add a new page script to your site (like logflags.apg), you will replace the "Insert Body Text Here" with some real page content.

After you add some content to the generated page script, make sure that you set the page's written attribute to True in site.xml. If you do not set the attribute to True, then your changes will be overwritten the next time you run BuildNewPages.apg.

Code Discussion

BuildNewPages.apg is similar in structure to Build.apg (from Part 3 ): Sub Main loads the XML object, and uses recursion to walk the XML tree. The recursive procedure is BuildNewPage. BuildNewPage is actually called for every webpage in the site, but BuildNewPage does not do anything unless the written attribute is false:

Sub BuildNewPage (oXmlElt)

     ' Check if the page is written
     Dim bWritten
     bWritten = CBool(oXmlElt.getAttribute("written"))
     If Not bWritten Then

          ' Build a new page template

          ' Figure out the APG script filename for this oXmlElt
          ' Do this by replacing the filename extension with "apg"
          Dim strFname, strAPGFname
          strFname = oXmlElt.getAttribute("fname")
          strAPGFname = Left(strFname, InStrRev(strFname, ".")) & "apg"

          ' Load NewPageTemplate.apg
          Dim oScriptNPT
          Set oScriptNPT = g_oAPGen.OpenScript("NewPageTemplate.apg")

          ' Set the output file (created file will be an APG script)
          oScriptNPT.Output.Filename = strAPGFname

          ' Set values for fname and title
          oScriptNPT("fname") = strFname
          oScriptNPT("title") = oXmlElt.getAttribute("title")

          ' Run it
          oScriptNPT.Run

     End If

     ' Recursively call BuildNewPage on all children
     Dim oChildElt
     If Not oXmlElt.children Is Nothing Then
          For Each oChildElt In oXmlElt.children
               BuildNewPage oChildElt
          Next
     End If

End Sub

If a webpage is not written, then BuildNewPage computes the filename for the page script by replacing the extension of the fnamevalue with "apg". Sub BuildNewPage opens the APG script "NewPageTemplate.apg" using APGen.OpenScript. BuildNewPage sets the Output.Filename for the script, which is "logflags.apg" in this example. BuildNewPage also sets some APGScript.Values: The fname value is passed in ("logflags.htm" in the trial run); and the title value is passed in ("Log.Flags (r/w)" in the trial run). Then NewPageTemplate.apg is run.

Which brings us to NewPageTemplate.apg. This is the script that is responsible for generating another APG script. First, let's review the code:

<%#
Option Explicit
'--------------------------------------------------------------
' NewPageTemplate.apg
'
' Template for new pages. Yes, this script generates
'     another APG script.
'
' Parameters "fname" and "title" must be specified.
' This script CAN'T be run interactively.
'--------------------------------------------------------------

'--------------------------------------------------------------
' These subs can be used to make the Output File an APG script
'--------------------------------------------------------------

Sub WriteOpenAPGBracket
     Output.Write("<" & "%" & "#")
End Sub

Sub WriteCloseAPGBracket
     Output.Write("#" & "%" & ">")
End Sub

Sub WriteAPGInclude (strIncludeFile)
     Output.Write("<" & "!-- #include apg=""" & strIncludeFile _
                    & """ -->" & vbCRLF)
End Sub

Sub Main

     ' extract filename and title
     Dim strFname, strTitle
     strFname = Script("fname")
     strTitle = Script("title")

     ' Error handling
     If (Len(strFname) < 1) Or _
          (Len(strTitle) < 1) Then
          MsgBox "NewPageTemplate.apg requires 'fname' " & _
                    "and 'title' values."
          Script.Abort
     End If

     '----------------------------------------------------
     ' Write page content
     '----------------------------------------------------
     WriteAPGInclude("template.apg")
     WriteOpenAPGBracket #%>
' ----------------------------------------------------------
'     <%# =Output.Filename #%>
'
'     Creates the file <%# =strFname #%>, using formatting from
'     template.apg.
'
'     This file was created by NewPageTemplate.apg
' ----------------------------------------------------------

Output.Filename = "<%# =strFname #%>"

RenderPreContent "<%# =strTitle #%>"
<%#     WriteCloseAPGBracket #%>
Insert Body Text Here
<%#     WriteOpenAPGBracket #%>
RenderPostContent

<%#     WriteCloseAPGBracket

End Sub 'Main
#%>

Since Output.Write("<%#") will cause an error, we wrote procedures WriteOpenAPGBracket and WriteCloseAPGBracket. Both procedures send an APG script bracket to the output stream. Similarly, WriteAPGInclude sends an include file tag to the output stream.

Sub Main writes content to the output file (logflags.apg in the trial run). But first, Sub Main retrieves the "fname" and "title" Script.Values that were set by BuildNewPages.apg. We added an error handling block to ensure that the "fname" and "title" values were passed in. If the variables are missing, then a MsgBox is displayed and the script aborts.

Once the "fname" and "title" values have been retrieved, Main writes the new APG script's content to the output file.

Review

After walking through 4 examples that Automate Web Page Authoring, we have a web site solution that has the following advantages:

Shared content is placed in procedures. This makes shared content easier to reuse, maintain, and modify. In our example, the shared content is HTML formatting that is used in multiple pages.
Navbars are built automatically. You have absolute control over the appearance of the navbar, without the burden of updating navbars every time you add, move, remove, or rename pages. Make sure to keep the information in site.xml current!
The web site can be built by running a single APG script, build.apg. Build.apg writes all common content, navbars, etc. to an output directory, and copies the necessary accessory files.
To move, remove, or rename a page, just update the information in site.xml, and run build.apg.
To change the formatting of all the pages, make changes to template.apg, and run build.apg.
To change the appearance of the navbar or the behavior of all pages, change RenderNavBar in template.apg, and run build.apg.
To add new pages to the site, add a new webpage item to site.xml for each new page, and run BuildNewPages.apg. Then, add content to each new page script, and change the webpage written attribute to True. Run build.apg to build the web site.

The solution that we have created can be adapted to automate your web site development projects. If your web site project is vastly different from our example, then you should have ideas on how to use APGen in other ways to simplify your web development efforts.

Taking it Further

To take web site automation further, the next step supports multiple templates, and it supports page content being stored in multiple formats. This approaches the functionality of a simple Content Management system.

Continue with Part 5: Multiple Templates and Multiple Content Types...