The Web

4.1.1 Working with URLs

The TouchDevelop API provides an easy way to interact with software installed on your device to access the web. Most of these interactions begin with a URL. Here is an example of one of the simplest things we can do in a script – opening the web browser at a particular webpage.

        If not web→is connected then

                “Sorry, you don’t have an internet connection!” → post to wall

                time → stop

        else

                // do nothing

        web → browse(“ http://touchdevelop.com ”)

4.1.2 Creating and using web-based links

One use of the Link datatype in TouchDevelop is to save links to people in the form of their email addresses or their phone numbers. This usage is covered in  Chapter 8. Another use is to save links to materials found on the web, such as videos, pictures, and webpages in general. The web resource in the TouchDevelop API provides methods for creating links in the latter category. Some more methods will search for webpages or web resources and return a collection of links to the results. These methods are listed in Table 4-2.

The Link datatype combines additional information with an address such as a URL. It can optionally have an associated name and a location (which is usually relevant for a photograph but is certainly not restricted to photographs). Methods are provided for setting and getting this additional information.

Note that no checking on the validity of the URL is performed when the Link instance is created. The URL is simply held as a string, and can be accessed as a string by using the address method.

Using the wall with web-based links

The wall can be used to hold links to websites in general or to various kinds of resources that may be downloaded. For example, to display an image when an instance of the Link type has been provided, code like the following may be used.

            // link (of type Link) refers to an image on a website

            var pic := web → download picture(link → address)

            wall → set background picture(pic)

Here are some more examples. The following script lines (extracted from the script /hrvg held on the TouchDevelop Samples website) demonstrate some interesting possibilities.

// 1. This creates a basic internet link which is opened in the browser

//  when the link is tapped

web → link url("This is a link to TouchDevelop", " http://touchdevelop.com ") → post to wall

// 2. This will load and display an image from the web

//  when the link is tapped

web → link image(" http://www.touchdevelop.com/Images/title1.png ") → post to wall

// 3. You can also link to a movie or a sound file through the link

//  media method. It will be played when the link is tapped

web → link media(

" http://media.ch9.ms/ch9/06b9/1669dae1-2b5f-4858-abee-9ea7018806b9/

WP7Pex4FunPeliNikolai_ch9.wmv") → post to wall

If the first of the examples above is run as a script, the result displayed on the screen looks similar to Figure 4-1. Tapping the ‘go’ button on the right causes the webpage to be displayed.

Open image in new window

Running the second example displays the image which is downloaded from the web. The result of running it as a script looks similar to Figure 4-2. (The image looks fuzzy because the original is a small low resolution image which gets scaled up in size before being displayed the screen.)

Open image in new window

4.1.3 Checking the internet connection

Your device can usually access the internet via a Wi-Fi connection or through a cellphone connection. However there will be occasions when there is no internet connectivity. A script should test whether there is connectivity before proceeding to try to access web resources. The API method call

        web → is connected

returns true or false to indicate the current situation.

The following API method call should provide information about the kind of connection, if one exists. The result will be one of the strings “unknown” “none” “ethernet” “wifi” or “mobile”.

        web → connection type

Finally, the script can discover the name of the Wi-Fi service or the cellphone service which is handling internet requests. The following API method call returns a string with the name of that service, if there is one. If no name can be found, the result is an empty string.

        web → connection name

4.2.1 Downloading a text file or downloading HTML

The simplest format for a web resource is a text file. If the URL ends with the suffix “.txt” or “.text” then the web resource is almost certainly a plain ASCII (or UTF8) text file. However the URL does not necessarily need either of these suffixes to refer to a text file.

A webpage which contains HTML is also a text file; it is simply text which includes extra commands to specify the structure and the format of the webpage when displayed by a browser. If it is useful, the raw HTML can be read as though it were a text file.

A TouchDevelop script can download a text file or a HTML page and read it into a String variable using script lines similar to those shown in this example:

        action main( )

            var s := web →

        download(" http://www.smlnj.org/doc/FAQ/faq.txt ")

            if s → is invalid then

                    "unable to read webpage" → post to wall

            else

                    // … proceed to use the string s

                    "" → post to wall

                    s → substring(0,100) → post to wall

                    "First 100 characters are:" → post to wall

                    ("Length = " || s → count) → post to wall

When this script is run, the result looks as shown in Figure 4-3. Most likely, though, your script will proceed to do something more complicated with the string than just display the total length and the first 100 characters.

Open image in new window

4.2.2 Downloading a picture

A variety of formats are used for encoding pictures as computer files. The commonly used formats are JPEG, GIF, PNG, BMP, TIFF and WMP. They are all supported by TouchDevelop. If the filename or URL ends with the suffix “.jpg”, “.jpeg”, “.gif”, “.png”, “.bmp” or “.wmp” then one of these formats has been used, and the methods provided in the TouchDevelop API should be able to download and manipulate the picture.

The script statements are similar to before, but use a different method so that the result is obtained as a Picture value (and not as a String value).

    action main( )

            var pic := web → download picture(

        " http://www.touchdevelop.com/Images/title2.png ")

            if pic → is invalid then

                    "Unable to download picture" → post to wall

            else

                    // … proceed to use the picture pic in some way

                pic → post to wall

                ("Image dimensions = " || pic → width || " x " || pic → height) →

         post to wall

Running this particular script yields the result shown in Figure 4-4.

Open image in new window

4.2.3 Downloading sounds and music

TouchDevelop and the Windows phone software support two kinds of audio files – short sound clips and longer audio tracks which would usually contain music (or spoken voice). In TouchDevelop, these correspond to values with type Sound and type Song respectively.

If the filename or URL ends with the suffix “.wav” then the file contents are in the ‘Waveform Audio File’ (WAV) format and it is material that can be downloaded as a Sound value. A Sound value can only be created from a WAV file. If the suffix is “.mp3 ” then the material is in an audio format commonly used for music and the spoken word. This material can be downloaded as a Song value.

Some code to download and play a sound effect is shown below. (The sound effect used in this example comes from the website “Partners in Rhyme” which provides royalty-free music and sound-effects.)

        action getSound( )

            var snd := web → download sound( " http://www.sound-effect.com/pirsounds/WEB_DESIGN_SOUNDS_WAV1/SOUNDFX/TOYLASER.WAV " )

            if snd → is invalid then

                    "unable to download sound" → post to wall

            else

                // … proceed to use the sound value snd

                snd → set volume(0.7)

                snd → play

                ("Duration = " || snd → duration) → post to wall

Example: A script to access and play a song is available as Stream mp3 from internet (/ncwo). The script includes some extra features to make it a bit more useful. These are events to suspend the playback and to stop the playback permanently. When the script is run, the URL can be provided as an argument. If no URL is provided, the last used URL is used again.

4.2.4 Uploading strings and files

Two API methods are available for uploading material to a website. One method uploads a string and the other uploads a picture. Both use the HTPP POST protocol for the uploads. Typically, uploads will be performed when interacting with a website which follows the REST guidelines (as covered below).

Here are sample statements which use the API method call for uploading a string.

        var info := “name=an+other&age=37&car=Ford+Mustang”

        // upload key-value pairs in the info string to website specified by the url

        var response string := web → upload( url, info )

The website which receives the POST request will pass the string onto a program for processing and a string returned by the program comes back as the result of this API call.

Uploading a picture is similar. The sample script web stuff (/hrvg) is an example of uploading a picture of a QR code in the JPEG format to a website.

4.3.1 Downloading information in JSON format

JSON is short for JavaScript Object Notation. It is a text format which borrows notations and data structuring ideas from the JavaScript scripting language. It is a format which has been designed to be easy for processing by computer software (and therefore by TouchDevelop scripts too), but is human-readable too.

An example of some data expressed in JSON format appears in Figure 4-6. It is weather data obtained from the weather2 service.

Referring back to Figure 4-6, we can see that the figure shows an object with just one key-value pair, where the key is “weather” and the associated value is another object. That object contains two key-value pairs; one key is “curren_weather” and the other is “forecast”. The value associated with “curren_weather” is an array that contains just one element, which is an object. The value associated with “forecast” is an array containing two elements, and the two elements are objects with identical structures. (The elements do not need to have the same structure, or even have the same types, but processing the JSON file is easier if they do.)

• If we have found a website which provides results in JSON format, we can access it using the call web→download json. Here is an example invocation.

Open image in new window

        var jobj := web→download json(

    " http://www.myweather2.com/developer/forecast.ashx?uac=X &

    output=json&query=SW1")

It will download JSON data similar to that shown in Figure 4-6. (The ‘X’ shown after ‘uac=’ in the URL must be replaced by a user access code which is given to you only if you register with the weather2 website.)

The value retrieved by this API call has the data type Json Object. The data type provides many methods for accessing information from inside a JSON object. These methods are listed in Appendix C. Using these methods, here is how we could obtain today’s temperature from the JSON object shown in Figure 4-6. The code is shown as a series of very simple steps.

        // assume jobj has been read using the call previously shown

        if jobj → is invalid then

                "unable to download JSON data" → post to wall

        else

                var w := jobj → field("weather")

                var cw := w → field("curren_weather")

                // get first element of array

                var cw0 := cw → at(0)

                // get temperature as a Number

                var temp := cw0 → string("temp") → to number

                // get temperature units as a String

                var units := cw0 → string("temp_unit")

                ("Today’s temperature is " || temp || units) → post to wall

All we had to do was look at one example of the JSON data produced by our weather query. From that example, it was easy to figure out how to extract the information we needed. (Of course, we could have also read the documentation provided by the service provider.)

Two popular services which provide results in the JSON format are Flickr and Twitter. Two scripts in the TouchDevelop Samples collections implement libraries for using these services. A trivial script which searches for tweets containing a particular keyword (or #tag) is shown in Figure 4-7.

The code for the library can be found under the name twitter search (/stlm). It extracts enough information from each tweet to format it as a message with an author name, a picture of the author, the date when the tweet was posted, plus the message itself.

4.3.2 Downloading information in XML format

XML is short for Extensible Markup Language. It is a notation for adding markup to a text document so as to show its structure. It provides an alternative to JSON for delivering results from web services in a format which can easily be processed by software and which is moderately easy for a human to read.

Open image in new window

An incomplete example of the XML produced by the weather2 service is shown in Figure 4-8. The information is the same as shown in Figure 4-6 but, because it is rather more voluminous, only the first 25 lines are displayed. As seen in the example, the start of a component (a logical unit) in the document is flagged by an opening tag such as <weather>. The end of that component is flagged by a matching close tag such as </weather>. The components can be nested, as seen in the figure.

An opening tag can include attributes, such as this one <font name=”Courier” size=”12”>, though this possibility does not occur in the weather data.

Downloading XML data requires a call to web→download to fetch the data as a string, and then a call to web→xml to parse the string as XML, as in the following example.

        var xobj := web→xml( web→download( " http://www.myweather2.com/

developer/forecast.ashx?uac=X&output=xml&query=SW1"))

The result of the code is a value with the datatype Xml Object. This datatype provides methods for traversing the XML object and extracting various components. The methods are listed in Appendix C.

Extracting the current temperature from XML shown in Figure 4-8 can be programmed as follows.

Open image in new window

        // assume xobj has been read using the call previously shown

        if xobj → is invalid then

                "unable to download XML data" → post to wall

        else

                var cw := xobj → child("curren_weather")

                // get temperature

                var temp := cw → child("temp") → to string

                // get temperature units

                var units := cw → child("temp_unit") → to string

                ("Today’s temperature is " || temp || units) → post to wall

As with JSON, it is fairly easy to figure out how to extract the desired information just by looking at an example of the XML data. However, the structure of the XML is almost always rigidly defined by a DTD (Document Type Definition) which specifies the tag names to use and how they are allowed to nest inside other tagged sections. It is preferable to consult the DTD when developing scripts for processing XML.