getURL( ) Global Function

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

getURL( ) Global Function

Flash 4

load a document into a browser, execute server-side scripts, or trigger Macromedia Director eventsFlash 2; method parameter added in

getURL (url) getURL (url, window) getURL (url, window) getURL (url, window, method)

Arguments

url: A string specifying the absolute or relative location of the document to load or external script to run, or a command (depending on the protocol, as shown in Table 18-7).
window: An optional string specifying the name of the browser window or frame into which to load the document. Can be a custom name or one of the four presets: "_blank", "_parent", "_self", or "_top".
method: An optional string specifying the method by which to send the current timeline's variables to an external script either "GET" or "POST". This parameter must be a literal string, not a variable or other expression. On Windows, the Standalone Player always uses the "GET" method, regardless of the method specified. See Appendix F for details on support for GET and POST.

Description

The getURL( ) function is used to:

Load a document (usually a web page) into a web browser frame or window
Execute a server-side script and receive the results in a browser frame or window
Execute JavaScript code in a web browser
Trigger events from Flash assets imported as sprites into Macromedia Director

To load a document into the current window or frame, simply specify the URL of the document as the first parameter, url, without supplying a window or method argument. Naturally, Flash supports absolute URLs (those that contain a protocol such as "http:" plus a server name or hardware device) and relative URLs (those that are relative to the current location):

getURL("http://www.moock.org/");                  // Absolute URL to web page getURL("file:///C:/WINDOWS/Desktop/index.html");  // Absolute URL to local file getURL("/whatever/index.html");                   // Relative URL, http protocol                                                   // is assumed

To load a document into a named window or frame, supply the window or frame name as the window argument. For example:

getURL("http://www.moock.org/", "contentFrame");  // Load into named frame getURL("http://www.moock.org/", "remoteWin");     // Load into named window

To replace the frameset that contains the current movie, use "_parent" as the value of the window argument. For example:

getURL("http://www.moock.org/", "_parent");

To replace all framesets in a web page with a loaded document, use "_top" as the value of the window argument. For example:

getURL("http://www.moock.org/", "_top");

To open a loaded document in a new, anonymous browser window, use "_blank" as the value of the window argument. For example:

getURL("http://www.moock.org/", "_blank");

Note that launching a new window with "_blank" does not give us any control over the appearance of the new window (e.g., its size, toolbar configuration, location, etc.). To launch customized windows with getURL( ), we must invoke a JavaScript function on the movie's host page. Techniques for launching windows with JavaScript are described at:

http://www.moock.org/webdesign/flash.

Prior to Flash 6, the getURL( ) function was used to send variables to a remote server application or script, and receive results in a web browser. As of Flash 6, the LoadVars.send( ) method is better suited for that task. To send the current movie clip's timeline variables to an external script using getURL(), specify the name of the script as the url argument, and use either "GET" or "POST" as the method argument. For example:

getURL("http://www.someserver.com/cgi-bin/search.pl", "resultsFrame", "GET");

When invoked as a movie clip method, getURL( ) sends the timeline variables of that clip to the remote script, as in:

// Sends myClip's variables to search.pl myClip.getURL("http://www.server.com/cgi-bin/search.pl", "resultsFrame", "GET");

The results of the script execution will appear in the window or frame specified by getURL( )'s window argument (which is required when variables are submitted).

To load the results of a script execution into the current frame or window, use "_self" as the window argument value, as in:

getURL("http://www.someserver.com/cgi-bin/search.pl", "_self", "GET");

When the method argument is "GET", the current movie clip's timeline variables are sent as a query string attached to the script URL in an HTTP GET request. Query strings are composed of variable name/value pairs, separated by ampersands (&). For example:

http://www.someserver.com/cgi-bin/search.pl?term=javascript&scope=entiresite

When the method argument is "POST", the current movie clip's timeline variables are sent to the script as a separate block of data after the HTTP POST-request header (exactly like a regular HTML form that uses the POST method). Note that on Windows, "POST" is not available in the Standalone Player.

Because many web servers restrict the length of URLs to between 255 and 1024 characters, use "POST" instead of "GET" to transfer larger amounts of data.

