# Chapter 13

# Internet Lingo for Shockwave

CONTENTS

- Using New Lingo
  - GoToNetMovie
  - GoToNetPage
  - GetNetText
  - NetDone( )
  - NetTextResult()
  - A Sample Movie Loading Text from the Internet
  - PreLoadNetThing
  - Limitations of PreLoadNetThing
- From Here…

Animation and sound are excellent enhancements to a Web page, but Shockwave is not limited to those functions only. Your movies can also interact and respond to the Internet. This chapter offers applications of Shockwave that are exclusive to the Web. The main functions covered are:

- `GoToNetMovie`: Enables you to load new movies in the same Web page location.
- `GoToNetPage`: Can be used for Shockwave navigation through different Web pages.
- `GetNetText`: Loads an external text file from the Internet.
- `PreLoadNetThing`: Enables you to download files to the user's cache before they are needed.
- Other related functions are used in the preceding examples.

## Using New Lingo

There has been much discussion through messages and Web pages about how to use the Internet Lingo commands. It is possible that Macromedia will document the new Lingo in upcoming versions of Director, but for the latest information at this time you should watch the developer's center of Macromedia's Web site:

> http://www.macromedia.com/shockwave/developer.html

Note
The new Lingo commands used by Shockwave are not understood by Director. When you look at these examples or program your own, you won't be able to really test the commands. As you create your movie, leave the network Lingo commands out until you are ready to try it as a Shocked movie.

### GoToNetMovie

The purpose of this function is to call and load a separate Shockwave movie to be played in the same location on the Web page. This could be useful for several reasons.

Suppose that you have a 200K movie that you want people to see. It would take several minutes to download it, during which they would normally just see a big, white square with the Macromedia logo in it. But by using the `GoToNetMovie` command, you can load a small Shockwave movie that comes up quickly and then calls the larger movie. So while the larger movie is downloading, the viewer sees the small movie (perhaps reading text or interacting somehow with it).

Or you may have five separate Shockwave movies that are available for viewers to see, and you want them to be able to switch between them without leaving the Web page. By using the `GoToNetMovie` command, you can switch movies easily without downloading all five as one big movie.

The syntax for the `GoToNetMovie` Lingo command is:

>     gotoNetMovie "moviename.dcr"

You may include the HTTP location as well as the file name, but it all must be within quotes because you are passing a string value to the command. You don't need quotes if you use a variable as a value for the command. Suppose that you have a variable called `whereto`. The following frame script would load a new movie using that variable:

>     on exitframe
>        set whereto="http://www.pdgroup.com/shock/main.dcr"
>        gotoNetMovie whereto
>     end

That example is useless because a local variable is just defined one line above the `GoToNetMovie` command. But in a larger context, the possibility of using a variable can be valuable.

Note
If you issue a second `GoToNetMovie` command before the first one is finishedloading, it will cancel the first command and load the second movie.

#### Using an Introductory Movie to Call a Shockwave File

Here's a simple example that uses `GoToNetMovie`. On the CD-ROM, the file prepare.dcr is a small movie that loads another larger movie, pdgmain.dcr, using the `GoToNetMovie` command. Pdg.html embeds the movie. Run it in your browser to see it work. From a CD-ROM or hard drive, it doesn't make much difference. But over the Internet, there would be a long delay before the second movie loads. So the small introductory movie loads quickly to get rid of the blank, white default box and to make the viewer aware of what's coming.

You can look at the prepare.dir file in Director to see how it is set up, though it won't run properly because Director can't understand the new Lingo. In frame 3, a script calls the new movie.

>     On exitframe
>        gotoNetMovie "pdgmain.dcr"
>     end

In this case, the second movie is located in the same directory as the first movie. You could also specify the whole URL:

>     On exitframe
>        gotoNetMovie "http://www.pdgroup.com/pdgmain.dcr"
>     end

Once you have issued the `GoToNetMovie` command, Shockwave starts to load the new movie. Because it can never be sure how long it will take, the current movie continues to run until the new movie is finished loading. So a looping frame keeps the viewer aware that something "cool" is loading. When the new movie is finished loading, the first one is automatically ended, and the second one begins. Figure 13.1 shows the introductory movie in a Web page.

