How To Build Your Own Pages Using 20/20 DataShed's Engine

Step 1: Create a new .asp page and write the necessary code to "consume" 20/20 DataShed's features.

1. On a typical web site, 20/20 DataShed's source files are probably in the same folder as the other pages of the site. For example, you might have .html files in the same folder as the "listings.asp" and other 20/20 DataShed scripts.
   
   In this example, you can see the following normal pages in the same folder as 20/20 DataShed's scripts.
   • about.html
   • companyinformation.html
   • contactus.html
   • index.html
   For this tutorial, let's create a new page for the web site and we'll call it "hello-world.asp".
2. Open a text editor such as NotePad. You may also use an HTML editor and select the option to edit the "HTML source" directly.
3. Save the new document as "hello-world.asp" to your hard drive. (You may wish to save it to a specific folder if you keep a local copy of your web site on your own computer.) Note, if you save the file using Notepad, then Microsoft Windows might append the .TXT extension to your file. Please ensure that the file is called "hello-world.asp" and not "hello-world.asp.txt" -- to do this you might need to alter the "Folder Options" in Windows Explorer so that the file extensions are not hidden.
4. With NotePad still open, copy-n-paste the following code into the new document:

   <%@ Language="VBScript" ENABLESESSIONSTATE="False" %>
<%
Option Explicit
response.buffer = true
response.expiresAbsolute = #1/1/2000#
response.CacheControl = "Private"

dim booleanIsParentFolder
booleanIsParentFolder = True
%>
<!--#include file="_globals.asp"-->
<% Inject "","","template.html" %>


<% SUB Process2020Page %>

<h1>Hello World!</h1>

<% END SUB %>

5. Save the file.
6. Upload it to your web site! (Please...if you already have a file named "hello-world.asp" then give this file a different name before uploading it to your web site.)
7. Then visit this new page in your web browser. You should see the words "Hello World!" inside DataShed's HTML template.
8. If this works properly, then carry on to the next section: Step 2.

Step 2: Explanation of the code in this basic example.

If you don't care to understand the code...then skip to the next section. However, we recommend it's probably important to have at least a basic understanding of the most important elements of this example code.

<%@ Language="VBScript" ENABLESESSIONSTATE="False" %>

This line contains the language declaration (Language="VBScript") and identifies the file as an ASP document (<% %>).

This line also instructs the web server to disable "sessions": (ENABLESESSIONSTATE="False"). This instruction is optional. We have chosen to disable sessions throughout 20/20 DataShed because doing so saves a considerable amount of overhead on the web server and DataShed doesn't require sessions for any internal features.

If your purposes require sessions, then you could rewrite this line as follows: <%@ Language="VBScript" %>

Option Explicit
response.buffer = true
response.expiresAbsolute = #1/1/2000#
response.CacheControl = "Private"

We have used this header throughout 20/20 DataShed. Unless you have good reason to remove or alter these options, we recommend you leave them as they are.

dim booleanIsParentFolder
booleanIsParentFolder = True

This variable should be set either to True or False.

True indicates that the file resides in the parent folder of 20/20 DataShed. (The same folder as the _globals.asp file.)

False indicates that the file resides in the sub folder of 20/20 DataShed. (The same folder as the _locals.asp file.)

In this tutorial, we've assumed that you will locate this file in the parent folder.

<!--#include file="_globals.asp"-->

This SSI reference instructs the web server to include the _globals.asp file in this document.

This line ensures that all of 20/20 DataShed's "global" functions and features are available to your new web page. Features such as the skinning engine!

<% Inject "","","template.html" %>

This line invokes DataShed's skinning engine. Cool eh? Just one little line. Actually this line calls the "Inject()" function (which in turn process the HTML template and contains some other logic).

The "Inject()" function accepts three arguments:

1. CallingPage: What is the name of this page? In our example, we've left this blank but you could rewrite it like this:

   <% Inject "hello-world.asp","","template.html" %>

   `
2. PageTitle: What "title" do you want to appear in the web browser? In our example, we've left this blank but you could rewrite it like this:

   <% Inject "hello-world.asp","Welcome to My Web Site!","template.html" %>

3. strTemplateFileName: What is the file name of the HTML template to process? In our example, we have used the usual "template.html" but it's actually possible to call specific files if you wish. Perhaps your home page should have a different template than the other pages on your site, you could create a template specifically for that purpose and call it like this:

   <% Inject "hello-world.asp","Welcome to My Web Site!","myHelloWorldTemplate.html" %>

   Note that the line above is an example only...it won't actually work unless you've had already created a template file called "myHelloWorldTemplate.html" and placed it into the "templates" folder.

The most important thing about this line is the fact that it will in turn call a subroutine called "Process2020Page()". That is discussed next.

<% SUB Process2020Page %>

<h1>Hello World!</h1>

<% END SUB %>

The "Inject()" function discussed earlier will call this sub routine.

The contents of this subroutine will be injected into the template. Therefore, this will become the most important subroutine for you to understand and manipulate and we'll discuss this in more detail in the next section: Step 3.

Step 3: Create some example content for the new page.

In the previous section we saw this subroutine:

<% SUB Process2020Page %>

<h1>Hello World!</h1>

<% END SUB %>

We can add HTML and/or ASP code to this subroutine and it will be injected into the template's body. In this manner you can create virtually any content you like.

To continue this tutorial, we'll create some basic content within the subroutine so that it will be displayed on the web site inside your template.html file.

1. With this file still open in your text editor, add any content you wish to this subroutine.

   <% SUB Process2020Page %> (<-- Don't edit this line!)
   
   (Put your own content here!)
   
   <% END SUB %> (<-- Don't edit this line!)

   Perhaps like this: (Note that this example combines basic HTML with some ASP -- the "Now()" function).

   <% SUB Process2020Page %>

<h1>Welcome!</h1> <p>Hello, world! This page on our web site is created by <i>me</i> and by <a href="http://www.2020datashed.com/">20/20 DataShed</a>.</p>

<p>The current time is <%=Now()%>.</p>

<% END SUB %>

2. Save and upload the file to your web site.

Step 4: Utilize a few functions and features of 20/20 DataShed within the new page.

We will not get into a full list of available functions...(sorry, maybe we'll expand on this tutorial in the future). However, suffice to say that any subroutine or function in the _globals.asp file is available to your new page. Perhaps you should scan through the source code of _globals.asp and you may discover some functions that will be useful in your new page.

We'll incorporate four of DataShed's functions into this tutorial:

DisplayDate()

A function which 20/20 DataShed uses to validate and format date/time data.

MakeAbsoluteURL()

A function which will reformat a file name to an "absolute" URL.

GetDBConnection()

A function which will open a connection to DataShed's database. Note that a global variable called cn stores the connection.

Destroy()

A function used to close and clean up the database connection.

1. Try the following code:

   <% SUB Process2020Page %>

<h1>Welcome!</h1> <p>Hello, world! <a href="<%=MakeAbsoluteURL("hello-world.asp")%>">This page</a> on our web site is created by <i>me</i> and by <a href="http://www.2020datashed.com/">20/20 DataShed</a>.</p>

<p>The current time is <%=DisplayDate(Now(),13)%>.</p>

<%
dim lngNumberOfListings
dim objRecordSet

CALL GetDBConnection(0,0,1)

set objRecordSet = cn.Execute("SELECT Count(items.itemID) AS numberOfListings FROM items;")

lngNumberOfListings = objRecordSet("numberOfListings")

Destroy(objRecordSet)
Destroy(cn)
%>

<p>Our web site has <%=lngNumberOfListings%> listings.</p>

<% END SUB %>

2. Save and upload the file to your web site.