|
Dilemma
Although most wireless Internet phones in the United States will accept
both the Handheld Device Markup Language (HDML) and the Wireless Markup
Language (WML), you have decided to use HDML and Active Server Pages (ASP)
for your application. This may be a wise choice, but you may have noticed
that there is not much information available about using ASP to output
HDML. Since there seems to be much more information about using ASP with
WML (see www.wapuseek.com)
and little to none on ASP and HDML, this article
will focus on the latter. In this article I will discuss:
- Setting the MIME content type for HDML in ASP
- Passing data from HDML to ASP
- Passing data from ASP to HDML
- When to use Method and Postdata
- Using Vars with ASP
- How to output reserved characters to HDML
- Accessing environment variables from ASP
Prerequisites
This article assumes that you have a basic working knowledge of HDML and a
basic working knowledge of ASP. If you need assistance with HDML,
information can be found at phone.com's developer site. If you need
assistance with ASP, there are tons of Web sites with information.
(ASP-Help.com and 15seconds.com are both great starting points.)
MIME Content Type
One of the most common problems when trying to get HDML and ASP to work
together is related to the MIME type. Setting the MIME content type must
be the first line of your ASP file, without exception. Any white spaces,
carriage returns, comments, etc., that are before the content type
definition will be acknowledged and the server may not recognize the file.
Therefore, just leave them out. The correct line of code to start your ASP
file follows:
<%response.ContentType = "text/x-hdml"%>
Passing Data from HDML to ASP
One of the main differences between using ASP to output HDML versus HTML is
the way in which you pass data. In order to pass a variable from HDML to
ASP you need to specify a destination option on the card that will contain
the data. A successful destination option has the following form:
Dest="nextpage.asp?var1=$(value1:esc)"
The variable name is defined in the Key option of the card element. In
this case the variable name is var1. The variable is set at the same time
the user hits the accept key, so you will have access to the value when you
send the request for the next deck.
The destination address must go to another deck and not just a card. If
you substitute the name of a card in place of the next deck's ASP file and
keep the rest of the destination address in the same form, then the server
will be looking for a card named "nextcard?var1=whatever." This card, of
course, does not exist. In this case, it will return to the first card in
the deck. This is most likely not the intended functionality, and if it
is, there are better ways of doing it.
We use the form $(value1:esc) for the actual value passed through so that
if there are any spaces or special characters in the value, they will be
escaped using URL conventions. (This is the same as using URLEncode with
your ASP variables.) If you want to send the value without the escaping
characters (perhaps it is already URL escaped) then use the form
$(value1:noesc).
If an ASP page already has one or more variables and you are setting
another, you can pass them all (or as many as you want) through to the
destination in the following form:
Dest="nextpage.asp?var1=$(value1:esc)&var2=<%=value2%>&var3=hardcodedV
alue"
Notice that you can hardcode a value into a variable here also.
Example 1 - Passing data from HDML to ASP
Here is some sample code for two decks used to get a user's password. We
already have the user's name in a variable called uName. We are passing
the name, password, and page number to nextpage.asp.
First.asp:
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<%uName = request.queryString("uName")%>
<entry key=pass default=tsmith>
<action type=accept task=go
dest="next.asp?uName=<%=uName%>&pass=$(pass:esc)&page=1">
Enter password:
</entry>
</hdml>
Next.asp:
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<%
uName = request.queryString("uName")
pass = request.queryString("pass")
page = request.queryString("page")
%>
<display>
Password:<br>
<wrap><%=uName%>
<wrap><%=pass%>
<wrap><%=page%>
</display>
</hdml>
The scope of a variable is defined by the activity in which it is defined.
You can access the variable anywhere within the activity but not in other
activities.
Passing Data from ASP to HDML
Passing a variable from ASP code to an HDML variable is much easier - just
set them equal. Here is a short example to demonstrate.
Example 2 - Passing data from ASP to HDML
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<%uName = request.queryString("uName")%>
<entry key=pass default=tsmith>
<action type=accept task=go dest="next.asp"
vars="uName=<%=uName%>">
Enter password:
</entry>
</hdml>
When to Use Method and Postdata
When to Use Method and Postdata
So the question is, when do you need to use the Method and Postdata options
for passing variables? You only need to use Method and Postdata when
passing a variable between pages in HDML and when you do not need the value
in the ASP code of your destination page. Method and Postdata can be used
in the following four elements: Anchor, Action, Choice, and Choice Entry.
It is worth noting that the Entry element does not use the Method and
Postdata options, and Method and Postdata cannot be used to transfer data
to ASP variables.
Example 3 - Method and Postdata usage
The following example demonstrates how to use the Method and Postdata
options in a choice card. We take the user's choice in the first card and
return the value to the screen in the second card. The variable "animal"
gets passed through using Method and Postdata.
First.asp:
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<choice key=animal>
<action type=accept task=go dest="next.asp"
method=post postdata="animal">
<ce value="Corgi">Corgi
<ce value="Tiger">Tiger
<ce value="Potbelly">Potbelly
</choice>
</hdml>
Next.asp:
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<display>
animal = $(animal)
</display>
</hdml>
Using Vars with ASP
Vars allows you to set a list of HDML variables as you pass from one card
to another. If you use Vars to set the values and then pass them to the
next deck, you will not be able to access those values with your ASP code.
Even if you try passing the variable names through the destination option,
the variable values are evidently set after the request for the next deck
is sent. However, if you use Vars to pass the variables to another card
first, then you can successfully use the destination option to pass them to
the next deck and use the values in your ASP code. This is just one of
many opportunities when the Nodisplay card is an asset.
Example 4 - Using Vars
This is an example of using Vars to set two variables and pass them to a
card before passing them to the next deck. This enables them to be
requested by the ASP code.
First.asp:
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<display>
<action label="Select" type=accept task=go dest="#next"
vars="dog=Corgi&cat=Tiger">
Click to set variables.
</display>
<nodisplay name=next>
<action label="Select" type=accept task=go
dest="temp2.asp?dog=$(dog:esc)&cat=$(cat:esc)">
</nodisplay>
</hdml>
Next.asp:
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<%
dog = request.queryString("dog")
cat = request.queryString("cat")
%>
<display>
<action label="Back" type=accept task=prev>
<wrap>dog = <%=dog%>
<wrap>cat = <%=cat%>
</display>
</hdml>
How to Output Reserved Characters to HDML
Another thing to be aware of when using ASP with HDML is reserved
characters. Make sure that when outputting the reserved characters
(<, >, ", &, $) to your HDML text you use their respective escape
sequences. See Table 1 below.
|
Character |
Escape Sequence |
|
< |
< |
|
> |
> |
|
" |
" |
|
& |
& |
|
$ |
&dol; |
|
ASCII character |
&nn; (nn is ASCII
code) |
Table 1 — Reserved Characters
(*Note —
Don’t leave the semicolon off the end!)
Example 5 - Reserved Characters
Since you can't use the formatCurrency function in ASP because it outputs a
dollar sign, here is an example of how to output a number in typical U.S.
currency format.
<%response.ContentType = "text/x-hdml"%>
<hdml version=3.0>
<%price = 12%>
<display>
<wrap>price = &dol;<%=formatNumber(price, 2,
-1)%><br>
</display>
</hdml>
This is what the output will look like:
$12.00
Accessing Environment Variables from ASP
When the Wireless Application Protocol (WAP) server you are using makes
HTTP requests to an HDML service, it adds headers that provide information
about the subscriber, the device, and the server. The headers are
converted to environment variables, which you can use in your ASP code. The
following table lists the environment variables set by the UP.Link HTTP
request headers.
|
Environment Variable |
Description |
|
HTTP_ACCEPT |
List of HDML versions
accepted by device |
|
HTTP_ACCEPT_LANGUAGE |
Language in use on
device |
|
HTTP_COOKIE |
HTTP cookies in standard
format |
|
HTTP_REFERER |
URL of the deck originating
the request |
|
HTTP_USER_AGENT |
Browser/version &
Server/version |
|
HTTP_X_UP_DEVCAP_CHARSET |
Character set used by the
device |
|
HTTP_X_UP_DEVCAP_IMMED_ALERT |
Specifies if device supports
immediate alerts |
|
HTTP_X_UP_DEVCAP_MAX_PDU |
Maximum packet size supported
by device (normally 1492 bytes) |
|
HTTP_X_UP_DEVCAP_NUMSOFTKEYS |
Number of softkeys on the
device |
|
HTTP_X_UP_DEVCAP_SCREENPIXELS |
Width, Height of display in
pixels |
|
HTTP_X_UP_DEVCAP_SMARTDIALING |
Specifies if device supports
smart dialing |
|
HTTP_X_UP_FAX_ACCEPTS |
Specifies acceptable fax
types |
|
HTTP_X_UP_FAX_ENCODING |
List of fax encoding types
that the server accepts |
|
HTTP_X_UP_FAX_LIMIT |
Maximum fax size in bytes
that the server accepts |
|
HTTP_X_UP_SUBNO |
Subscriber ID, globally
unique device ID |
|
HTTP_X_UP_UPLINK |
The host on which the server
is installed |
More detailed information about the specific environment variables can be
found at Phone.com's developer site.
In order to get the value of the environment variable into an ASP variable,
use the request.ServerVariables command with the desired environment
variable as the argument (see below).
Example 6 - Environment Variables
The following example shows how to use ASP and environment variables to
redirect the device to the pages that are formatted to the device's
capabilities. If the device accepts HDML, it will be redirected to
index.hdml, an HDML file. Alternatively, if the device accepts WML, it
will be redirected to index.wml, a WML file.
<%
acceptHeader = Request.ServerVariables("HTTP_ACCEPT")
If Instr(acceptHeader, "hdml") <> 0 Then
Response.Redirect "index.hdml"
Else
Response.Redirect "index.wml"
End If
%>
About the Author
Christina Biggs has been a software developer at Scarab Software in
Raleigh, N.C., since May 1999. Scarab Software is partner-oriented
infrastructure provider for e-commerce companies that wish to extend their
existing services to new Internet devices.
Christina graduated from North Carolina State University in August 1999.
She been involved in every step of the software-development process. Her
specialty is the design and development of fun, cutting-edge user
interfaces for desktop applications, wireless Internet phone applications,
and Palm VII applications. She enjoys programming in C++, as well as ASP,
WML, and HDML, using various scripting languages as needed.
Christina Biggs can be reached at cbiggs@scarabsoftware.com.
|
