SIMPOL Server Pages

SIMPOL Server Pages
	Chapter 3. The Superbase NG Project

SIMPOL Server Pages

Description

A SIMPOL server page is a file with the extension smz, the contents of which is HTML but which also includes blocks of SIMPOL source code. The blocks of source code are inside server page comment blocks (in between <% and %> tags), so if we launch the HTML viewer component of the SIMPOL IDE, we will see just the HTML page as if it did not contain any SIMPOL source code.

A project with smz files is a CGI project. This means that the final SIMPOL program is intended to be executed on the server side as a CGI, ISAPI or Fast-CGI program. Typically, a CGI program is called from a web server, for example the Apache web server. The entry point of a CGI or ISAPI program is the main() function, but in this case, the function has only one argument: function main(cgicall cgi). cgi is a cgicall object, and it contains all of the information the web server received from a browser call.

Building a CGI project adds another process to the normal build. First, the smz files are compiled into sma or smu files, and then the normal build follows. When a SIMPOL server page is compiled into SIMPOL source code, the SIMPOL source code in the server page block comments are passed through without change and the HTML is converted into string arguments of cgi.output() statements.

Here is an example of the process followed when building a CGI project:

Project's main server page files: MySPFile1.smz, MySPFile2.smz
MySPFile1.smz — includes —> MySPFile1a.txt
MySPFile1.smz — compiles to —> MySPFile1.sma
MySPFile2.smz — compiles to —> MySPFile2.sma
Project's main source code files: MyFile1.sma, MyFile2.sma
MyFile1.sma — includes —> MyFile1a.sma, MyFile1b.sma and MySPFile1.sma
MyFile2.sma — includes —> MyFile2a.sma and MySPFile2.sma
MyFile1.sma — compiles to —> MyFile1.smp
MyFile2.sma — compiles to —> MyFile2.sml
MyFile1.smp + MyFile2.sml — link to —> MyFile1.smp

The following is an example of SIMPOL server page code:

Example 3.1. SIMPOL Server Page Code

<%'-------------------------- begin code --------------------------
function ShowHelloOrNothing(cgicall cgi, integer i)
'--------------------------  end code  --------------------------%>
<HTML>
	<HEAD><META http-equiv="pragma" 
	  content="no-cache"></HEAD>
	<TITLE>SIMPOL Hello Page</TITLE>
<%'-------------------------- begin code --------------------------
	if(i == 1)
'--------------------------  end code  --------------------------%>
		<BODY>Hello</BODY>
<%'-------------------------- begin code --------------------------
	end if
'--------------------------  end code  --------------------------%>
</HTML>
<%'-------------------------- begin code --------------------------
end function

Results after compiling the server page:

Example 3.2. Compiled SIMPOL Server Page

'-------------------------- begin code --------------------------
function ShowHelloOrNothing(CGICall cgi, integer i)
'--------------------------  end code  --------------------------
	cgi.output("<HTML>" + "{0D}{0A}", 1)
	cgi.output("	<HEAD><META http-equiv=""pragma""" + "{0D}{0A}", 1)
	cgi.output("    content=""no-cache""></HEAD>" + "{0D}{0A}", 1)
	cgi.output("	<TITLE>SIMPOL Hello Page</TITLE>" + "{0D}{0A}", 1)
'-------------------------- begin code --------------------------
	if(i == 1)
'--------------------------  end code  --------------------------
	cgi.output("		<BODY>Hello</BODY>" + "{0D}{0A}", 1)
'-------------------------- begin code --------------------------
	end if
'--------------------------  end code  --------------------------
	cgi.output("</HTML>" + "{0D}{0A}", 1)
'-------------------------- begin code --------------------------
end function
'--------------------------  end code  --------------------------

The advantage of doing this, is that we can create HTML in a dynamic way using the power of the SIMPOL programming language and we can also visualize the HTML in the HTML viewer that is part of the IDE whenever we need it. So it is very easy to embed HTML (what a final user will see in his browser) in a SIMPOL CGI-style program.