Figure 13.1 : Using a small pre-movie to show a Shockwave movie is loading.

Note
Usually, a Lingo command must finish executing before it can move on to a new frame or new command. But network Lingo is different. It only starts a process. This is called an asynchronous operation. `GoToNetMovie` will start loading a movie but doesn't need to wait until the movie is finished loading. In later examples, you will learn to use the `netdone()` command to determine if the operation is completed or not. For `GoToNetMovie`, the new movie automatically takes over when it is loaded, so you don't need to check.

Only the first movie is embedded in the HTML document. In our example, it looks like this:

>     <embed src="prepare.dcr" height=400 width=250>

The only thing to remember is that the second movie that is loaded must be the same dimensions as the first movie because it will be played in the same spot on the screen. A new movie that is too large will be cropped, and one too small will leave blank space around the edge.

#### Moving Between Movies with GoToNetMovie

Perhaps you want to offer a choice of movies for the user to load. You could then use `GoToNetMovie` to navigate between movies. To show this, we have a basic example that switches between movies. This example uses three movies on the CD-ROM with this book: blue.dir, red.dir, and green.dir. The gomovie.html page uses the compressed .dcr versions of these files. They are very simple movies, but they show how you can jump between movies. Figure 13.2 shows the movie in Netscape Navigator.

Figure 13.2 : A simple example using `GoToNetMovie`.

Each movie in this example has two buttons that offer options of loading one of the other movies. So the red movie offers options to switch to the green or blue movies. The other two are similar.

The Lingo used was simple. I attached a script to the red button that looks like this:

>     On mouseup
>        gotonetmovie "red.dcr"
>     end

The blue button and green button have similar scripts but use blue.dcr and green.dcr instead. These movies must all be in the same directory to work properly. If the movies were in different directories, you could specify the whole or partial location.

The `embed` statement uses one of the movies-the red one in our example:

>     <embed src="red.dcr" height=300 width=400>

We could have started with any of the three because they can all switch between each other. You might have one particular movie that you load first that contains an introduction and several options to load other movies.

### GoToNetPage

You can also switch the entire Web page using Shockwave Lingo. The `GoToNetPage` command allows you to specify a new HTTP location to move to. The movie you are running will end, and the browser will switch to the new page. The syntax is just like `GoToNetMovie`:

>     gotonetpage "http://www.server.com/page.html"

If the new HTML file is located in the same directory as the Shocked movie, you don't need the whole location. You could use:

>     gotonetpage "page.html"

If you want to specify a specific location on the Web page, you can do so just as you would with a normal anchor:

>     gotonetpage "page.html#anchorname"

You can see how this command is useful as a navigation tool. You could have a main Shocked menu that lets the viewer select which section of your Web site to go to. You could even then have small Shockwave files throughout the site that let the viewer navigate to different areas.

#### A Menu Example Using GoToNetPage

On the CD-ROM, pdgmain.dir is a navigation tool that offers choices in an interactive, animated fashion and will go to the page the user clicks. Pdgindex.html embeds the .dcr version of the file. Sample HTML pages are included to show that the navigation works when pdgindex.html is loaded from the CD-ROM.

By looking at the pdgmain.dir file, you can see that there are seven possible options. The left arrow takes you to "CD-ROM," "Internet," and "Intranet." The right arrow takes you to "Kiosk," "Graphic Design," and "Animation." And the PDG company logo is always available as a link to the home page. So the cast member bit map that says "Graphic Design" contains a Lingo script that looks like this:

>     on mouseup
>        gotonetpage "design.html"
>     end

By clicking "Graphic Design," the user is taken straight to the Graphic Design page of the Web site (figure 13.3).

Figure 13.3 : The PDG navigation movie using `GoToNetPage`.

#### Using GoToNetPage to Detect for Shockwave

Many sites open their first page with a choice of Shockwave or non-Shockwave because they don't know if the user has the right browser and the plug-in. But you can detect this by creating a small Shockwave movie that jumps to a new page using `GoToNetPage`. If the user doesn't have Shockwave, the command is never issued, and the browser stays on that HTML page. If the viewer has Shockwave, he or she will be taken to a new page, which starts the Shockwave section of the site.

So you might create a Shockwave movie that has just one line of text that reads, "Shockwave detected. Entering the Shocked version of this site." Then in a frame script, you would have something like this:

