Name: load

Type: command

Syntax: load [URL] <url> [with message <callbackMessage>]

Summary: <download|Downloads> the <file> specified by a <URL> to a <cache> where it can be used by another <handler>.

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,mobile

Security: network

Example:
load URL "http://www.example.com/index.html"

Example:
load URL myURL with message "downloadComplete"

Example:
load URL tMyUrl with message "myUrlDownloadFinished"

Example:
on myUrlDownloadFinished
   answer "Download Complete" with "Okay"
end myUrlDownloadFinished

Parameters:
url: Any valid http or ftp URL.
callbackMessage: The name of a message to send after the URL is loaded.

Description:
Use the <load> <command> to pre-fetch a <file> from the Internet in order to speed up access when using it in an <expression> with the <URL> <keyword>.

To use a file that has been downloaded by the <load> <command>, refer to it using the <URL> <keyword> as usual. When you request the original <URL>, LiveCode uses the <cache|cached> <file> automatically.

The <callbackMessage> is sent to the <object> whose <script> contains the <load> <command>, after the <URL> is <load|loaded>, so you can handle the <callbackMessage> to perform any tasks you want to delay until the URL has been <cache|cached>. Two <parameter|parameters> are sent with the <message> : the <URL> and the <URLStatus> of the <file>.

The <load> <command> is non-blocking, so it does not stop the current <handler> while the <download> is completed. The <handler> continues while the <load> <command> downloads the <URL> in the background. You can monitor the download by checking the <URLStatus> <function> periodically.

  load URL myURL
  wait until the URLStatus of myURL is cached -- DON'T DO THIS

The file is downloaded into a local cache. It does not remain available after the application quits; the purpose of the cache is to speed up access to the specified URL, not to store it permanently. You can use a URL even if it is not in the cache, so use of the <load> <command> is optional.

>*Note:* Cached <files> consume memory. To release this memory after you are finished with a <URL>, use the <unload (command)> <command> to remove it from the <cache>.

>*Important:*  The <load> <command> is part of the <Internet library on desktop platforms(library)>. To ensure that the <command> works in a <standalone desktop application>, you must include this <Revolution custom library|custom library> when you create your <standalone application|standalone>. In the Inclusions section of the <Standalone Application Settings> window, make sure Internet Library is selected in the list of script libraries. The iOS and Android engines do not support 'libUrl' but allows you to use <load> in the background.

>*Note:* When specifying URLs for iOS and Android, you must use the appropriate form that confirms to the RFC standards. Ensure that you <URLEncode> any username and password fields appropriately for FTP urls.

>*Note:*  When included in a <standalone application>, the <Internet library> is implemented as a hidden <group> and made available when the <group> receives its first <openBackground> message. During the first part of the <application|application's> startup process, before this <message> is sent, the <load> <command> is not yet available. This may affect attempts to use this <command> in <startup>, <preOpenStack>, <openStack>, or <preOpenCard> <handler|handlers> in the <main stack>. Once the <application> has finished starting up, the <library> is available and the <load> <command> can be used in any <handler>.

References: script (property), object (object), startup (message), openBackground (message), preOpenStack (message), openStack (message), preOpenCard (message), Internet library (library), library (library), Revolution custom library (library), url (keyword), file (keyword), application (glossary), standalone application (glossary), load (glossary), cache (glossary), command (glossary), standalone desktop application (glossary), main stack (glossary), expression (glossary), keyword (glossary), Standalone Application Settings (glossary), download (glossary), message (glossary), parameter (glossary), handler (glossary), libURLLastRHHeaders (function), URLEncode (function), files (function), libURLErrorData (function), URLStatus (function), cachedURLs (function), unload (command), libURLftpUpload (command), libURLDownloadToFile (command), get (command), load (command), group (command), function (control_st)

Tags: networking