Note that any information returned by a script invoked by getURL( ) is displayed as regular web content in the browser, not in Flash. To accept the results of a script execution into Flash, use loadVariables( ) or, preferably, the LoadVars class. To load a .swf file, see the loadMovie( ) function.

The getURL( ) function can also be used with protocols other than "http:", as shown in Table 18-7.

Table 18-7. Supported protocols for getURL( )
Protocol	Format	Purpose
event	"event: `eventName params`"	Send an event to Director if the Flash asset is a Director sprite.
file	"file:///driveSpec/folder/filename"	Access a local file.
ftp	"ftp://server.domain.com/folder/filename"	Access a remote file via FTP (file transfer protocol).
http	"http://server.domain.com/folder/filename"	Access remote file via HTTP (hypertext transfer protocol).
javascript	"javascript: `command` "	Perform JavaScript command in browser.
lingo	"lingo: `command` "	Perform Lingo command if Flash asset is a Director sprite.
print	"print:", "`targetClip` "	Print the target clip. In Flash 5 or later, use print( ) instead.
vbscript	"vbscript: `command` "	Perform VBScript command in browser.
mailto	"mailto:user@somedomain.com"	Send email via the default mail program on the user's system.
telnet	"telnet://domain.com:8888/"	Telnet to domain.com on port 8888.

As shown in Table 18-7, if a Flash asset is imported into a Macromedia Director file, getURL( ) can be used to trigger Lingo events or execute a Lingo command. (Lingo is Director's scripting language, akin to ActionScript). For example, you can add a frame event of this form:

getURL ("event: eventName params");

which will cause the Lingo event handler named on eventName to be called in Director. Here is a getURL( ) statement that generates an event named "myEvent" and passes it the string "A". Note that the " character is escaped using the sequence \":

getURL ("event: myEvent \"A\"");  // Send an event to Director

Here is the Lingo sprite event handler that should be attached to the Flash sprite asset in Director in order to receive the event. Note that a Director sprite is roughly equivalent to a Flash movie clip instance; the Lingo keyword put is akin to ActionScript's trace( ) command, and && is Lingo's string concatenation operator:

on myEvent msg   put "The message received from Flash was " && msg end

You can also trigger Lingo to be executed from a Flash sprite within Director using the "lingo:" keyword, such as:

getURL ("lingo: beep");  // Tell Director to play a beep sound

Using Flash assets in Macromedia Director requires an appropriate version of the so-called Flash Asset Xtra, a free plugin for Director, provided by Macromedia. Director 8.5 includes the Flash Asset Xtra for Flash 5 .swf files, but it cannot import Flash 6 .swf files. An updated Flash 6 (Flash MX) Asset Xtra ships with Director MX (i.e., Director 9) and is also available from Macromedia's site. The Flash MX Asset Xtra also works with Shockwave 8.5.1, but requires Mac OS 8.6 or later, or Windows 98 or later.

Finally, getURL( ) can also be used to execute JavaScript code. Here we invoke a simple JavaScript alert using getURL( ):

getURL ("javascript: alert('hello world');");

Note that execution of JavaScript code from a URL does not work in Internet Explorer 4.5 for Macintosh.

Example

Here's the code for a standard button that links to a web page:

link_btn.onRelease = function () {   getURL("http://www.macromedia.com/"); }

Bugs

Internet Explorer 4.5 (IE 4.5) and older versions on Macintosh do not support the "POST" method of a getURL( ) call. To service those browsers, use "GET" instead of "POST" (subject to the length limitations cited earlier).

In most browsers, relative URLs passed to getURL( ) are resolved relative to the HTML file that contains the .swf file. In IE 4.5 and older versions on Macintosh, relative links are resolved relative to the location of the .swf file, not the HTML file, which causes problems when the two are in different directories. To avoid the problem, either place the .swf and .html files in the same directory or use absolute URLs when invoking getURL( ), such as:

getURL ("http://www.someserver.com/")

Arguments

Description

Table 18-7. Supported protocols for getURL( )

Example

Bugs

See Also