MENU
    download
    • 11 Nov 2020
    • 2 Minutes to read
    • Contributors

    download


    Article summary

    Description

    Initiates an asynchronous download of a specified Internet resource such as a file, raw data, or image.

    When downloading completes, the results are stored inside the runtime's cache object using a provided key.

    The Ux.ResourceReady event is also triggered so you can take action when your resource becomes available.

    Downloading resources from an app's locker is also supported using the resource's locker token. This is the recommended approach for downloading resources since they are fully managed by the app.


    Input Parameters

    NameTypeRequiredDescription
    uriTextYesLocation of Internet resource
    keyTextYesUnique cache key where item will be stored
    [type]TextNoType of data being downloaded

    Returns

    Type: Any

    Returns the downloaded Internet resource and attempts to convert it to the type specified. Text is the default type.

    The following types are supported:

    NameDescription
    textPlain text (default)
    jsonJson object
    xmlXml document
    imagePlatform-specific image object
    bitsRaw binary data

    Examples

    // inside the Ux.Initialize script...
    // initiate download of text resource from app's locker using its token
    network.download("TOKEN", "config");
    JavaScript
    // inside the Ux.Initialize script...
    // initiate download of text and json resources from the Internet
    network.download("https://www.mydomain.com/file.txt", "config");
    network.download("https://www.mydomain.com/object.json", "person", "json");
    JavaScript
    // inside the Ux.ResourceReady script...
    // note: this script will run once for each downloaded resource
    
    // get the cache key for this downloaded resource
    var key = script.args[0];
    
    // fetch the downloaded resource from cache
    var item = cache.get(key);
    JavaScript

    Remarks

    Use this function when you need to download external resources from the Internet such as files, raw data, or images.

    Downloading resources from your app's locker instead of the open Internet is strongly recommended since they are fully managed by the app.

    One common scenario is to download a file available on a server using the Ux.Initialize event. Once downloaded, you can take action using the Ux.ResourceReady event. The cache key you provided is accessible via the runtime's script object.

    Two-Step Process

    Downloading resources from the Internet can be slow based on connection speeds and the size of the resources being downloaded.

    Because of this speed issue, downloading internet resources requires a two-step process. First, you must initiate the download (from one script). Second, you take action (if needed) after the download completes from another script (i.e. Ux.ResourceReady).

    By separating these steps, the user's experience remains fluid. Otherwise, the user interface would freeze until the download completes, which is a poor user experience.