Tutorial #1

Talking to the World...

In this tutorial, we will cover basic NeoWebScript ideas, building simple pages, handling variables and commands, and taking a look at some of the built-in variables and information available. This tutorial is broken down into the following categories:

Probably the most important task NeoWebScript can perform is to put text onto a page. This "simple" task is incredibly important, since that text, in the form of HTML Codes (HyperText Markup Language), describes everything that you see and hear on a webpage. Image placement, links, video clips, Javascript, and audio files are arranged to form the final product under the direction of HTML files. Let's take a look at how NeoWebScript goes about generating HTML:

Calling upon NeoWebScript

From any of your standard web pages, you can call out to NeoWebScript "in medias res" (in the middle of things). Simply insert the following bit of code in your document:

<--#neoscript code='
html "Hello, World!"
'-->

This little snippet tells the web server software that instead of copying out the entire document to the user's browser, it should instead evaluate it, using all of the powerful commands available to NeoWebScript users. Let's take a closer look at the tag above: What does it produce? It generates the following:

Getting the word out

Try entering the above snippet into a web page of yours. You'll see that your page looks the same right up to the NeoWebScript call, and it looks the same afterward, but instead of the <!--#neoscript ... -->, you get the text Hello, World!. That's because we put the html command inside the NeoWebScript segment, or snippet. The html command puts whatever is after it right into the web page. Try using other text, then try the following example:

<--#neoscript code='
html "This is the first line of text"
html "<p>"
html "That was really easy."
'-->

What do we get as a result?

This is the first line of text

That was really easy.

Variables

Even though emitting straight text isn't too exciting, it is very important, since NeoWebScript allows you to send out text that can change with each visit to your page. There are two ways of getting dynamic text out to the browser: Command Substitution and Variables.

In NeoWebScript, a variable is a bit of text that stands for another bit of text. Let's look at the following segment to see how it works:

<--#neoscript code='
set i "This is my text."
html $i
'-->

The segment above ends up looking like this:

This is my text.

The $ before the letter "i" tells NeoWebScript that instead of putting out the letter "i", it should put out what "i" represents. Variables can be made up of letters, numbers, and a few symbols. The following are all valid variable names:

    i  cur_time  theirName  MYNAME  FloridaTaxID
You can group variables together into arrays of data. Using arrays, it is easy to know what variables relate to what. For example, you may want to keep information about a particular task or user together, but still get to the information about that user. NeoWebScript uses parenthases to signify arrays. Take a look at the following example:

<--#neoscript code='
set visitor(name) "Achilles"
set visitor(occupation) "Warrior"
set visitor(nation) "Greece"
set date "March 4, 2007"

html "Welcome, $visitor(name)."
html "You are a $visitor(occupation)"
html "from $visitor(nation)."
html "The current date is $date"
'-->

Emits:

Welcome, Achilles. You are a Warrior from Greece. The current date is March 4, 2007

Saving the Environment

Every time somebody visits your page, the web server software creates an environment for you. The environment is nothing more than a collection of variables that describe the nature of the page, some basic information about the browser hitting the page, and infomation about the web server software. All of this information is kept in an array called webenv. You can easily tap into this set of information at any time, just like you would an array or set of variables that you created.

What kind of information is kept in this array? Here's some of it:

Let's look at an example:

<--#neoscript code='
html "Hello, there.  You are running "
html "$webenv(HTTP_USER_AGENT).<br>"
html "This filename is:  "
html "$webenv(DOCUMENT_NAME). <br>"
html "My server is: $webenv(SERVER_SOFTWARE)."
'-->

This produces:

If you are interested, a complete list of all the environment variables can be found at http://www.neosoft.com/neowebscript/tests/environment.html.

At your command

In addition to variables, NeoWebScript can be dynamic by means of commands. Even though we didn't know about it, we've already visited a command. Remember html? 'html' is a command that takes whatever is after it and puts it into the current webpage. Although this command is very powerful, there are many other ones. They can do things like:

How do we get the results from these commands into out webpage, though? We use Command Substitution. Command Substitution is nothing more than feeding the output of one command into another one. We use the square brackets to accomplish this. Remember the set command? We used it in variables a little while ago. It puts a value into a variable. Instead of setting the variable to straight text, let's set it to the result of the remote_hostname command. The remote_hostname command returns the domain name of the person viewing the page.

Here's an example:

<--#neoscript code='
set host [remote_hostname]

html "Welcome to the page"
html "$webenv(DOCUMENT_NAME).<br>"
html "You are coming from $host.<br>"
html "Have a nice day!<br>"
html "This is another way of doing it, "
html "[remote_hostname]."
'-->

Which produces:

To see a list of all the commands, try going by http://www.neosoft.com/neowebscript/commands/allcommands.html.

Let's try another example. If you look at the NEO_LAST_MODIFIED member of the webenv array, you'll see that the value is not one that we can really use. In fact, it's the number of seconds between the time the document was modified and January 1, 1970! That's not very convenient. Luckily for us, NeoWebScript has a command called clock that can format the result for us. We're going to access the webenv member called NEO_LAST_MODIFIED, feed it into the clock command, then feed that result into the html command. We also want to tell the clock command what to do with our seconds--we want it to format them.

Here's how it all boils down:

<--#neoscript code='
html "This document was last updated"
html "[clock format $webenv(NEO_LAST_MODIFIED)]."
'-->

That produces:

If you're more interested in commands, don't forget that NeoWebScript is based on a language called Tcl, so pretty much anything that works under Tcl will work under NeoWebScript.