Chapter 25 -- Adding Interactivity with Shockwave for Director Chapter 25 Adding Interactivity with Shockwave for Director by Mark "Woody" Woodman CONTENTS Placing a Shockwave File in Your HTML Page Configuring Your Server Writing the HTML to Use Shockwave Files Creating Shockwave Files in Macromedia Director Planning Your Shockwave Movie Learning the New Lingo Compressing Your Shockwave Movies with Afterburner Using Streamed Audio with Shockwave Online Resources for Shockwave Developers Summary Few plug-ins for Netscape Navigator and Navigator-compatible browsers have created as much of a stir as Macromedia's Shockwave for Director. Arguably the industry standard for creating interactive multimedia, Director is the software used to create thousands of popular CD-ROM titles like Passage to Vietnam, MYST, and Total Distortion. The Shockwave plug-in enables you to view Director files (called movies) right inside an HTML page without an external viewer. The release version of the Shockwave for Director plug-in was introduced in the spring of 1996 and was immediately one of the most popular plug-ins available. Note Macromedia has released several other plug-ins with the name Shockwave for viewing files made with various applications like Freehand and Authorware. Unless otherwise stated, any mention of Shockwave in this chapter implies Shockwave for Director 5.0. Netscape Navigator uses plug-ins to extend functionality with third-party software; Microsoft Internet Explorer uses what it calls ActiveX controls. Plug-ins and ActiveX controls are, for the most part, identical in purpose and function, so for the purposes of this chapter, I will use the generic term plug-in to accommodate either browser. With this chapter and a little work, you can embed Director-made applications right in your Web pages, regardless of whether you use Macromedia Director. To make the most of what Shockwave can do for you, however, you should learn Director. If you are already a Director user, you will find step-by-step instructions for making your own Shockwave movies that use the new Lingo commands built into the Shockwave plug-in. Placing a Shockwave File in Your HTML Page Using Shockwave movies in your Web pages requires a simple one-time server configuration. Once that has been done, you use HTML tags within your Web pages to signal the browser to load the Shockwave plug-in. If you haven't already done so, download and install the plug-in from Macromedia's site at http://www.macromedia.com (see Figure 25.1). You also can find the software by following the links from Netscape's plug-in directory at http://home.netscape.com. Figure 25.1 : The Shockwave starting point at macromedia. Configuring Your Server The Shockwave for Director plug-in (or control) loads when it detects an embedded file with one of the Shockwave file extensions. A .dcr file is a Director movie that has been compressed and protected with the Afterburner Xtra and is the most common Shockwave for Director format on the Internet. (An Xtra is a plug-in for Director 5.x that adds functionality to your movie. Afterburner is discussed later in this chapter.) A .dxr movie is one that has not been compressed with Afterburner, but has been protected from within Director itself. A file with the .dir extension is an uncompressed and unprotected Director movie. Unless you plan on sharing your code and cast members with other Director users, do not put .dir files on the Internet. You must configure your server to handle these file types and serve them properly to a Web browser. If you don't have root access to your Web server, have no fear; the process is simple and takes about five minutes. Chances are pretty good your server's administrator will be only too happy to configure things for a bag of corn chips. If he holds out, you may need to resort to throwing in a couple of Twinkies. Use this tactic sparingly, however; you may need it for Part VI when you want to start playing with CGI scripts. The server must be configured to handle the following MIME types: application/x-director dir application/x-director dcr application/x-director dxr application/x-director fgd Tip If you or your sysop is unsure of how to configure your server to handle the MIME types described previously, Macromedia provides excellent online technical support. You should be able to find the information you need at http://www.macromedia.com/shockwave. Macromedia is always thorough in documenting its products, so don't hesitate to look around for plenty of good technical information. Writing the HTML to Use Shockwave Files Placing a Shockwave movie into your Web page requires you to use the <EMBED> or <OBJECT> tags. The <EMBED> tag is the Netscape-compatible command for invoking a plug-in, and the <OBJECT> tag is for use primarily in the Microsoft Internet Explorer 3.x browser. <EMBED> is recognized by any browser that uses the Netscape-compatible plug-in architecture. Among such browsers are Navigator 2.x, Navigator 3.x, Attachmate Emissary, WebSurfer by Netmanage, and Microsoft's Internet Explorer 2.0 beta 3 for the Macintosh. At the time of this writing, <OBJECT> tags can only be used with the Microsoft Internet Explorer 3.x browser for Windows or Macintosh. Tip A Shockwave file can only be loaded once per HTML page. If you need to have the same file appear in several places on the same page, you must duplicate the file and give it a different name. For example, if you want to load the file myshock.dcr three times, you will need to copy and rename it twice so you have the files myshock.dcr, myshock2.dcr, and myshock3.dcr to use on the same page. Be careful not to load too many Shockwave files on the same page, however, because each one uses a 50-70 K chunk of available RAM. Macromedia suggests you limit yourself to three Shockwave movies per HTML page. Using the <EMBED> and <NOEMBED> Tags Netscape plug-ins are loaded when the browser detects the <EMBED> tag in your HTML. If the plug-in hasn't been installed, the browser displays a missing plug-in icon (see Figure 25.2) and alerts the user that the plug-in is required. To accommodate browsers that do not use Netscape plug-ins, such as the America Online Web browser, you can display alternate content between the tags <NOEMBED> and </NOEMBED>. Figure 25.2 : Without the Shockwave plug-in installed, Netscape displays a missing plug-in icon where the Shockwave movie should be. Note Netscape Navigator normally checks <EMBED> to see whether the user has the necessary plug-in to view the file. If not, the browser alerts the user that the plug-in is needed and takes them to an URL to find it. Navigator 1.1 is the exception to this and will only display a missing plug-in icon where the <EMBED> is placed. (See Figure 25.2.) Unfortunately, it won't display the content in <NOEMBED> either. Because there is not a readily available solution to this problem, most Web sites with Shockwave make a note that the user needs Netscape 2.0 or later to view the site. The basic structure for an <EMBED> tag is as follows: <EMBED SRC=filename WIDTH=width HEIGHT=height VSPACE=vspace HSPACE=hspace ALIGN=align BGCOLOR=color PALETTE=ground> You can use these basic parameters with any Shockwave file: The SRC parameter should be a file name with one of the appropriate extensions mentioned in "Configuring Your Server." To specify the location of the file, use the standard format of path/filename. You can use the file's relative path, such as "intro/welcome.dcr", or use an absolute path, such as "http://my.domain.net/intro/welcome.dcr", if you prefer. In some situations, people have had trouble using relative paths; if this happens to you, make the paths absolute instead. Either way, don't forget the quotes around the file name parameter, or evil things will happen to your Web page. (Okay, evil may be a stretch, but chances are good that your Shockwave movie won't load.) The WIDTH and HEIGHT parameters tell the browser how much space (measured in pixels) to reserve for the Shockwave file while it is loading. If you use numbers that are smaller than the dimensions of the file, the browser will crop off the excess accordingly. VSPACE and HSPACE tell the browser how much of an empty margin (again measured in pixels) to place around the file. VSPACE means vertical space and controls the empty margin above and below the file. HSPACE means horizontal space and controls the empty margin to either side of the Shockwave movie. Use ALIGN to place the file either in the left, the center, or the right of the window. If you're sharp and got plenty of sleep last night, you may have already guessed that you can use ALIGN=left, ALIGN=center, or ALIGN=right to do this. BGCOLOR is a parameter that lets you specify the color you want to be displayed behind the Shockwave movie. This parameter works just like it would for the <BODY> tag of your Web page. You can get more information about how to specify a certain color in the Chapter 5section titled "Using Background Colors." The PALETTE option is a tricky one and should be used with care. The default setting is PALETTE=background, but if the Shockwave file has its own custom palette, and you want to force the whole page to be displayed with that palette, use PALETTE=foreground. Caution Be careful when using PALETTE=foreground. On machines that can only display 256 colors, forcing the screen to change palettes may produce a "palette flash" and alter the colors of anything else on the screen. This tends to be uglier than a Mac versus pc flame war in a chat room and nearly as annoying. In addition to these basic parameters, Macromedia has custom parameters that allow you to pass information, such as a user name or a string of text, to the Shockwave movie. These options are covered in "Passing Information from HTML to Shockwave" later in this chapter. A complete <NOEMBED> tag has the following structure: <NOEMBED> Alternate content </NOEMBED> Using <NOEMBED> is straightforward. Any HTML you put between <NOEMBED> and </NOEMBED> is displayed to browsers that do not use Netscape-compatible plug-ins. Many Webmasters provide an image map that mirrors the Shockwave file, and some even provide a link to a non-shocked version of the Web site. The final HTML in your page for these tags might look like the following: <EMBED SRC="shockstuff/intro/welcome.dcr" WIDTH=300 HEIGHT=235 VSPACE=5 HSPACE=5 ALIGN=left BGCOLOR=#FFFFFF PALETTE=background> <NOEMBED> <IMG SRC="images/getnn.gif"><BR> Sorry, you need a browser that uses Netscape plug-ins to view this site. To download a trial version of Netscape, <A HREF="home.netscape.com">Go here.</A> </NOEMBED> Using the <OBJECT> and <NOOBJECT> tags Microsoft's Internet Explorer 3.0 uses a software architecture called ActiveX that allows developers to write plug-ins (called controls) for it. Any file using such a control is inserted into HTML pages with the <OBJECT> tag, which is similar in purpose to Netscape's <EMBED> tag. In fact, <EMBED> works just fine with Internet Explorer. If you need to write your HTML specifically for Explorer with <OBJECT>, however, here are the elements you need: <OBJECT CLASSID=classid CODEBASE=codebase WIDTH=width HEIGHT=height NAME=name ID=idname> <PARAM NAME="SRC" VALUE=filename> <PARAM NAME="PALETTE" VALUE=ground> <PARAM NAME="BGCOLOR" VALUE=color> </OBJECT> <NOOBJECT> Alternate content </NOOBJECT> You may have noticed that <NOOBJECT> seems to mirror the function of <NOEMBED>. Any browser that cannot use the <OBJECT> tag will display whatever you put in the <NOOBJECT> tag instead. If you did in fact notice this, consider yourself part of the coding elite that will one day rule the world. Either way, here's an example of how <OBJECT> and <NOOBJECT> may look in your source code: <OBJECT CLASSID="clsid:166B1BCA-3f9C-11CF-8075-444553540000" CODEBASE="http://active.macromedia.com/director/cabs/sw.cab#version=5,0,1,61" WIDTH=300 HEIGHT=235 NAME="Shockwave" ID="swwelcome"> <PARAM NAME="SRC" VALUE="shockstuff/intro/welcome.dcr"> <PARAM NAME="PALETTE" VALUE="background"> <PARAM NAME="BGCOLOR" VALUE="white"> </OBJECT> <NOOBJECT> <IMG SRC="images/getmsie.gif"><BR> Sorry, you need MSIE 3.0 to view Shockwave files in this site. <A HREF="www.microsoft.com">Get it here.</A> </NOOBJECT> Let's break this code down and take a look at the pieces: The CLASSID parameter is a mind-numbingly long string of code to tell the browser that you are using a certain plug-in. Be sure this string is exactly as you see it in the preceding example, or Explorer will not be able to load the Shockwave for Director control. CODEBASE is where you specify the URL where the latest version of the plug-in is. If the user doesn't already have the Shockwave control, Explorer will prompt her and ask whether she wishes to download it. Again, use the exact URL you see in the preceding example for this to work properly. WIDTH and HEIGHT function just as they do in the <EMBED> tag and specify the dimensions of the stage in the Shockwave file. Note that you must enclose the numbers in quotation marks when using <OBJECT>. If you use numbers that are smaller than the stage, the excess will be cropped off in your page. If you use a FORM in your page, use the NAME parameter to tell Explorer how to identify this object. You must use NAME="Shockwave" for this to work. The ID parameter is where you can give the Shockwave file a unique name or document identifier. This name lets you and the browser refer to the Shockwave file by ID for hypertext linking and communication between objects. This value can be any string you like. Internet Explorer has other parameters as well: <PARAM NAME=paramname VALUE=value>. The only one that you must use with Shockwave is the SRC parameter, which should have the path and file name of your Shockwave file in the value. The preceding example illustrates this parameter. The BGCOLOR parameter is where you can indicate the color to be displayed behind the Shockwave movie. The section "Using Background Colors" in Chapter 5 gives you more information on this parameter. The PALETTE parameter can have VALUE="foreground" or VALUE="background". It tells the browser whether to use the palette of colors specific to the Shockwave file, or the colors native to the browser, respectively. See the caution about the PALETTE parameter with the <EMBED> tag above for additional information. As with the <EMBED> tag for Netscape, there are other parameters you can add to pass information directly into the Shockwave movie with <OBJECT>. Some of these are discussed in "Passing Information from HTML to Shockwave" later in this chapter. For more information on using the <OBJECT> tag with Shockwave, look for technical support documentation at Macromedia's site at http://www.macromedia.com/shockwave. Putting It All Together By now you may be asking yourself, "What if I want to try to load Microsoft's ActiveX control first, and then fall back to load a Netscape plug-in if the user's browser doesn't recognize <OBJECT>?" Good question; give yourself 15 seconds to feel smugly superior. The following code uses the previous examples with slight modifications to cover the bases in one fell swoop: <OBJECT CLASSID="clsid:166B1BCA-3f9C-11CF-8075-444553540000" CODEBASE="http://active.macromedia.com/director/cabs/sw.cab#version=5,0,1,61" WIDTH=300 HEIGHT=235 NAME="Shockwave" ID="swwelcome"> <PARAM NAME="SRC" VALUE="shockstuff/intro/welcome.dcr"> <PARAM NAME="PALETTE" VALUE="background"> <PARAM NAME="BGCOLOR" VALUE="white"> </OBJECT> <NOOBJECT> <EMBED SRC="shockstuff/intro/welcome.dcr" WIDTH=300 HEIGHT=235 VSPACE=5 HSPACE=5 ALIGN=left BGCOLOR=#FFFFFF PALETTE=background> <NOEMBED> <IMG SRC="images/getaclue.gif"><BR> Sorry, you need a browser that uses Netscape plug-ins or Microsoft ActiveX controls. You can <A HREF="home.netscape.com">Get Netscape</A> or <A HREF="www.microsoft.com">Get Internet Explorer</A>. </NOEMBED> </NOOBJECT> The browser will try to use Microsoft's <OBJECT> tag first, and then try Netscape's <EMBED> tag. If the browser can't use plug-ins compatible with either method, you will see the contents of <NOEMBED>. This last part is particularly handy if the user who pulls up your page has something like an older AOL browser. One final note: When Shockwave first came out, it was necessary with some older versions of Netscape to use JavaScript work-arounds to get it to behave properly. You may run into online documentation that suggests you take this route, but this should no longer be necessary with the latest versions of Netscape- and Explorer-compatible browsers. However, the mantra of the Internet is "whatever works." If you run into problems using standard <EMBED> or <OBJECT> specifications, the work-arounds might be exactly what you need. One source of excellent information is the ShockeR Listserv, maintained at http://www.ShockeR.com/ShockeR. The e-mail listserv is for Shockwave developers to exchange ideas and tips with each other about using the latest developments in Shockwave. You'll even find a few of the Macromedia tech-heads who invented Shockwave lurking about and answering technical questions. Chances are that if something cool is being done with Shockwave, the ShockeR subscribers know about it. Creating Shockwave Files in Macromedia Director This section assumes you are comfortable working with Macromedia Director and have at least a basic knowledge of using Lingo. (If you're not used to seeing the splash screen in Figure 25.3, this next section may be a challenge for you.) The methods you use to create Shockwave movies will be nearly identical to those you use to create anything else in Director. However, there are a few disabled features, a few new Lingo commands, and bandwidth issues to be taken into account. With a little patience and a little experimenting, you'll be churning out your own Shockwave movies with abandon. Figure 25.3 : The birthplace of Shockwave-the splash screen for Macromedia Director 5.x. Planning Your Shockwave Movie Your capacity for presenting a professional, polished Shockwave-enhanced site directly correlates to how much planning you do ahead of time. As tempting as it can be to "shoot from the hip" and see what happens, you will do yourself a significant favor by making some key decisions about the uses of Shockwave in your site ahead of time. To illustrate my point with a non-Shocked example, think of the most graphically appealing Web site you've browsed lately. Chances are the graphics and artwork fit a specific theme, integrated closely with the content, and didn't overshadow that content. Graphics should be more than just eye candy; they should be tools to evoke a theme, idea, or consistent frame of reference. Your Shockwave movies can and should perform the same function. The difference is that Shockwave provides you with a vastly superior set of tools. Now you can have something that not only looks good, but also sounds good and responds to user input. Making the best use of this potential involves two basic stages of planning: deciding what role Shockwave will take in your Web site and determining what parameters to set to keep your file sizes small. Deciding How "Shocking" Your Site Will Be Any plans you make about using Shockwave in your Web site should probably center around the question, "Who is my audience?" Out of this question are numerous other questions for you to consider before building a site that uses Shockwave. This section contains a few of these questions to prime the pump. Shockwave is only available for Navigator- or Explorer-compatible browsers; does your audience use such a browser? If so, do they have the Shockwave plug-in or control? If not, will they know how to get it? Will you provide information to help them do this? You can create an entire Web site with one HTML page and a series of Shockwave movies, but if your audience doesn't have access to Shockwave, will you provide them with alternative content? Will that alternative content be on different HTML pages, or will it exist on the same page as the Shockwave movies? What function will Shockwave play in your Web site? Is it appropriate to use it for navigation (toolbars, icons, and so on)? Is it appropriate to deliver the main content of the page? Will you be able to navigate from one Shockwave movie to another from within the movie, from HTML links, or from a separate "toolbar" movie? You can use Shockwave as a form of entertainment that attracts the user's attention but doesn't have the real meat of your information. Is this a better or worse use of Shockwave? If you are paying somebody to write Shockwave movies for you, will you have to pay them to update the content? How often? After you have weighed all of these options, there is one more question to ask: "Is Shockwave the best way to get the job done?" For the average Web site, the answer may be, "Probably not." But if you need the extra punch of interactivity and multimedia in your site, Shockwave for Director is one of the best ways to go. Keeping File Sizes Small Your Shockwave movie can be anything from a CD-ROM-sized application to a simple looped animation. The former may not be the best approach; most users don't like waiting for a 650 M download. Until the curse of limited bandwidth lifts from the Internet, you have the task of keeping your Shockwave movies at a reasonable size for your users. Shockwave does not currently stream its information to your browser. The entire movie file must load before you can see it. (Shockwave Audio is a different story, however. See the section "Using Streamed Shockwave Audio" for more information.) If you have the freedom to design your Shockwave movies for an intranet platform where users will have unlimited bandwidth, you can smugly skip this section altogether. The other 99.9 percent of you may glean a helpful hint or two in avoiding insufferably long download times. If your users are accessing your Web site over the Internet, you can safely expect that they will load files at about 1000-1500 bytes per second. So if your Shockwave movie is 200 K, your users may have to wait over three minutes to view it. Granted, that's a poor-case scenario. (The worst-case scenario happens when the user is getting about 65 bytes per second of data transfer. This typically happens in one of two situations: just after you finished bragging about your bandwidth to a potential client or when you use AOL during any of its 22 "peak hours" in the day.) Many professionals using Shockwave have adopted an unofficial standard of keeping their movie files under 200 K. This seems to be a reasonable amount of time for the user to wait without doing something drastic to their keyboard in frustration. The following sections have some tips on keeping your file sizes friendly to the user. Limit Your Bitmap Cast Members Limiting your bitmap cast members is by far the best way to keep your movie size down. Bitmap cast members are the real bandits in bloating a movie's file size, so try to reuse the same bitmap cast members as much as possible. For instance, instead of making five bitmap buttons with different labels, make one bitmap button and use it five times. Text cast members don't take up nearly the same memory that bitmap members do, so you could label each of your generic button sprites with a different text cast member placed over it. Another way to keep your movie file size smaller is by keeping your overall dimensions smaller. You may be used to producing applications for full-screen delivery; coming up with something visually stimulating to fill a 640¥480 or 800¥600 screen can be quite a challenge. With Shockwave, chances are good you will never need to cover that much screen area. Your movie will be playing in the browser window, remember, and you don't want users to have to scroll back in forth in their browsers to see the whole thing. The stage size itself has little bearing on the file size. What you put inside that stage determines the file size. If you can accomplish your purpose with a smaller stage size, you'll be doing yourself and your users a favor. Another way to keep your bitmap cast members manageable is to reduce their color palette. This palette determines the colors that can be displayed in the image, but it is not limited to the colors actually used in the image. So even if the image uses only several of the available colors, the entire palette is still built-in. Therefore, if you can reduce the palette without compromising the quality of the image, you'll save memory. The buttons named Press in Figure 25.4 serve as a good example of how much of a difference it makes to lower the color resolution of your bitmap cast members. The top button at 16 bits (thousands of colors) is roughly twice as large as the identical button reduced to 8 bits (256 colors). Generally speaking, you can cut a bitmap's file size in half by taking it down one level in palette resolution. Black-and-white, or 1-bit images, are the smallest of all, if you can use them without compromising the artistic considerations of your movie. If you can make use of 1-bit or 2-bit images in any involved animation sequences, the memory savings you make could be enormous. Experiment with ink effects on these images to give you variety without additional cast members. Figure 25.4 : Examples of memory sizes among different cast members. To set the color resolution on a bitmap cast member in Director 5.0, select the item in the cast window and choose Modify | Transform bitmap. Or if you have the cast member open in the Paint window, the resolution appears below the tool palette on the left side. Double-click the resolution to display the Transform bitmap window. Director doesn't let you undo resolution changes, so you may want to experiment with expendable copies of your cast member first. Use QuickDraw Shapes with Patterns The floating Tool Palette window lets you put QuickDraw text and shapes into your movie with very little cost in added bytes. Creating something visually stimulating with only QuickDraw shapes may feel prohibitive, but you can use them for borders, backgrounds, separators, buttons, and the like. Again, try experimenting with ink effects to add variety to these sprites without adding cast members. Note QuickDraw shapes are the plain boxes, ovals, and lines you can create from the Tool Palette. They take up very little memory because Director stores only their boundary coordinates, not a bitmap of the entire shape. Another way to make the most of QuickDraw shapes is by using the tile patterns Director offers. They enable you to have textured backgrounds and shapes in your movie without large bitmaps. Figure 25.5 shows two 50¥50 boxes. The top one is a bitmap, considerably larger in file space than its QuickDraw filled rectangle counterpart below. If you don't like the patterns built into Director, you can import your own. Follow these steps: Figure 25.5 : The Tile Settings window. Create a seamless tile in a graphics program like Adobe Photoshop or Macromedia xRes. The dimensions should be any combination of 16, 32, 64, or 128 pixels (for example, 16¥16, 32¥64, 128¥32) Save it as a PICT and import it into your movie as a cast member. Select Window | Tool Palette. In the Tool Palette, double-click the pattern bar beneath the foreground/background selections. (It's the bar just above the line-width options.) The Tile Settings window appears (see Figure 25.5). Highlight the built-in pattern you want to override. For the Source option, choose the Cast Member radio button. Use the arrow buttons to go through the cast members until you find your imported pattern. At the bottom left of the window, select the dimensions of your pattern from the Width and Height menus. The left half of this window shows your pattern and a selection box of what Director will try to tile. The right half of the window shows what the tiling will look like. If you need to, adjust the selection box on the left side until your pattern tiles properly on the right side. Click the OK button when you are finished. Now you can select your custom pattern to fill any QuickDraw shape in your movie. Display Text in Field Cast Members Director 5 allows you to use anti-aliased text, but be warned that this kind of text takes up considerably more file space than plain text in a field cast member. (Anti-aliasing makes the letters appear smoother by filling in jagged edges with transition colors.) When Director applies anti-aliasing to a block of text, the text is changed to a bitmap. The text in field cast members, however, is stored as plain ASCII information and not as a bitmap. Figure 25.5 shows three boxes of text in the lower left of the stage. The top box was created in the paint window, the second with the text tool (with anti-aliasing on), and the third in a field cast member. If you have a lot of text to put into your Shockwave movie, pick the size savings that the field cast members give you. You won't get the eye-pleasing results of anti-aliasing, but sometimes form has to give way to function. Use getNetText uri for Dynamic Content The Shockwave lingo command getNetText is an often-overlooked command that enables you to use the same movie over and over again while changing any text content. You will learn how to use this command in "Learning the New Lingo," but this space-saving feature bears mentioning here. If you have a Shockwave movie that has text that must be updated on a regular basis, consider designing your movie to act as a player or kiosk for that text. getNetText lets you import a text file from anywhere on the Internet directly into your Shockwave movie while it is running. For example, imagine a certain college wants to have a Shockwave kiosk on its home page that displays the latest athletic scores and scheduled events. The departments responsible for keeping the information current need only update the text, and the Shockwave kiosk movie will display the latest information each time it is loaded. See Figure 25.6 for an example of what this might look like. Figure 25.6 : One use of getNetText is to create a kiosk that draws on regularly updated text files. Use Sound Cast Members Frugally Using sound in your Shockwave movies always adds a nice touch to normally mute Web pages. Sound cast members quickly bloat the size of your movie, however, so you have to weigh the desire for a feature-length soundtrack with a reasonable download time. When possible, use the smallest sound files possible. If you need a music soundtrack, try to use short clips that can be seamlessly looped for an extended period of time. You can also experiment with different sampling rates to reduce the file size, but down-sampling a sound too much makes it unusable. A common sound format is to record at an 8-bit, 22 MHz resolution. With the proper recording equipment, this format is usually satisfactory for narration and sound effects. Avoid using sounds recorded at an 8-bit, 11 MHz resolution if at all possible. You also have the option of using external audio files that can load and play independently of your Shockwave movie. They have the .swa extension and can be compressed with Xtras provided by Macromedia. See the section "Using Streamed Audio with Shockwave" for more information. Learning the New Lingo The real power of Director is found in Lingo, the internal programming language that gives your control over virtually everything in the movie. Although you don't need to be a certified propeller-head (also known as a programmer) to use Director well, the more Lingo you know, the better. There are new considerations you have to take into account when designing Director movies for Shockwave. Some of the features you may be used to are disabled for security or practical reasons. Furthermore, the Shockwave plug-in uses Lingo commands to give you added functionality and access to network-related functions. Disabled Lingo Commands Several commands normally available to you in Director have been disabled in Shockwave to protect users from security breaches on their computers. These commands perform system-related functions or give directory and file information on the host computer. At the time of this writing, Macromedia listed the following commands and features as disabled in Shockwave: closeDA, closeResFile, closeXLib, close window custom menus fileIO fileName of cast, fileName of castLib, fileName of window getNthFileNameInFolder importFileInto keyUp (Netscape 2.x only) mci command moviePath open, openDA, openResFile, open window, openXLib, openCastlib OrthoPlay functions pathName printFrom, pasteFromClipboard quit restart saveMovie searchCurrentFolder, searchPaths serialIO shutdown XObjects, XCMDs, XFCNs From the preceding list, you may have gathered that several powerful features of Director are not available to you. One of these, regrettably, is the "Movie in a Window" method of having multiple movies open at the same time and passing information between them. Macromedia has indicated that it is working on this problem, but for the moment, there is no easy way to have Shockwave movies pass information to each other. (You can have one movie load and play another movie when it is finished, however. Keep reading for details.) Despite the list of verboten commands, Shockwave does allow the movie to access Xtras and linked media. The item must be in the Shockwave Plug-in Support folder, however, so the user must download the Xtra or media and place it in the folder before your movie will be able to use it. It's a hassle, but it's also an understandable security restriction. You don't want somebody's malicious movie traipsing about your hard drive while supposedly looking for a missing Xtra. For an updated list of disabled commands, refer to Macromedia's Shockwave Developer's Guide online at http://www.macromedia.com/shockwave. Shockwave Lingo Commands There are all sorts of new things you can do in Shockwave that you can't do in a normal Director movie. In this section, you'll learn what they are and how they work so that you can build your own Net-aware Shockwave movies. Note The Internet is unreliable. (Propeller-heads call this asynchronous, but don't let that fool you.) When you want something done on a network, you have to ask for it and keep checking to make sure you are going to get it. This process holds true for using the new Lingo commands with Shockwave. Suppose you want to load an external text file into a variable. Your movie has to tell the server to go get the content of the file, monitor whether the request is being filled, and then put the text into a variable when it is finally retrieved. Don't assume that asking is enough; always monitor asynchronous functions. getNetText uri The getNetText command searches for a text file at uri and imports the text directly into your Shockwave movie while it is playing. Uri stands for universal resource indicator and is a standard HTTP file location (URL). The following is an example of how this command might be used: on startMovie getNetText "http://www.blahblah.com/welcome.txt" go to "Intro" end startMovie This is a wonderful command to use if you want your movie to act like a kiosk to display constantly updated information. Instead of updating your Shockwave movie with time-sensitive information on a regular basis, have the movie retrieve the text with getNetText instead. This way, you only have to update the text file and not the Shockwave movie. If you are proficient in CGI or Perl-esque programming, there are all sorts of nifty things you can do with importing text files that are generated on-the-fly. You could show a Shockwave movie that shows the latest usage statistics on a certain Web site, the highest bid on a FORM-fed auction, or the current weather forecast. The following are some related commands: getLatestNetID, netAbort(), netDone(), netTextResult() getLatestNetID() Because more than one asynchronous task can be executed at once, you need to be able to refer to each task by a unique ID. Right after you have started an asynchronous task, such as GetNetText, you can use getLatestNetID() to get the unique network ID number for it. The following example shows how you can use this command: on startMovie -- Declare a global variable to store a network task ID. global textTaskID -- Get the text located in an external file. getNetText "http://www.blahblah.com/welcome.txt" -- Put the task ID of the recent command into the variable. set textTaskID=getLatestNetID() -- Take the user to wherever the movie begins. go to "Intro" end startMovie When you are using asynchronous commands with Shockwave, your movie is instructing the user's browser to perform that command. A limited number of commands can be performed at once, and most browsers default to four sockets or connections. Use getLatestNetID() to keep track of the different tasks in progress and assign them their own variables. If a command can't be carried out on the first try, your movie may need to netAbort() and try again. The following are some related commands: netAbort(), netDone() getPref(prefName) The getPref command is used to retrieve user preference data that you have defined with setPref. The prefName parameter is the name of your preference file, located in the Prefs folder of the Plug-In Support folder. If no such file exists, the result of this command will be void. The following is an example of how this command is used: on startMovie -- Define a global variable to store the user's preferences. global userPref -- Get the preferences from the file previously created. set userPref = getPref("shockfun.prf") -- If there are no existing preferences, take the user to -- A first-time visitor's area. Otherwise, take the user to -- the area where repeat visitors begin. if voidP(userPref) then go to "Firstvisit" else go to "Repeatvisit" end if end startMovie The preference file contains information the program has established about the user for future reference. The capability to retrieve this information is especially helpful in situations where you want to customize what the user sees. You may have first-time visitors fill out their favorite interests, for example, and record them with setPref to a preference file. Later, when they return to your site, you could utilize getPref to automatically show them the things they might be the most interested in. Preference files may also be useful in establishing statistics on how many visitors return to your site on a regular basis. gotoNetMovie uri The gotoNetMovie command loads the movie file specified in uri, halts the current movie, and begins playing the new one in the same position on the HTML page. Macromedia has indicated that, for the time being, the movie called must be in a standard HTTP file location. (Not, for instance, on an FTP server.) You can even have the movie begin at a certain internal marker by using a target-style modifier, such as "http://path/filename.dcr#target". on exitFrame -- Tell the user another movie is about to play. put "Returning to main menu...." into field "StatusWindow" -- Load and play the next movie. gotoNetMovie "main.dcr#menu" -- Go to a frame that waits for the next movie to load. go to "Hold" end exitFrame Something to keep in mind when using this command is that you can only have one active gotoNetMovie in progress at the same time. If you issue gotoNetMovie with another one already in progress, the second command will override the first. Because the called movie will begin playing as soon as it is loaded without warning, you might want to use preLoadNetThing as a helpful way of loading the movie into the user's cache without immediately launching it. When your first movie is finished with whatever it needs to do, it can then use gotoNetMovie without an abrupt transition. The following are some commands related to this command: getLatestNetID, preLoadNetThing gotoNetPage uri, target You can use gotoNetMovie to play a sequence of movies on one HTML page, but if you need the browser to switch to a different HTML page, gotoNetPage is the command to use. The uri parameter can be any HTTP file location, and if your Web site uses frames, you can specify a frame with the optional target parameter. The site in Figure 25.7 uses this function. Figure 25.7 : A site that uses Shockwave navigation inside browser frames. The following is an example of how this command might be used: on mouseUp -- This button, labelled Home, is on a Shockwave menu bar at -- the bottom of the HTML page. -- Play a sound that resembles a mouse button being released. puppetSound "mouseUp.wav" updateStage -- Load a new HTML page in the current browser window. gotoNetPage "http://myserver.myschool.edu/index.html#top" end mouseUp If the specified target frame doesn't exist, the user's browser loads the uri in a new window with target as its name. This feature can be handy if the uri is a link to a page not in your Web site. The user can explore the link in a new window, but yours will still be in the background when he is ready to return. This setup is often a much nicer alternative to hitting the Back button a dozen times. Don't forget to monitor the progress of this command to see whether it is being accomplished. If the page located at uri doesn't exist or is not accessible, you need to provide a way for your Shockwave movie to deal with this situation. Use getLatestNetID() and netDone() to monitor the gotoNetPage operation. You might even want to use preLoadNetThing to load the page ahead of time. Tip You can use gotoNetPage to bring up an e-mail window for the user. The HTML method of doing this is as follows: <A HREF="mailto:[e-mail]">Email me.</A> To accomplish the same thing in Shockwave, use the following line of code in Lingo: gotoNetPage("mailto:[e-mail]") The result is that an e-mail composition window pops up in front of your HTML window, and the To line contains the value of [e-mail]. netAbort() Without a specified task ID, the netAbort() command cancels the last asynchronous command executed. It aborts a specific asynchronous command by referring to it by task ID. (For information on how to identify a command's ID, refer to the information on getLatestNetID.) The following is an example of how this command might be used: on exitFrame -- In a previous frame, the timer was started and a network -- command was given. The task ID was placed in the global -- variable 'netTask'. global netTask -- If the task is completed successfully, leave this frame loop. if netError(netTask)="OK" then go to "Success" exit -- The task isn't completed, so if the 10-second limit is reached, -- abort the task, alert the user, and leave the frame loop. else if the timer>600 then netAbort(netTask) alert "Operation timed out or failed. Please try again." go to "Menu" exit end if end if -- Repeat this frame. The user won't exit from this frame until -- either the task is completed or the time limit is reached. go to the frame end exitFrame You should always program "outs" for yourself in any given situation. When you execute a network (asynchronous) command, be sure to account for the possibility that it doesn't work. Typically, the way you would do this is by putting the program into a loop until one of three things happens: the command is successfully completed, an error is returned, or a time limit you set is exceeded. Caution When you are checking on the status of an asynchronous command in progress, it is tempting to use a repeat while loop to make your movie concentrate on that one thing. Don't! Repeat loops are very CPU-intensive and can slow down the user's machine to a crawl. Use frame loops whevever possible; they allow the movie to check on any other events that need attention. (See the code sample for netAbort() as an example.) A "go to the frame" loop also frees up the user's browser to perform other functions. If you must use a repeat while loop, always provide a way for time to run out or the user to cancel the loop. It's a good idea, in fact, to incorporate similar safety measures into any kind of loop your movie may perform. The following commands are related to this command: getLatestNetID, netError, netDone() netDone() The netDone() command returns the status of the last network command given. If you specify a task ID number within the parentheses, it returns the status of that particular task. The result of this command is either TRUE or FALSE. The command only returns FALSE if a task is in progress; it returns TRUE if there is no task being executed, if a task has finished, or if a task has been aborted. The following is an example of how this command might be used: on exitFrame -- In a previous frame, the movie has issued a getNetText -- command to retrieve a weather report text file. The task ID -- is in the global variable called "getTheWeather". global getTheWeather -- If the task is done, put the result into "theReport". if netDone(getTheWeather)=TRUE then set theReport = getTextResult(getTheWeather) -- If the result of the task is empty, something went -- wrong, and the text file wasn't retrieved. if theReport = "" then alert "I didn't get the weather report. Try again." go to "Menu" exit else -- Display the weather report text in a field and exit. put theReport into field "Weather Report" go to "Menu" exit end if end if end exitFrame Be sure to account for the fact that when netDone() = TRUE, it means that the task is no longer in progress. It does not imply that the command was successful, however, so be sure to check the result of the command and make sure you got what you needed. The following commands are related to this command: getLatestNetID, getNetText, getTextResult, gotoNetMovie, gotoNetPage, netAbort, netError, preLoadNetThing netError() Use netError()to monitor a network task in progress for a specific error. The command returns the status on the most recent network command given unless a specific task ID is provided by getLatestNetID. The result of netError is one of four strings: "OK" if the task was successfully completed, "NONE" if there is no task in progress, an error string if something went wrong, and an empty string ("") if the task is still in progress. The following is an example of how this command might be used: on mouseUp -- This is the handler for a button labeled "Check Status". -- The task ID for a network command initiated in an -- earlier frame is stored in the global variable "myTask". global myTask -- If the result is "OK", the command worked. if netError(myTask)="OK" then go to "Success" exit else -- If the result is "", the command is still in progress. if netError(myTask)="" then put "Still waiting." into field "Report" exit else -- If the result is "NONE", the command was never given. if netError(myTask)="NONE" then put "Nothing to check on." into field "Report" exit else -- The result isn't one of the other three options, so -- the remaining option is that an error occurred. put "ERROR: " & netError(myTask) into field "Report" exit end if end if end if end mouseUp This command can be useful if netDone() isn't giving you the feedback you need when a command is issued. There is one case, however, where using netError() will give you trouble. If you have given a command with a uri that doesn't exist, netError() will return an empty string indefinitely. So be sure to code a way for the movie to abort after a certain amount of time or at the user's discretion. The following commands are related to the netError() command: getLatestNetID, netAbort, netDone() netLastModDate(uri) Use the netLastModDate command to return the date that the specified HTTP item was last modified. The uri parameter must be a valid HTTP file name. The result of this command will be a string. The following is an example of how this command might be used: on enterFrame -- Check the last-modified date on a file that changes often. set myFile = "news/pressrelease/press.txt" set myFileModDate = getNetModDate(myFile) -- Put the result into a display field on the stage. put "Last press release: " & myFileModDate into field "Status" end enterFrame Programs called spiders roam and catalog a Web site for the user on command, and Shockwave spiders can be a great alternative for people who don't have access to CGI scripting. The command netLastModDate in particular is helpful for any Shockwave movie that is keeping track of a large number of files at the same time, be they HTML pages or graphics. You might find it helpful to build a spider that only monitors your own Web site and alerts you to pages that haven't been updated in, say, three months. Or if you have more than one person maintaining your site, you could keep track of which pages have been most recently updated in order to monitor quality control. The following command is related to the netLastModDate command: netMIME() netMIME(uri) The netMIME command returns the MIME type of the HTTP item specified in uri. The result is contained in a string. The following is an example of how this command might be used: on enterFrame -- Establish a list of files to check the MIMe types on. set fileList=[news.txt","home.dcr","logo.jpg"] -- Set a variable to hold the output. set report="" -- Repeat this process with each file in fileList. repeat with eachFile in fileList -- Output the name and MIME type of each file into 'report'. put eachFile & " is: " & netMIME(eachFile) after report end repeat -- Put the contents of 'report' into a field on the stage. put report into field "File Types" end enterFrame Like netLastModDate, this command is provided to allow you to glean information about HTTP files on a network. A file's MIME type describes what kind of application it is associated with and is usually indicated by the file's three-letter extension. This command will become increasingly useful as Xtras for Shockwave are developed to import new file types. netStatus msg If you are using Netscape Navigator, the netStatus command puts a string into the status message at the bottom of the window. Macromedia indicates that this command does not work with Microsoft Internet Explorer 3.0 and, at the time of this writing, has offered no information as to when or if it will. The following is an example of how this command might be used: on startMovie -- Put a message in the status window of the browser. netStatus("Welcome to our Shocked Web site!") end startMovie This isn't one of the more awe-inspiring commands that Shockwave provides, but it has its usefulness. There are probably thousands of different JavaScripts on the Net to accomplish the same thing within HTML, so why not have it in Shockwave? Hopefully, the technical folks at Macromedia will make this command work with Internet Explorer in the near future. The following command is related to the netStatus command: netAbort() netTextResult() Use the netTextResult()command after issuing a getNetText command on a text file. Providing that the getNetText command was successful, the netTextResult() command will return a string of the text contained in the file. Figure 25.8 shows a site that uses this command for an online quiz. The following is another example of how this command might be used: Figure 25.8 : A light-hearted online quiz using getNetText and netTextResult( ) by Alan Levine. on exitFrame -- For this example, getNetText("usernames.txt") has -- already been given, and the movie has used netDone() to -- confirm that it worked. -- Put the text from the file into a field on the stage. put netTextResult() into field "Imported Text" end exitFrame This command must be used in conjunction with the getNetText command. You will need to use either netAbort or netError to monitor the progress of getNetText until it is completed. (See the notes on these commands for more information.) After you have stored the result of netTextResult in a variable or field, you will probably need to format it to fit the aesthetics of your Shockwave movie. Keep in mind that text created in Windows and text created on a Macintosh use different ASCII characters for a line feed (carriage return). Consult your Director manuals for more information on ASCII tables for each platform. For more information, check the descriptions of these related commands: getNetText, netDone, netError preLoadNetThing uri The preLoadNetThing command is one of the hidden gold mines in working with Shockwave. The uri parameter can be any HTTP file, and the result is that the specified file will begin to load into the browser's cache. Use netDone or netError to monitor the progress of this command. The following is an example of how this command might be used: -- This script is in a frame script at the beginning of the -- Shockwave movie. The idle script executes as soon as the movie -- isn't executing another handler. We only want the preLoad -- commands to be called the first time, however, so we'll use a -- global variable called NextMovieIsLoading to prevent repeats. on idle -- 'NextMovieIsLoading' is set to FALSE before the first time -- that this handler executes. The global 'preLoadTask' will -- hold the task ID of the preLoadNetThing command. global NextMovieIsLoading , preloadTask if NextMovieIsLoading = FALSE then -- Preload the Shockwave movie that will come after this one. preLoadNetThing "part2.dcr" -- Store the command's task ID in a global for later use. put getLatestNetID() into preloadTask -- Make sure this script won't run again set NextMovieIsLoading = TRUE end if end idle Keep in mind that this command only preloads one file into the browser's cache. If the uri you specify is a HTML page, it will preload the HTML, but it won't preload any of the graphics or embedded files in that page. To load the individual elements into the cache, you have to refer to them specifically. Many browsers only allow four asynchronous commands to be in progress at once, so you may have to write a script to deal with what is often called the four-socket barrier. These commands are related to the preLoadNetThing command: getLatestNetId, netAbort, netDone, netError setPref prefName, prefValue If you need to record the user's preferences concerning certain aspects of your Shockwave movies, use the setPref command. The prefName parameter is the name of a file that will be created in the Prefs folder of the Plug-In Support folder. If the folder does not already exist, it will be created the first time setPref is used. The prefValue parameter is a text string that contains any information you want to be stored. Macromedia recommends that you keep the file name to eight characters long with an optional three character extension, but the naming convention you use is up to you. Make the file name fairly unique to avoid the possibility that somebody else's Shockwave movie has created a preference file with the same name; avoid names like shockwave, shockdata, shockinfo, and anything else you might think of off the top of your head. The last thing you want is somebody else's Shockwave movie overwriting your preference data. The following is an example of how the setPref command might be used: on enterFrame -- The user has filled out several items of information -- which have been stored in global variables. global userName, userAge, userGender -- Prepare a string of the preferences delimited by spaces. set userPrefs = userName & " " & userAge & " " & userGender -- Create a user preference file called "1732prefs". setPref "1732prefs",userPrefs end enterFrame The term for a preference file created by a Net-accessed application is cookie. This file contains information the program has established about the user for future reference. You may have first-time visitors fill out their favorite interests, for example, and record them with setPref to a cookie. Note Be advised that many users are wary of letting Web sites glean to much information about them. Commercial programs are being developed to prevent cookie files from being maintained on the user's computer, so it is considered polite to inform the user that you plan to create a preference file. Passing Information from HTML to Shockwave Sometimes you will want to specify variable information in your HTML page rather than inside of the Shockwave movie. You could, of course, put the information into a text file and use getNetText to retrieve it. For small strings of text, however, there is an easier way. Your Shockwave movie can detect custom parameters and their values specified in the <EMBED> or <OBJECT> tag of the <HTML> tag. If you are coding for the Netscape broswer with <EMBED>, these parameters can be named anything you like. If you are coding to accommodate both Netscape and Microsoft browsers, limit yourself to the preset parameter names recognized by Internet Explorer in the <OBJECT> tag. They are as follows: swAudio swBackColor swBanner swColor swForeColor swFrame swList swName swPassword swPreLoadTime swSound swText swUrl sw1, sw2, sw3, sw4, sw5, sw6, sw7, sw8, sw9 Macromedia recommends you use values with these parameters that are logical to the person writing the HTML page. Assigning the parameter swForeColor a value of "Lord of the Flies", for example, might be a tad confusing. However, these parameters are just variable holders and do not automatically change the behavior of anything in your Shockwave movie. If you use up sw1 through sw9 and need more custom parameters, you can commandeer any of the other parameter names for whatever values you like. Using Custom Parameters with <EMBED> The format for specifying custom parameters in the <EMBED> tag is simply paramName=paramValue. For example: <EMBED SRC="myshock.dcr" WIDTH=100 HEIGHT=100 swForeColor="212" swBackColor="14" swText="Additional parameters are cool."> In addition to the preset parameter names, you can create any parameter name you like. If you know how to generate HTML pages on the fly with a CGI script, custom parameters becomes a very powerful method of sending information to your Shockwave movies. If the user answered a quiz inside a FORM, you could generate an HTML page with custom Shockwave parameters that contain the answers. It might look something like the following: <EMBED SRC="scoretest.dcr" WIDTH=500 HEIGHT=400 userName="Mark Woodman" userEmail="[e-mail]" answer1="A" answer2="B" answer3="C" answer4="B" favoriteBook="Web Publishing Unleashed"> Using Custom Parameters with <OBJECT> To specify custom parameters for Shockwave in the <OBJECT> tag, use the following format: <PARAM NAME=paramName VALUE=paramValue> The following code is an example of using custom parameters with <OBJECT>: <OBJECT CLASSID="clsid:166B1BCA-3f9C-11CF-8075-444553540000" CODEBASE="http://active.macromedia.com/director/cabs/sw.cab#version=5,0,1,61" WIDTH=100 HEIGHT=100 NAME="Shockwave" ID="myshock"> <PARAM NAME="SRC" VALUE="myshock.dcr"> <PARAM NAME="swForeColor" VALUE="212"> <PARAM NAME="swBackColor" VALUE="14"> <PARAM NAME="swText" VALUE="Additional parameters are cool."> </OBJECT> Unlike <EMBED>, you cannot create your own parameter names. (See the list of available parameter names under "Passing Information from HTML to Shockwave.") You do have 22 parameters at your disposal, however, and you can give them whatever custom parameter values you need to get the job done. Detecting Custom Parameters in Lingo Now that you can provide custom parameter values through HTML for Shockwave, you need to know how to bring those values into your movie. There are three Shockwave Lingo commands that you can use to detect and import custom parameter values: externalParamCount(), externalParamName(), and externalParamValue(). The command externalParamCount() returns an integer that is equal to the number of parameters detected in the <EMBED> or <OBJECT> tag. The SRC, WIDTH, and HEIGHT parameters are included in this number. The command externalParamName(n) returns the name (in a string) of the nth parameter detected. If an nth external parameter is not detected, the result is void. The command externalParamValue(n) returns the value of the parameter specified in n. You can use the parameter name in a string for n, or use an integer to indicate the nth parameter detected. If an nth external parameter does not exist, the result is void. A Sample Use of Custom Parameters This example is a simple Shockwave movie that displays the custom external parameters specified in the HTML page. The cast of the Shockwave movie consists of a Movie Script and a field named Status placed on the stage. The content of the Movie Script is as follows: on startMovie -- Look for external parameters specified in HTML. put externalParamCount() into expc -- Display how many parameters are detected. put "Parameters detected: " & expc & RETURN into field "Status" -- Display each parameter name and its value. repeat with eachParam = 1 to expc set eachPName=externalParamName(eachParam) set eachPValue=externalParamValue(eachParam) put eachPName & " = " & eachPValue & RETURN after field "Status" end repeat end startMovie You might think it is necessary to include an if...then statement in the preceding script to make sure that the number of parameters detected is greater than zero. However, because the SRC parameter is always detected, you are guaranteed that externalParamCount() will return a value of at least 1. For this example, the HTML of the embedded Shockwave movie is as follows: <EMBED SRC="params.dcr" WIDTH=496 HEIGHT=200 sw1="hello" swText="This is my text." swName="Joe Bob" myCustomParameter="123 abc doh ray me"> When the Shockwave movie runs, the output to the stage would look something like the following: Parameters detected: 7 SRC = params.dcr WIDTH = 496 HEIGHT = 200 sw1 = hello swText = This is my text. swName = Joe Bob myCustomParameter = 123 abc doh ray me Using Shockwave Lingo Offline The new Lingo commands you have learned are actually executed by the Shockwave plug-in and are not built into Director. Thus, when you are testing your movies in Director before putting them online, you need to trick Director into allowing the Shockwave Lingo commands to parse. The best way to accomplish this task is to create an external cast with dummy Shockwave handlers that will disable the Script Error: handler not defined alerts. (The commands themselves will not function beyond whatever output you have them fake.) When you are finished testing your movie and are ready to try it in your browser, unlink the external cast. In the simplest use, have each dummy handler do nothing but allow your scripts to compile without handler not defined errors. If you need to have the handlers return sample values, however, you must add some custom scripting. Whoever first thought of this idea deserves our thanks. This practice has become so common among Shockwave developers today that it is hard to imagine making Shockwave movies without it. Listing 25.1 is a sample movie script that you can use to start your own dummy handlers. Some of them do nothing more make a note in the message window; others are examples of how to fake the output of a Shockwave handler for offline testing. The script in Listing 25.1 is only one way to accomplish this, and considerably more sophiticated scripts are often made available by Director users on the Internet (see Figure 25.9). See "Online Resources for Shockwave Developers" for some ideas of where to look. Figure 25.9 : One of several public domain Shockwave movies that can help you do offline testing. Creating an External Cast To create a set of dummy Shockwave handlers for yourself, follow these steps: Select Modify | Movie | Casts. In the window that appears, click the New button. In the window that appears, set the Name field to SWdummy.cst or something that you will remember. Select the External radio button next to the Storage option. Leave the Use in current movie check box unchecked. Click the OK button. Create a Movie Script cast member and place the script found in Listing 25.1 into it. Save the external cast file. Listing 25.1. SWdummy.cst. -- The following handlers should be placed in a Movie Script in an -- external cast member. They will disable the "Handler not defined" -- error in Director while you are making a Shockwave movie. Most of -- these handlers only output a result to the message window for your -- convenience. You can modify them to fit the conditions of your own -- movies as needed. on getNetText uri put "Shockwave: getNetText " & uri end on getLatestNetID put "Shockwave: getLatestNetID" -- Your script will expect a returned value from this handler. -- You should modify this script to return a sample value -- of what your script is looking for. This example assigns a random integer -- to your taskID. return random(10000) end on getPref prefName put "Shockwave: getPref " & prefName -- Your script will expect a returned value from this handler. -- You should add to this script so that it will return a string -- in the same format your preference file will be in. end on gotoNetMovie uri put "Shockwave: gotoNetMovie " & uri alert "The next movie to play would be: " & uri end on gotoNetPage uri, target if the paramCount = 1 then put "Shockwave: gotoNetPage " & uri alert "The next page to load would be: " & uri else if the paramCount = 2 then put "Shockwave: gotoNetPage " & uri & "#" & target alert "The next page to load would be: " & uri & "#" & target end if end if end on netAbort taskID if the paramCount = 0 then put "Shockwave: netAbort()" else put "Shockwave: netAbort " & taskID end if end on netDone taskID if the paramCount = 0 then put "Shockwave: netDone()" else put "Shockwave: netDone " & taskID end if end on netError taskID if the paramCount = 0 then put "Shockwave: netError()" else put "Shockwave: netError " & taskID end if end on netLastModDate uri put "Shockwave: netLastModDate " & uri -- Your script will expect a returned value from this handler. -- You should modify this script to return a sample value -- of what your script is looking for. return the date end on netMIME uri put "Shockwave: netMIME " & uri -- Your script will expect a returned value from this handler. -- You should modify this script to return a sample value -- of what your script is looking for. return "application/x-director" end on netStatus msg put "Shockwave: netStatus -> " & msg end on netTextResult taskID if the paramCount = 0 then put "Shockwave: netTextResult()" return "This is sample text." else put "Shockwave: netTextResult " & taskID set mySample="This is sample text from taskID " & taskID return mySample end if end on preLoadNetThing uri put "Shockwave: preLoadNetThing " & uri end on setPref prefName, prefValue put "Shockwave: setPref " & prefName & " = " & prefValue end on externalParamCount put "Shockwave: externalParamCount()" -- Your script will expect a returned value from this handler. -- You should modify this script to return a sample value -- of what your script is looking for. end on externalParamName param put "Shockwave: externalParamName " & param -- Your script will expect a returned value from this handler. -- You should modify this script to return a sample value -- of what your script is looking for. end on externalParamValue param put "Shockwave: externalParamValue " & param -- Your script will expect a returned value from this handler. -- You should modify this script to return a sample value -- of what your script is looking for. End Linking an External Cast To link an external cast, follow these steps: Select Modify | Movie | Casts. In the window that appears, click the Link button. (See Figure 25.10.) In the dialog box that appears, locate the external cast you saved and click the Open button. Figure 25.10: The Movie Casts window. Now your movie will be able to use all the Shockwave dummy handlers that are in your external cast. You can't use an external cast with an online movie, though, so remember to unlink it when you are done testing offline. Unlinking an External Cast To unlink an external cast, follow these steps: Select Modify | Movie | Casts. In the window that appears, highlight the external cast and click the Remove button. Compressing Your Shockwave Movies with Afterburner Macromedia has made a compression Xtra for Director called Afterburner freely available to Shockwave developers. It will take any loaded Director .dir file and "burn" a compressed version of the file for use online. The resulting "burned" file has the extension of .dcr and can only be accessed within a browser equipped with the Shockwave plug-in or control. A movie compressed with Afterburner cannot be examined for contents or Lingo scripting and is often compressed from 60 to 40 percent of the original file size. You can, of course, leave your raw Director movie (.dir) in its unprotected format for testing purposes, but anyone with Director will be able to open your file. You can also use a protected movie (.dxr), but as with a .DIR file, a significant amount of file space is wasted. The process of burning an Afterburner file is simple: If you don't already have it, download Afterburner from Macromedia and go through the installation process. The Afterburner Xtra is added to the others in your Director Xtras folder. Open the movie you intend to burn into Director. Select Xtras | Afterburner. Name and save the Shockwave (.dcr) file. Watch the little progress bar march along, and you will have instant Shockwave! (See Figure 25.11.) There is typically a list of concerns and workarounds that Director issues with each release of the Afterburner Xtra. Consult the Read Me files that come with the Afterburner Xtra for this information. Figure 25.11: Afterburner at work compressing a .dir file. Using Streamed Audio with Shockwave One of the newer features of Shockwave is the capability to play streaming audio files. This powerful feature allows the user to hear an audio file as it is downloading rather than having to wait for the download to be completed. Audio can be compressed in a variety of ways to best suit the intended audience. In a best-case scenario for users with T1 access, you can deliver CD-quality audio in real time. At the time of this writing, Shockwave audio was quite new to the Web scene and still had some glitches to be worked out by Macromedia, especially with cross-platform creation of streamed audio files. Committing anything to print here would have been premature, so I encourage you to visit Macromedia's site at http://www.macromedia.com for current developers' information on using Shockwave audio. Online Resources for Shockwave Developers There are many Web sites that make good starting places for getting help and hints on doing your own Shockwave projects. Macromedia's Shockwave site is the jumping-off point for just about everything you will do with Shockwave. Go here for the latest downloads, technical releases, and the famous Shocked Site of the Day gallery. (See Figure 25.12.) The URL is as follows: Figure 25.12: Macromedia's listing of some hot new Shockwave sites. http://www.macromedia.com/shockwave/ Perhaps the best Shockwave-related e-mail listserv in circulation, the ShockeR listserv is frequented by some of the best minds in the industry. You will find the brains behind the latest developments in Shockwave technology lurking here, as well as a few Macromedia employees who have the inside scoop on how things work. The URL is as follows: http://www.ShockeR.com/ShockeR/ Director Web is an all-around good resource for Director users, and the resources and information are not limited to Shockwave. It is also the starting point for getting yourself on the Direct-L listserv, arguably the e-mail group for Director users. The URL is as follows: http://www.mcli.dist.maricopa.edu/director/ Summary Developing your own Shockwave movies for the Web is an exciting and rewarding way to use your Macromedia Director skills. As with anything related to the Internet, however, there is no way a single chapter or book can hold everything you need to know about Shockwave. Use this chapter as a reference to the Shockwave basics, and make a habit of checking Macromedia's Web site for updates and new features to Shockwave. For added support, join a user group or listserv that discusses Shockwave and Director issues. Don't hesitate to experiment with everything you've read here, and above all, have fun!