The previous chapter introduced the main functions of Shockwave network Lingo. You learned how to navigate between movies and pages, how to retrieve text files from the Internet, and how to preload files to the user's cache. This chapter continues with those same functions, but expands them with a few additional commands.
Shockwave allows you to initiate up to four network operations
at one time. Obviously, this is not used for GoToNetPage
or GoToNetMovie because you
can't look at four pages or four movies at the same time. But
for GetNetText or PreloadNetThing,
you may want to do multiple operations: four text files to load,
four graphic images to preload, and so on. When one of the four
operations is finished, you have a free "spot" to perform
another operation, so you can continually perform network commands;
however, no more than four can be initiated at once.
| Note |
Even though you can initiate four operations at one time, this doesn't mean they will all occur simultaneously. Only one file can be downloaded at a time, and it will be going as fast as possible given the speed of the connection. Initiating four commands may just be simpler for you to do than initiating one at a time. |
Every time you issue a network command-GetNetText or PreloadNetThing-the operation is given a unique identifier. Fortunately, it's not a cryptic twelve-digit code number; instead, it starts at 1 and progresses up. Your first command is 1, your second command is 2, and so on. The number is reset to zero only when a new movie starts.
Remember those parentheses after NetDone and NetTextResult? Earlier examples left them empty. What goes into the parentheses is the identifying number for the operation. If you leave the parentheses empty, Shockwave assumes you are interested in the latest command, so if you are performing only one operation, you won't need a number. But if you are loading four text files, you need to be able to access all four, not just the last one.
By putting the identifier into those parentheses, you can access any of the last four operations. Suppose that you have initiated four GetNetText commands and you want to find out when they are all completed. You could use the following Lingo to check each one:
on exitframe if netdone(1)=true then put nettextresult(1) into field "textone" if netdone(2)=true then put nettextresult(2) into field "texttwo" if netdone(3)=true then put nettextresult(3) into field "textthree" if netdone(4)=true then put nettextresult(4) into field "textfour" go to the frame end
In the preceding example, if the particular operation is finished,
the results are put into four different text fields. Note that
the frame will continually loop, even after all four operations
are finished, so you need a button that can jump to another part
of the movie.
| Caution |
Remember, each operation has a unique identifier. The previous Lingo example will work only once! Any operations after the first four will have higher ID numbers, so your next four commands issued will have identifiers of 5, 6, 7, and 8. You'll soon learn how to determine the latest ID number by using GetLatestNetID. Also note that information for network operations will be discarded when new operations are started. Only the last four operations remain in memory, so when six operations have been completed, only ID numbers 3, 4, 5, and 6 will be able to return information. |
You may decide to keep track of the operation identifiers yourself,
perhaps by using a global variable that you set to increment with
every network command. But a better way to keep track of the current
operation number is to use the GetLatestNetID()
function.
| Note |
You will notice that there are parentheses after the GetLatestNetID() command, but the command doesn't take a parameter because it always returns the last operation number. The parentheses are necessary for Shockwave to understand that it's a network command, but it ignores anything you put into them. |
Suppose that I want to set a local variable, x, equal to the last operation number. Then I want to check to see if the last operation is finished. Perhaps this is put into a handler named "checkdone" that I call periodically from another part of the movie. It could look like this:
on checkdone set x=getlatestnetid() if netdone(x) then put nettextresult(x) into field "results" end checkdone
The preceding example isn't really useful because I could have just used netdone() with nothing in the parentheses to check the latest operation. But maybe you have issued four operations and want to check the last four. Instead of using specific numbers, you can use a variable. Your handler might look like this:
on checkdone
set x=getlatestnetid()
if netdone(x) then put nettextresult(x) into field "fourth"
if netdone(x-1) then put nettextresult(x-1) into field "third"
if netdone(x-2) then put nettextresult(x-2) into field "second"
if netdone(x-3) then put nettextresult(x-3) into field "first"
end checkdone
This is a bit more complex. If the last operation ID is 12, then
the four statements will check using 12 (x), 11 (x-1), 10 (x-2),
and 9 (x-3). If each is done, it will put the results into four
separate text fields. This same handler could then be used no
matter what the latest ID number is.
| Note |
You use only two commands in multiple operations: GetNetText and PreloadNetThing. They work slightly differently. When PreloadNetThing is finished downloading, you can issue another preload command immediately. But GetNetText requires that you use the NetTextResult() command before it releases its "spot" for a new operation. So if you issue four GetNetText commands but don't retrieve the text using NetTextResult, your four operations are still considered active. By issuing another GetNetText command, you will cause the latest ID number to increase; however, the operation will not occur. Therefore, you will have unretrieved information in ID locations 1, 2, 3, and 4, and your latest ID number will be 5. This can throw off your Lingo scripts and can be confusing. Be sure you use NetTextResult to retrieve the text information and allow a new operation. |
Certain browsers that allow separate scrollable windows on the same page use frames. You may have incorporated into your Web page design frames that you want to use with Shockwave's GoToNetPage command.
GoToNetPage "url" will leave your current page and load a new one. But with an extra parameter, you can target one particular frame on the page. So, your Shockwave movie could stay in one frame, while GoToNetPage switches the URL of another frame. Here is the syntax:
gotonetpage "http://www.server.com/page.html", framename
Let's look at an example from the CD-ROM. In Netscape or another frames-capable browser, load framed.html. In the left frame, there is an embedded Shockwave movie with three options. When you choose one, it causes a new HTML page to load into the right frame. The Shockwave movie stays in the left frame without changing. This is very useful for navigation movies so that you always have certain options in one frame, and the Web page content can change in a different frame.
Figure 14.1 shows the framed HTML document. You can see that we have named our two frames "left" and "right."
Figure 14.1 : The HTML setting up our framed page.
The movie is embedded into the HTML document called "left.html" that is put into the frame called "left."
In Director, we set up three buttons with Lingo scripts to call a new HTML page in the right frame. The second button, for example, looks like this:
on mouseup gotonetpage "two.html", "right" end
This button will load the HTML document called "two.html" and it will target the frame named "right." Our movie continues to run because the HTML document in the left frame has not changed. Figure 14.2 shows this example in the browser.
Figure 14.2 : Targeting a different frame using GoTo
NetPage.
| Note |
Targeting frames with GoToNetPage is only recognized by the Shockwave version 5 plug-in. The version 4 plug-in will ignore the target and load the new page in the same frame that the movie is playing in. |
External parameters are strings of information that are passed to the Shockwave movie from the embed tag in the HTML document. External parameters were not an original feature of Shockwave, but are a valuable addition.
How are they used? Let's say you have a movie that uses the GoToNetPage command to switch Web pages. When you created the movie, your Web page to be loaded was named page2.html so you wrote the Lingo command as GoToNetPage "page2.html." However, you later changed your mind and renamed the HTML document for the second page to be newp2.html. Your Shockwave movie now does not work because the Lingo script uses the wrong file name for the new Web page. You have to go back into Director, change the Lingo command, save and Afterburn the movie, then upload the new version to your server.
Using external parameters, you can avoid problems like this that result from changing information. The solution to the above example would include an external parameter that is specified in the embed tag of the HTML document. You would pass a string to the movie that names the second Web page. Lingo reads the external parameter, knows what the name of the page is, and consequently puts the name into a variable used in the GoToNetPage command. By changing the name in the embed tag, the same Lingo script always uses the correct file name in the GoToNetPage command.
External parameters are listed just like the file name, height, width, and other information about the movie. For example, to use an external parameter named "sw1" that contains a string of information, you could use the following embed statement in your HTML document:
<embed src="movie.dcr" height=250 width=125 sw1="External information goes here.">
The information contained in the sw1 parameter could then be used within the Shockwave movie. Perhaps you want to put it into a variable or display it in a text field. The next section describes the Lingo used to retrieve the information.
To access an external parameter in the movie, use the Lingo command externalParamValue(n), where n is the name of the parameter. Continuing the example from above, the following Lingo handler would put the value of parameter sw1 into a text field named "mywords."
on getx
put externalParamValue("sw1") into field "mywords"
end
In the externalParamValue(n) statement, n could also be an integer instead of a string. As an integer, it returns the value associated with the nth parameter. So externalParamValue(3) would return the value of the third parameter.
If you're not sure what parameters the embed tag uses, you can determine the name of a particular parameter by using another Lingo command: externalParamName(n). So the following statement would put the name of the fifth parameter into a variable called "name5":
set name5=externalParamName(5)
If the embed tag had a fifth parameter called "swText," the above Lingo statement would set the variable "name5" equal to the string "swText."
To find out how many total parameters the embed tag contains, use the Lingo externalParamCount(). The parentheses are needed, though nothing is put in them. The following Lingo statement would set a variable called "ptotal" equal to the total number of parameters in the embed tag:
Set ptotal=externalParamCount()
Macromedia has issued a list of possible parameter names that you may use. These are simply suggestions for useful parameters. You can make up any name for a parameter as long as it does not have another purpose (the "src" parameter for example). Here is the list Macromedia provides:
swURL
swText
swForeColor
swBackColor
swFrame
swColor
swName
swPassword
swBanner
swSound
swVolume
swPreloadTime
swAudio
swList
sw1
sw2
sw3
sw4
sw5
sw6
sw7
sw8
sw9
| Note |
The above parameter names are merely names. You can pass any value you want using those parameters. If you want to use the swVolume parameter name to pass the URL of a Web page, that choice is up to you. The names were created by Macromedia to easily correspond to information you might be using. |
You can use as many of the above parameters as you like. A possible embed tag could look like this:
<embed src="movie.dcr" height=300 width=400 swURL="http://www pdgroup.com/" swName="audio.sw1" swText="A really great song." sw1="85" sw4="1">
Chapter 18, "Shockwave for Audio," uses external parameters in an example that plays streaming audio files. External parameters are ideal for situations where the same Shockwave movie could be used on different Web pages but performs differently-such as using the same movie to play different audio files depending on what Web page the user is viewing.
This is quite a powerful feature of Shockwave. Macromedia calls
it storing "preferences," but it's basically just writing
a text file to the user's hard disk. It's useful for storing information
that can be retrieved by a different Shockwave movie or the same
movie after the user has left and returned to the Web page. You
could store information that the user enters the first time he
or she loads the movie, then simply load that information automatically
for subsequent visits to the Web page.
| Note |
The text file is not written to the Web server, it's written to the user's computer. You can never be sure how long it will remain there and it is always placed in the prefs folder within the Shockwave plug-in directory. |
Two Lingo commands are used, one to store the information and one to retrieve it. To store the info use:
setpref filename, value
The file name is recommended by Macromedia to be eight characters or less. It can have the extension .txt and will automatically be given that extension if none is specified. For example, if I wanted to store the phrase "I like snakes" in a file named "reptile" I could use the following Lingo:
setPref "reptile", "I like snakes"
The above statement would create a text file named reptile.txt and place it in a directory named prefs within the Shockwave plug-in folder of their browser.
To retrieve the file name, use the Lingo getpref(prefname). To retrieve the example from above and put it into a text field, you could use:
put getpref("reptile.txt") into field "presults"
On the CD-ROM, load pref.html to see an example of how this works. If it is the first time loading the Shockwave movie (prefs.dir), it will ask you a few questions. The responses will be stored in a text file within the plug-ins folder. When the movie is loaded again later, it will retrieve the file and display a message showing the information. Figures 14.3 and 14.4 show the two possible options of the sample movie.
Figure 14.3 : Questions are asked the first time the movie is played.
The netStatus command is a simple Lingo function that puts a single line of text into the status bar at the bottom of the browser window. The syntax is:
netstatus msg
For example, to display "This site is Shocked!" in the status bar, you could use the following script:
on exitframe netstatus "This site is Shocked!" end
Currently, this function does not work with Internet Explorer, though it may change in future versions.
You can use three other commands to retrieve information about recent operations. These commands probably will not be used as often as NetDone() or NetTextResult() but may be useful in certain cases. On the CD-ROM, load GetNet.dir or GetNet.dcr to see some of these commands used. Of course, it won't run from Director, but you can see how it is set up. You can load the HTML document, Getnet.html, to view the Shockwave movie also.
Getnet.dir is the same as the gethttp.dir file from chapter 16, but it not only loads a text file (or HTML source file), it also displays the ID number, date, error, and done state of each operation (see figure 14.5).
Figure 14.5 : A simple Shockwave movie using various network Lingo commands.
NetError() allows you to
check whether an operation was successful or not. There are several
different responses you can receive from this command as seen
in table 14.1.
| NetError Response | Meaning |
| None | No operation has been started. |
| OK | Operation completed successfully. |
| (nothing) | Operation is not finished yet. |
| Error | Particular error is identified if the operation fails. |
The syntax is just like NetDone(). The following Lingo handler puts the error response into a field called "error."
On checkerror put neterror() into field "error" end checkerror
You could also specify a parameter in the parentheses to identify
one of the four last operation ID numbers.
| Note |
You may be expecting an error message if a file is not found on the server. However, many servers send a message that says something like "file [file name] could not be found on the server…" This is sent as an HTML document, so your GetNetText command will receive this and think it is the text that you requested. NetError() will return "OK" thinking the file was loaded properly. But when you use NetTextResult to view the results, you will see the HTML code for the message "<body>The file could not be found…"and so on. |
The NetMIME() function is used to identify the MIME type of a recent operation. MIME stands for Multipurpose Internet Mail Extension. Every file type has its own extension: Graphics can be .GIF or .JPEG, Shockwave files can be .DCR or .DIR, text might be .TXT, and so on. The server and browser need to know how to view or use each MIME type. So for Shockwave, any file that has the extension .DCR or .DIR has the MIME type of "Application X / Director."
You may wish to check with Macromedia on using this function. At the time this book was published, NetMIME continually reported "Application X / Director" as a MIME type for any operation, whether it was loading a Shockwave file or another file type. This could be a bug, or it could simply be reporting the MIME type of the movie that is playing, which will always be "Application X / Director."
Each file on the server has a date and time attached to it when it was last modified. By using NetLastModDate(), you can view the last modified time of a file used in a recent network operation.
For example, if you were loading a text file using GetNetText that contained information that changed daily, you could have the Shockwave movie display the date and time that the text file was updated so users would know how recent the information is.
The syntax follows the same pattern as NetDone(), NetError, and the others. An identifier can be put in the parentheses or left out for the most recent operation. To put the date into a global variable called "lastdate," you could use the following script:
On exitframe global lastdate set lastdate=netlastmoddate() end
As an example, the returned value put into the variable, "lastdate" could be "Tue, Jun 25, 1996 6:31:44 PM GMT." GMT means the time was converted to Greenwich Mean Time.
You have now learned how to use multiple operations, external parameters, and several other Internet Lingo functions. Be sure to watch for updates and new information about Shockwave development on Macromedia's Web site (http://www.macromedia.com).