>     on exitframe
>        gotonetpage "shocked.html"
>     end

For your starting HTML document, you could use statements like this:

>     <embed src="shtest.dcr" height=64 width=256>
>     <noembed>
>     Shockwave not detected. Use the links below to navigate.
>     </noembed>

Someone with Shockwave would see the short movie and immediately jump to the Shocked page. Someone with a browser that doesn't recognize `<embed>` and `<noembed>` statements would see the text, "Shockwave not detected. Use the links below to navigate."

Note
Another situation is also possible. Someone with Netscape 2.0 or another browser that recognizes the `<embed>` and `<noembed>` statements but doesn't have the Shockwave plug-in would see a broken icon. This is because the browser understands `<embed>` but doesn't have the capabilities of playing the movie. The browser also understands the `<noembed>` statement, so it skips the line of text. This makes for a difficult situation because you can't have alternate images or text on a browser that understands the code but doesn't have the plug-in. Hopefully, if the viewer has Netscape 2.0 or a compatible browser, he or she has the Shockwave plug-in, also.

### GetNetText

In certain situations, you may want to load a separate file into your Shockwave movie with text information. `GetNetText` allows you to do just that. It retrieves a text file from the Internet.

Suppose that you have some information that is continually changing-statistics, for example. And every day you want the Shockwave movie to display the updated information. Instead of creating a new Shockwave movie every day with updated information, you can just upload a new text file to your server every day and have the same movie load the text file. You could even have a CGI script automatically update the text file periodically, though how to write CGI scripts isn't covered in this book. For more information on CGI, try Special Edition Using CGI, by Que Publishing.

The syntax for the Lingo command is:

>     getnettext "http://www.server.com/file.txt"

Again, you need only specify the file name if it's in the same path of files as the Shockwave movie.

Caution
`GetNetText` works only over the Internet. You will be very frustrated if you can't get it to work off of your local hard disk. The command is intended to load information from an HTTP URL and will not load local files. The Shockwave movie can be played from a local disk, but the text files that are loaded using `GetNetText` must be on the Internet; and, in that case, you would need to specify the whole HTTP location because your movie is not in the same directory as the text file.

### NetDone( )

`GoToNetMovie` and `GoToNetPage` end the current movie when they're finished loading, but `GetNetText` stays within the same movie. You need a way of determining when the text file is finished loading; You can't just delay the movie for ten seconds and hope that it was enough time to get the information from the Internet. Downloading is too irregular for that. To test if the operation is finished, you can use another Lingo command new to Shockwave: `NetDone()`.

You can use `NetDone()` in an `if` statement, and it will be either true (1) or false (0). After you have started the `GetNetText` operation, if `NetDone()` returns true, the operation is finished and you can proceed to use the information. If `NetDone()` returns false, then the file is still loading and you will need to wait longer before using the information.

Here are two simple Lingo statements that use `GetNetText` and `NetDone()`. For now, put nothing in between the parentheses; they will be explained later.

>     On exitframe
>        getnettext "http://www.pdgroup.com/file1.txt"
>     end
>     On exitframe
>        if netdone()=false then go to the frame
>     end

You can't put these two statements into the same frame because the `NetDone()` command here is set to loop to the frame. You would be issuing a new `GetNetText` command repeatedly.

Caution
You might decide to use a test like this: `repeat while netdone()=false nothing end repeat` But this is a bad idea. I have found that `NetDone()` never seems to return true in a case like that, so you get stuck in an endless loop. The `updatestage` command doesn't seem to help this, either. Apparently, you need to allow for at least a single frame loop. Lingo loops can be risky anyway because you lose interaction functions while the script repeatedly executes.

### NetTextResult()

The `NetTextResult()` statement is used to access the information you just downloaded using `GetNetText`. You can use `NetTextResult()` to put the information into a variable or text field or do whatever you like. I am wary about how long the movie will remember the information, so I always put it into a global variable so it won't be lost (a new `GetNetText` statement can replace the `NetTextResult` information). You could use a script like this:

>     on exitframe
>        global gresults
>        put nettextresult() into gresults
>     end

### A Sample Movie Loading Text from the Internet

