Office of Digital Humanities

DigHT 310
Web and Internet I:
Creating Web-Savvy Stacks

Note: This lecture is intended to be used with the stack "InternetLecture.rev", which you can download by launching LiveCode and entering in the message box:

go stack URL "http://livecode.byu.edu/internet/InternetLecture.livecode"

Introduction

One of the most powerful capabilities in LiveCode is the ability to access Internet files using simple tools that are built into the LiveCode environment and the scripting language. They allow you to quickly and easily access web-based resources, displaying them in your LiveCode project; to send data over the internet to web and FTP servers; and even to create two-way communications with other computers on the internet, which could permit development of sophisticated distributed applications. This lesson will examine the basic internet capabilities and look briefly at some of the more sophisticated capabilities.

Basic Web Access

If all you want to do is open an existing web page in your computer's web browser, use the launch url command:

launch url "http://www.example.com/page.html"

where the command is followed by any valid URL, including the proper scheme (http:// in this example). This will cause your system's web browser to launch and display the page indicated. Which web browser is used depends on the systems you are using:

Mac OS 9 and earlier: the default web browser as set in the Internet Control Panel;

Mac OS X

v. 10.2 and earlier: the default web browser as set in the Internet Pane in the System Preferences;

v. 10.3 and above: the default web browser as set in the Preferences for the Safari web browser application.

Windows: the browser set in the Windows Registry. (In XP the Internet Options Control Panel lets you set Internet Explorer as the default; Other browsers like Firefox generally have an option in preferences that let you designate the default web browser.)

 

Getting Web Content into LiveCode Stacks: Text

The URL keyword and the htmlText property

There are several commands that let you easily grab text and other resources from the Web to display in LiveCode, or even to transfer them to your local disk. The key to this is the URL keyword, used in conjunction with the familiar get and put commands. (URL = “Uniform Resource Locator” Refers to the familiar web page addresses that we all type into our Firefox, Internet Explorer or other web browsers.)

The URL keyword

The URL keyword designates a container consisting of an Internet resource or local file in URL form. LiveCode supports the following URL schemes:

http:	a web server page
ftp:	a directory or file on an FTP server
file:	a text file on a local drive
binfile:	a binary file (i.e., one whose primary data is not text, but executable code or graphics, eg.)
resfile:	the resource fork of a Mac OS file

This keyword can be used together with get or put to transfer text into a field:

put URL "http://www.example.com/someText.html" into fld "myField"

-OR-

get URL "http://www.example.com/someText.html"
put it into fld "myField"

the htmlText property

The examples above will put plain text into the field designated. If you put a .html file into a LiveCode field you will see not only the text, but also all of the markup tags that determine how the text will be formatted in a web browser. For example, you might see something like this in your LiveCode field:

<p>This is <i>some text</i>. It is <b>very</b> <br>important text.</p>

In a web browser the text above would look something like this:

This is some text. It is very
important text.

LiveCode provides a way to display some basic html formatting in text fields, by using a field property called the htmlText. LiveCode supports a subset of standard html tags, plus a few additional HTML-like tags that accomodate the full range of text styling available in LiveCode. (See the HTMLText entry in the LiveCode Dictionary for a full list of supported tags. Here is an example of how to write a command that uses the HTMLText property:

set the htmlText of fld "myField" to URL "http://www.example.com/someText.html"

-OR-

get URL "http://www.example.com/someText.html"
set the htmlText of fld "myField" to it

Commands for preloading and caching URLs

LiveCode also provides commands that allow you to preload URLs into the stack for faster displaying. You could, for example, preload some web text into your stack so that it would display quickly when the user needed it, rather than the user needing to wait for it to download, then display.

load command - pre-fetches a file from the internet for faster displaying later. Example:

load URL "http://www.example.com/someText.html"

  Optionally you can include a with message clause that allows you to run a specified handler when the URL finishes downloading:

load URL "http://www.example.com/someText.html" with message "doneLoading"

  You would then have to write a doneLoading message handler, which might look something like this (hopefully you can come up with something more useful, but you get the idea):

on doneLoading
  beep
  answer "The URL is finished downloading."
end doneLoading

unload command - Un-does the load command by flushing the pre-loaded URL from the stack's cache. Unloading URLs frees up memory in your stack.

unload URL "http://www.example.com/someText.html"

URLstatus function - Returns information on the progress of the download. One of the following is returned:

• contacted: the site has been contacted but no data has been received yet
• requested: the URL has been requested
• loading bytesTotal,bytesReceived: the URL data is being received
• cached: the URL is in the cache
• error: an error occurred and the URL was not downloaded
• timeout: the application timed out when downloading the URL
• not found: the URL was not loaded, or has been unloaded

Example:

put URLstatus("http://www.example.com/someText.html") into msg

cachedURLs function - returns a list of cached URLs (i.e., URLs that have been pre-loaded using the load command.)

put cachedURLs() into fld "myField"

-- a handy way of unloading cached URLs is to refer to the result of this function:

unload URL the last line of cachedURLs()

This example unloads the last URL loaded.

Saving Styled Text

The htmlText property gives us another benefit besides being able to show formatted web text in a field: it also provides a way to save formatted text to a file and to read formatted text into a field.

As you may recall, we previously examined ways to save text to the local file system, but all we did was to save plain text—no formatting. By using the put URL form together with the htmlText property you can save formatted text to your hard drive, like this:

put the htmlText of field "myField" into URL "file:/MyHD/myfolder/myfile.txt"

When you want to read in the formatted text, just reverse the process:

set the htmlText of field "myField to URL "file:/MyHD/myfolder/myfile.txt"

Getting Web Content into LiveCode Stacks: Images

Displaying URLs that are stored on the web can be a good way to avoid having to distribute huge files to your users, as well as providing an easy way of updating graphics. If a graphic changes, you can simply replace it on a web server, rather than having to send it out to all your users. LiveCode also provides several methods for displaying web-based graphics in a stack.

the filename property of image objects

Use the filename property of an image object to display a referenced graphic object. This means that the graphic resides on the web, and will simply be displayed in your stack. To do this you must first create an image object in your LiveCode stack. Then you issue a command like this:

set the filename of image "myImage" to "http://www.example.com/someGraphic.jpg"

put URL ... into image

This method actually downloads the graphic into your stack (much like the Import as Control menu item), so it will take up more memory than the previous method. On the other hand, it should also display faster, since it becomes resident in the stack.

put URL "http://www.example.com/someOtherGraphic.gif" into image "myImage"

The imageSource property of text in fields

It is actually possible to display a graphic inside a text field in LiveCode by using the imageSource property. This property applies not to the field itself, but to specific characters inside the field. You can set it like this:

set the imageSource of char 5 of fld "myField" to "http://www.example.com/someGraphic.gif"

This actually causes the image to be displayed in place of the 5th character of the field, so make sure if you use this that character 5 is a character that doesn't need to be displayed (like a return or tab character). (What actually happens is that this command replaces the specified chunk of text with an IMG tag that has a SRC attribute.)

This property also comes into play when displaying the htmlText of a field, as described above. When you set the HTMLtext of a field to a valid web URL, AND that URL contains an IMG tag that references a fully qualified web URL (i.e., a complete URL as in this example: <IMG SRC="http://www.example.com/someOtherGraphic.gif">, not a relative URL), that graphic will appear in the field. See card 1 of the lecture stack for an example. Use URL "http://livecode.byu.edu/index310.html" to see this work.

The htmlText property interprets IMG tags in html text files and correctly displays the referenced images (as long as the references are fully-qualified URLs) along with the styled text.

Transferring Files using FTP

LiveCode also provides tools for transferring files using FTP - File Transfer Protocol. It is an older, but still widely-used protocol for non-secure file transfer over the internet. Remember that since this is non-secure, your password is being sent in the clear over the internet and could be intercepted by evil-doers. This is why FTP is not used for sensitive internet transactions. However it can still be useful for routine file transfers from non-sensitive servers.

Here’s an example of how you would use LiveCode’s FTP keyword to download a file via FTP to your hard drive. In this example, username and password would be replaced with your login name and password.

put URL "ftp://username:password@chum.byu.edu/ClassSpace/CHum381/ftptemp/enableSendmail.txt" \
    into URL "binfile:/myFolder/NewFileName.txt"

To upload from your hard drive to an FTP server, simply reverse the order of the two URLs in the statement:

put URL "binfile:/myFolder/NewFileName.txt" into \
    URL "ftp://username:password@hummac.byu.edu/ClassSpace/CHum381/ftptemp/enableSendmail.txt"

TCP/IP Capabilities

The entire Internet runs over a communications protocol known as Transmission Control Protocol/Internet Protocol, or TCP/IP. LiveCode provides a rather extensive set of commands and functions that allow a knowledgeable user to exploit this protocol for low-level data communication between machines on the internet. Using these tools requires more technical knowledge of how the internet and TCP/IP work than we have time for in this course, so I mention these capabilities only for reference. More information can be found in the LiveCode Dictionary if you wish to explore them further.

open socket command - opens a connection to another computer
close socket command - closes the connection
accept command - accepts a connection request from another computer requesting a socket
read from socket command - accepts data from a socket, puts the data into it
write to socket command - sends data to a socket
resetAll command - closes all open sockets
socketError message - message that is sent when an error occurs; allows you to write a handler to handle the error

+ various functions and properties that allow for fine control of the communication between computers
socketTimeoutInterval function - returns the timeout interval for an inactive connection
openSockets function - returns a list of open sockets
hostNameToAddress function - when given a host name, returns an IP address
hostAddressToName function - when given an IP address, returns a host name
hostAddress function - returns the IP address of a local system a socket is connected to
peerAddress function - returns the IP address of the system at the other end of a socket