This section covers most of the issues regarding HTML and HTTP that relate directly to writing web-based JACL games. Also covered are the JACL commands that directly relate to the output of HTML. If you are not familiar with HTML, however, it is highly recommended that you read at least a basic tutorial before starting to write your first game.
A complete HTML page, including the HTTP header, must be returned by you game in response to each of the player's moves. To assist with this, there are two functions included in frame: +header and +footer. The function +header is executed by the JACL interpreter before any other processing of the player's move is performed. It is reproduced here:
{+header
write "Content-type: text/html"
write "Expire: -1^^"
write "<HTML><HEAD>"
write "<TITLE></TITLE>"
execute "+styles"
write "</HEAD><BODY bgcolor=~blue~>"
write "<FORM NAME=~GameForm~ METHOD=get ACTION=~" $url "~>"
}
The first two lines of this function output the HTTP header. The first line tells the web browser that it is about to receive an HTML page, while the second prevents the browsers from caching any of the pages. The two carets at the end of the Expire line are very important. An HTTP header is delimited by a blank line (the result of two linefeeds). Without this blank line the page will not be displayed.
The following the HTTP header is the HTML header. The title of your game should be placed between the two <TITLE> tags. This is the title that will appear at the top of the browser window. Before the HTML header is closed, the function +styles is called. This function outputs all the CSS styles information to control presentation. Feel free to modify this function to suit your taste.
The body of the HTML document is then started, specifying that it should have a blue backgro und. The only part of the HTML body that is automatically written is the open tag for a form. T his is the form that will be submitted when the player makes a move.
The function +footer is the very last function to be executed after a player's move have been processed. It is reproduced here:
{+footer
write "<hr><center>"
execute "+exits"
prompt
execute "+score"
write "</centre>"
write "</FORM>"
write "</BODY></HTML>"
}
This function begin by drawing a horiztonal line across the screen then calling a function that displays all the possible exits as hyperlinks. The next line contains a prompt command. This command displays the text input box where the player types their moves. See below for more information on the prompt command. Next, the function +score is executed to display the player's current score and the number of moves they have made. The final step is the close the document with matching </FORM>, </BODY> and </HTML> tags.
HTTP is a stateless protocol. This means that each request received by the web server is completely independent of any that has come before it. The JACL interpreter, however, needs to know which player each request has come from, and more specificly, what state the game world was in at the end of their previous command. For this reason, a unique user ID must be sent with each of the player's commands. Failure to do so at any time will result in the game restarting from the beginning and a new user ID being assigned automatically.
To propogate the player's user ID, it must be passed as the HTML parameter user_id. This is done by including it as a hidden field in any forms, or as a URL parameter in any hyperlinks. The token $user_id maybe be used in any write statement to output the automatically generated ID. Below are two examples of its use:
write "<a href=~" $url "?user_id=" $user_id
write "&command=look~>Look</a>"
write "<input type=~hidden~ name=~user_id~ "
write "value=~" $user_id "~>"
In the first set of write statements, the token $user_id is added directly to the end of the URL being linked to. Also used is the token $url. This token displays the URL of the game, such as /fastcgi-bin/game.jacl.
The second set of write statements ouput a hidden field. This field should be used as part of an HTML form when the player issues their commands by submitting this form.
When using an HTML form, there are two simpler methods of including the player's user ID. The first is the command hidden. This command outputs a line exactly like the input tag above. Below is an example of its use:
write "<form>" write "<input type=~text~ name=~command~>" hidden ;adds the player's user ID as a hidden field. write "</form>"
As you can see, there is nothing difficult about using the hidden command. The second related command is prompt. This command outputs a text input box and the player's user ID. Using prompt, the above code snipet would look like this:
write "<form>"
prompt ;adds a text field with the name 'command' and
;the player's user ID as a hidden field.
write "</form>"
As you can see, there is even less to using the prompt command. The prompt command will also output a small amout of Javascript to set the input focus to the text input box.
The player's commands are passed to the interpreter via three parameters: verb, noun and command. If the paramters verb and noun are passed, noun is concatenated on the end of verb and the result is processed. This is useful when writing point-and-click adventures that use a combination of list boxes and submit buttons to form verb-noun commands. If the parameter command is passed, it is processed as a complete command. This is useful for traditional text-based adventures.
It is also possible to use both methods of passing the player's moves. When a request is received, the interpreter will first test the value of verb. If this is empty, the value of command is used as the player's move. If verb does contain a value, the value of noun will be concatenated to it, and the move will be processed, ignoring any value that command may or may not have.
|
It is also possible to define custom parameters that will be automatically copied into a specified container before the player's command is processed. For more information, see the section on Parameters |
The remainder of this section discusses commands that simplify the output of HTML. These commands are ignored by the TACL interpreter without error.
The button command must be followed by a single parameter that indicates what command this button should issue. Behind the scenes, this command creates an input tag of the type submit and sets the value of a parameter named verb to the specified command. Below is an example of its use:
button Look button "Read Map"
The command specified for each button will appear as text on the button. If a command contains any spaces, the command must be enclosed in double quotes as usual.
The command hyperlink is a simple method of creating a hyperlink that issues a command for the player. It can accept either two or three parameters. The first parameter is the command to be issued when the link is clicked. The second is the visible text to be displayed. The third, optional, parameter is the name of a CSS style that should be applied to the link. Below are some sample hyperlinks:
hyperlink east East hyperlink "take all" "Take All" small hyperlink look "Where am I?" big
With the third hyperlink, the text Where am I? will appear on the screen with all the styles specified in a CSS style named big applied. When clicked, it will pass the value look to a parameter named command. This, in effect, issues a look command on the player's behalf.
When manually creating special-purpose hyperlinks, the {+name} macro is very useful. For more information, see the section on Screen Display.
The control command is also used to create a hyperlink. With the control command, however, the second parameter is the name of an image to display instead of some plain text. As the control command displays an image, no third parameter indicating a CSS style is allowed. Below is an example of a control command:
control look "/images/look.png"
The option command is used to include an object as a part of a <select> list box. A list box allows the user to select one of the objects from the list then submit the form the list box is a part of. In HTTP, information is sent to the server in the form for name and value pairs. By default, the option command will set the value for each option to all of the specified object's names. The object is specified by following the option command with an object label or pointer. The visible text for the option is the object's short description. For example:
<form>
write "<select name=~noun~>"
loop
if noun3 is *present
option noun3
endif
endloop
write "</select>"
button Look
button Use
button Take
button Drop
</form>
The about code creates a list box with a parameter name of noun and adds an entry for each object that is in the player's current location. If an object was selected before the form was submitted (by clicking one of the four buttons), the parameter noun would have its value set to all the names of the object the player selected. The paramer verb would have its values set to text on the button that was clicked. These two parameter would then be concatenated (verb noun) and processed by the interpreter as the players move.
It is also possible to specify that an option command should pass the object's index as opposed to its names by following the object pointer or label with the word index. This is only of use if a parameter statement is has been defined to accept the parameter name specified in the select tag. Below is an example of this:
parameter destination SOME_VARIABLE
<form>
write "<select name=~destination~>"
loop
if noun3 is *present
option noun3 index
endif
endloop
write "</select>"
hidden
button Jump
</form>
When this form is submitted, the JACL interpreter will look for the parameter destination, as it has been defined using a parameter statement. This parameter will contain the internal number of the object that was selected and this number will be copied into the location specified by the parameter statement. In this case, it is a variable called SOME_VARIABLE. For more information, see the section on Parameters.
The image command is used to display an image. No surprise there. It accepts three parameters of the format:
image file alignment alternate_text
For example:
image "/images/view.jpg" left "[View from the balcony]"
This command displays the image /images/view.jpg aligned to the left. If the picture is not found, or is displayed in a text-only browser such as Lynx, the text [View from the balcony] will be displayed instead. This is also the text that will be displayed by most graphical browsers when the cursor is held over the image.