From the CD-ROM, load the page called gettext.html. It will load the Shockwave file gethttp.dcr. For this example to work properly, you'll need to have a connection to the Internet. You can run the movie from the CD-ROM, and it will load text using the `GetNetText` command. It then tests if the operation is complete using `NetDone()` and displays the results using `NetTextResult().`

The movie allows you to type in an HTTP address and file name, and view the results. If you don't have any text files on your server to look at, you can call any HTML document anywhere on the Web. For example, you could look at the PDG index.HTML document by typing:

> `http://www.pdgroup.com/index.html`

and pressing the Show HTTP button. Figure 13.4 shows the movie in a Web page.

Figure 13.4 : Using `GetNetText` to view a text file.

By looking at the Director file, gethttp.dir, you can see how this was put together (see figure 13.5). A text field that can be edited was created to allow you to type in the location and file name. Then, when you press the button, a script executes:

>     on mouseup
>        set x=field "where"
>        getnettext x
>        go "test"
>     end

Figure 13.5 : The `gethttp` movie in Director.

This script sets a local variable x equal to the text field that contains the file and location. Then it uses the `GetNetText` command to retrieve the item. Finally, it sends the playback head to a frame marked "test."

In the "test" frame, a script looks like this:

>     on exitframe
>        if netdone()=false then go to the frame
>     end

If the text file is not finished downloading, the frame loops. When the test
returns true, the playback head can go to the next frame, which has this script:

>     on exitframe
>        put nettextresult() into field "results"
>        go "start"
>     end

This script puts the text information into a scrollable text field that I named "results." Then it goes back to the frame marked "start" to allow a new text retrieval.

### PreLoadNetThing

Preloading is the process of loading information that is not currently needed, but will soon be used. The purpose is to have the information available before it is required so that there is no waiting time to access the information.

The `PreLoadNetThing` command can be very useful, although it is currently limited. What it does is load any file item from the Internet to the user's disk cache. So, while they are interacting with the Shockwave movie, various items can be downloaded that will be used later. When it's time to use the items, they don't need to be downloaded from the Internet because they are already available on the user's local disk cache.

For example, you have a simple Shockwave movie that loads on one Web page. While the user reads the Web page or looks at the movie (game, text, whatever), the movie is preloading other items to the cache-a new HTML document, a GIF or JPEG image, another Shockwave movie, and so on. Then, when the user is ready to move to the next Web page, the items have already been loaded, so there's very little delay in seeing them.

The syntax is:

>     preloadnetthing "http://www.server.com/item.extension"

Suppose that I want to preload a JPEG image called logo.jpg while my Shockwave movie plays. In this example, the JPEG file is in the same directory on the server as the Shockwave file. In a frame script, you would put:

>     on exitframe
>        preloadnetthing "logo.jpg"
>     end

Because Shockwave's network Lingo only starts the operation and lets it run in the background, the movie continues to play. Later, if you want to check whether the operation is finished, you can use a `NetDone()` test as you did with the `GetNetText` example. If the operation is finished, you can preload something else.

### Limitations of PreLoadNetThing

There are a few limitations to using the `PreLoadNetThing` command:

> There is a 64K limit. Anything larger appears to download, but will not be written to the cache. Hopefully, this will be different in future versions of Shockwave.

> You have no way of knowing the size of the user's cache or when items will be removed from it. Most people have it set large enough to hold just about anything you want to preload-especially if you can only do it in 64K chunks. But if you plan on having the user navigate a variety of pages, you may not know if the preloaded items stay in the cache.

> The system may slow down while the browser is downloading the items. It can affect your Shockwave movie's performance if you are continually loading things in the background.

It's difficult to offer an example of `PreLoadNetThing` because items currently on the Internet may not be there when you are reading this book. Hopefully, this chapter describes the process well enough so you can adapt it to your own purposes.

## From Here…

This chapter has covered the main Shockwave network Lingo operations. You can find more advanced uses in upcoming chapters or in the gallery at the end of the book.

1. Chapter 17, "Alternatives to Shockwave": More exciting options!
2. Chapter 18, "Shockwave for Audio": "Hear" all about the use of streaming and other audio techniques.
3. Chapter 19, "Shockwave for Authorware": Learn about the differences between Director and this high-end authoring package.