The way that SIMPOL server pages work is different to that of ASP, JSP, or PHP. In each of these cases, the source code is also embedded into the HTML but unlike with SIMPOL these mixed-mode pages are then interpreted by the web server (which must be especially designed to be aware of them) and then the code portions are passed to the language interpreters for execution. With SIMPOL server pages, the design style is similar but the results are compiled rather than interpreted, which is faster and also does not require any special capabilities on the part of the web server.

A CGI project can contain any number of server pages. The server pages follow the same pattern as SIMPOL source code files when including files. Each main server page is the root node of a tree of other included files. The Superbase NG IDE manages the file time-dependencies when a build is done, as in the case of source code SIMPOL files.

The Superbase NG IDE provides a way to compile SIMPOL server pages into SIMPOL source code, and a way to regenerate a SIMPOL server page after manipulating the associated (compiled) SIMPOL source code; this allows the programmer to use the color coding capabilities of the IDE for the HTML source when working on the server page and then after compiling, it is possible to work on the SIMPOL program source in the resulting compiled page. After the changes are done to the compiled source, the option to regenerate the server page from the right mouse button popup menu should be used to send the changes back to the server page source code.

	Tip
It is always a good idea to propogate the changes back to the server page source right after making them, since the server page is the reference source code in the project. If you forget, during the next build you will be prompted that the code has changed. If you say okay, your changes will be lost as the compilation of the server page overwrites them. Also, only change code in the blocks between the begin code and end code comments. If you change anything else, it won't successfully regenerate the server page!

Tip

It is always a good idea to propogate the changes back to the server page source right after making them, since the server page is the reference source code in the project. If you forget, during the next build you will be prompted that the code has changed. If you say okay, your changes will be lost as the compilation of the server page overwrites them. Also, only change code in the blocks between the begin code and end code comments. If you change anything else, it won't successfully regenerate the server page!

Server Page Directives

This section covers the syntax of the server page and the specific directives provided.

Multiline Comments

A multiline comment can consist of any piece of text between the start tag <%-- and the end tag --%>. The comment can cover multiple lines and since it is a comment in the server page it will not be transferred to the source code when that is compiled. Only white space (spaces and tab characters) may precede the begin comment tag on the same line, and only white space may follow the end comment tag on the same line.

Server Page Comment Blocks

These comment blocks are similar to the previous type, except that the contents are passed through to the resulting compiled SIMPOL source code file as source code statements. This is the method by which the embedded source code is extracted into the target program source file. Any text between the start tag <% and the end tag %> will be transferred as SIMPOL source code to the target source code file. As in the previous case, the start tag may only be preceded on the same line by white space and the end tag may only be followed on the same line by white space.

`include`

Include the content of a file when the server page is compiled. Example:

<%@	include = ".\folder\MyHTMLChunk.txt" %>

`outputcall`

By default a line of HTML code in the server page file is converted into a line in the SIMPOL source code file after compilation. The HTML text is embedded in a SIMPOL string that is an argument to the output method of the cgicall object. It means that if we have a large server page file, after compilation, lots of output calls are generated. We can optimize this using the outputcall = chunk directive. It can be located at any line in the server page file. To reverse this behaviour we have to use the outputcall = line directive. For example:

<%@ outputcall = chunk %>
<%@ outputcall = line %>

SIMPOL Source Code in an HTML Argument Value

In a line of a server page that holds an HTML argument value in between double quotes, we can add a small piece of SIMPOL source code in between back tick (`) character marks. For example:

<A href="`sVar1`">Hello</A>

Typically it is used to embed a SIMPOL string variable. In this example, after compilation we will get something like this:

cgi.output("<A href=""" + sVar1 + """>Hello</A>" + "{0D}{0A}", 1)

So, we can see that the value of the HTML argument that the browser will receive is the value of the SIMPOL variable. It is also possible to embed short chunks of inline code.