|
WCTL
Server-side Scripting
WCTL
and Form Processing
Introduction
A Sample Form
Troubleshooting
Resources
Next Section
Introduction
In the
previous section, you learned
how to turn your WCTL scripts into macros (scripts with names)
and how to use them in your Web Crossing conference - and even
call them as commands with a special URL syntax. Please be sure
you understand the concepts covered there before proceeding with
this new section.
In this
section we will expand our use of macros to do something very
useful - process a form.
Forms
are at the heart of Web Crossing. When you post messages, or create
new folders or discussions, you are really just filling out forms
for Web Crossing to process.
Creating
your own forms - or modifying Web Crossing's standard forms -
is something that almost every sysop will want to do at some point.
Since
Web Crossing can also process forms from static web pages outside
Web Crossing, you can use your Web Crossing server as an invaluable
tool in all your web development. You can take the contents of
forms and send the results by email. You can create online surveys,
online shopping systems, auction systems - the possibilities are
endless.
A
Sample Form
Let's
create two macros to start with:
|
Note:
You don't have to create two macros. All you need is one
macro to process the form. A form is just ordinary HTML
so you can put it anywhere that ordinary HTML goes - in
a folder/discussion header, a banner - even outside Web
Crossing in any ordinary home page on the World Wide Web.
We
are going to create a form macro for convenience; If we
put the form and form processing macros together in one
file we can easily move them about, share them with other
sysops and turn them on and off by just removing them from
webx.tpl.
Also,
sometimes you might want to use WCTL in generating the form
itself, using while loops or conditionals, to show different
forms to different users.
|
The form we want to make looks like the form in figure 1.
A user would choose a location, enter his or her name and email
address and press the submit button.
Your
WCTL macro would then receive the form data and send you email
letting you know about the user's request for information.
Figure
1 - We want to create and process this form
Follow
the steps below to create this form as a macro and process it.
(1)
First create a file called requestform.tpl which will hold
both macros (the form itself and the form processor). Place the
following macro in requestform.tpl:
%% macro requestForm %%
<FORM ACTION="http://yourdomain.com/webx?requestFormProcess@@"
METHOD=POST>
<P>Please send me information about the following
location:
<SELECT NAME=requests>
<OPTION VALUE="St. Louis">St. Louis
<OPTION VALUE=Tokyo>Tokyo
<OPTION VALUE="San Francisco">San Francisco
</SELECT></P>
<P>Your name<INPUT TYPE=text NAME=namef
VALUE="" SIZE=56></P>
<P>Your email address<INPUT TYPE=text
NAME=emailaddress VALUE="" SIZE=61></P>
<P>Press the<INPUT TYPE=submit NAME="submit"
VALUE="SUBMIT!">button now! Thanks!
</FORM>
%% endmacro %%
-
|
Note:
Replace http://yourdomain.com/webx
with your actual domain and script name. If you are
running as a CGI rather than in direct web service mode,
remember to include cgi-bin, as in http://yourdomain.com/cgi-bin/webx.
|
As you
can see, everything inside the macro section is just ordinary
HTML. After installing the macro, you can use the statement %%
use requestForm %% anywhere inside Web Crossing where WCTL
is permitted to see the form in figure 1.
-
|
Hint:
You could include WCTL commands inside your form macro
if you want. For example, you could have an %% if
user.userIsRegistered %% conditional surrounding
the form to make sure you only show the form to registered
users.
|
The form
tag itself includes ?requestFormProcess@@ as part of the
Action URL. You will recognize
this from the previous section
as a way to call a WCTL macro via a URL as a command. The name
requestFormProcess will be the name of our form processing
macro.
(2)
Now we need to add the form processing macro. Add the following
macro to your requestform.tpl file:
%% macro requestFormProcess %%
%% set _message
"<support@yourdomain.com>" & crlf &
"To: support@yourdomain.com" & crlf &
"From: " & form.emailaddress & crlf &
"Subject: Request for information " & crlf
&
"MIME-Version: 1.0" & crlf &
"Content-Type: text/plain; charset=" & """"
& "ISO-8859-1" & """" & crlf &
"Content-Transfer-Encoding: 7bit" & crlf
& crlf &
form.namef & "(" & form.emailaddress
& ")" & crlf &
"Has requested information about: " & form.requests
& crlf %%
%% email( _message ) %%
<HTML>
%% form.namef%% - Thank you for your request.
<P>
To return to your previous location, please press
the back button in your browser.
<P>
</HTML>
%% endmacro %%
This
macro is really quite simple. Let's look at it section by section
to see how it works.
%% macro requestFormProcess %%
This
marks the beginning of the form processing macro.
%% set _message
"<support@mydomain.com>"
& crlf &
"To: support@mydomain.com"
& crlf &
"From: " & form.emailaddress
& crlf &
"Subject: Request
for information " & crlf &
"MIME-Version: 1.0"
& crlf &
"Content-Type: text/plain;
charset=" & """" & "ISO-8859-1" & """" & crlf
&
"Content-Transfer-Encoding:
7bit" & crlf & crlf &
form.namef & "("
& form.emailaddress & ")" & crlf &
"Has requested information
about: " & form.requests & crlf %%
This
whole section is just one big set command - it stores an
Internet email, including all the standard Internet headers, in
a local variable called _message.
Be
sure to replace the address support@mydomain.com
with your email address. The address in <angle brackets>
is the actual address to which the email gets sent. The rest of
the lines are just Internet headers and the mail content.
If
you are sending messages in Japanese, just replace ISO-8859-1
with ISO-2022-JP.
|
Note:
We named our local variable beginning with an underscore
(_). No built-in WCTL variable starts with an underscore,
so if you name your local variables starting with an underscore
you are guaranteed not to conflict with any built-in variable
names.
|
All the
form fields are available by just adding the variable type "form."
to the name of the form field. In our example, form.emailaddress
contains the contents of emailaddress, form.namef contains
the contents of namef and form.requests contains the contents
of the selected popup menu value, requests.
|
Note:
We did not use the name "name" for the user's name. This
is a common mistake made by people starting out with forms.
The name "name" is a reserved JavaScript keyword and using
that as a field name will almost inevitably cause weird
problems that will drive you crazy. Best to avoid it.
|
%% email( _message ) %%
The WCTL
email command takes the email message stored in the variable
_message and sends it out over the Internet.
-
|
Note
for people sending Japanese messages: Personal computers
use Shift-JIS code for storing two-byte Japanese characters.
Web Crossing's internal database is stored in Shift-JIS.
However, Internet standards have determined that Japanese
mail sent over the Internet be sent according to the
ISO-2022-JP (JIS) standard. Web Crossing has built-in
commands to convert character strings between JIS and
Shift-JIS.
When
using the email command, simply convert your _message
to JIS as follows:
%%
email( _message.toJIS ) %%
|
You
do not need an other mail server on your system to use this command.
Web Crossing has its own built in SMTP mail server for this purpose.
<HTML>
%% form.namef%% -
Thank you for your request.
<P>
To return to your
previous location, please press the back button in your browser.
<P>
</HTML>
This
section is just ordinary HTML for the most part. After the user
presses the submit button, this is the web page that appears to
the user. As you can see, it is perfectly OK to use form fields
here as well. In this example, we used %% form.namef %%
so we could thank the user personally.
|
Note:
In this example, we have intentionally written a bare-bones
web page to be returned by the macro. In practice, you
would want to include more standard tags, such as a <TITLE>
tag for the page title and a <BODY> tag to set page
attributes.
WCTL
also has a number built-in
variables that can help you set up the <BODY>
tag, using your site's customized attributes. For example:
<BODY %% background %%>
will
automatically use the background settings you have set
in your Web Crossing conference.
|
%% endmacro %%
Finally,
we end the macro.
Well,
that was rather a long explanation about what is really a very
small and basically simple macro. You could add all sorts of extra
features to your form processor, including adding conditionals
to check for valid content. For example, you might want to add
a conditional to check to see if the user actually entered his
or her email address with something like:
%% if !form.emailaddress %%
You must enter your email address<BR>
Press the back button
in your browser to return to the form.
%% endif %%
But this
is a perfectly good, working example that you can use to understand
form processing in Web Crossing.
(3)
Now move requestform.tpl over to your Web Crossing
folder, edit webx.tpl to include the line
<!--#Include File="requestform.tpl"-->
and reset
the file cache, all as explained in the previous
section. Your form and form processing macros are ready to
use.
(4)
Go to your test folder (as explained in the introductory
section) and enter the following WCTL in the header:
%% use requestForm %%
If you
now enter the test folder you will see the form. If you fill out
the form and press the submit button you will get the response
page that appears at the end of the requestFormProcess macro.
If you check your email, you should also receive email from Web
Crossing with the processed form data!
Using
forms you can also read and write external files, create discussions
and Web Crossing messages, create online shopping systems, take
user surveys and add useful commands to your Web Crossing system.
The next
section will show you how to modify templates - the macros
that comprise the basic look-and-feel and operation of your Web
Crossing server.
Troubleshooting
The form
seemed to work, but I did not receive email.
- Make
sure that you have set the address of your DNS (name server)
in the Outgoing SMTP mail section
of Control Panel > Email Services.
I tried
the example above, but when I look at the header all I see is
the WCTL itself, with all the double-percent marks. What am I
doing wrong?
- Make
sure you have turned on WCTL evaluation in the Control
Panels > General Settings:
Resources
Web Crossing
FAQ:
Sysop
docs:
WCTL
Concept Reference Page
Web
Crossing Tech Support Forum
Developer
Center
WebX
Harbor
|
