Opening Remote Documents

Navigation:  Appendix > Advanced Topics >

Opening Remote Documents

Previous pageReturn to chapter overviewNext page
Show/Hide Hidden Text

You may have noticed a special Remote Document window when you choose Help | Sample Sketches & Tools or File | Sketchpad LessonLink. This Remote Document window shows you the documents available in a particular location on the web and allows you to open remote sketches directly in Sketchpad, without having to use your web browser to download them.

 

It’s possible for you to use this mechanism for your own collections of documents by creating a specially formatted text file in a folder on the web. This text file (with a suffix of .rdb) names and describes the sketch documents that will be displayed in the Remote Document window. Once you’ve created the rdb text file, and saved both it and the sketch documents on the web, you can create, within a sketch, a Link button that points to the rdb file and opens the Remote Document window.

 

RDB File Grammar

An RDB file contains one [CollectionInfo] section describing the entire collection to be displayed in the Remote Document window, followed by one or more [Document] sections describing the documents that are included in the collection. Each section contains a set of key-value pairs; each legal key, and its purpose, is described below. (This grammar is based on the standard ini format, as described here: http://en.wikipedia.org/wiki/INI_file.)

[CollectionInfo]

There should be zero or one [CollectionInfo] sections. An RDB file with more than one such section will be considered equivalent to an RDB file in which only the last [CollectionInfo] is defined.

Recognized keys in a [CollectionInfo] are:

Description: (optional) A multi-line description, which serves as a summary, expressed as a single string. (Use \n to indicate linebreaks). This field will be displayed in the Remote Document window as header information. Try to keep the Description to four or fewer lines of text, with no more than 80 characters per line.

Comment: (optional) Any descriptive tagging of the RDB file's author and creation purposes. This string field will not be displayed in the Remote Document window.

[Document]

An RDB file contains one or more [Document] sections, each of which describes a separate document. Documents may be sketches (.gsp), other rdb files, pdf files, or other types of files. Sketchpad immediately opens sketch (.gsp) and rdb files with no need to use a browser; requests for other file types are passed off to the operating system. (The operating system may pass the request to a browser, or may choose to handle it in some other way.)

Recognized keys in a [Document] are:

PrimaryDescription: (optional) One line description that describes the item. This string field will be displayed in the Remote Document window as the document's "choosable" representation. In the event the PrimaryDescription is missing, the URL will be used as a PrimaryDescription.

SecondaryDescription: (optional) A longer description of the item, possibly multiline. This string field may be displayed in the Remote Document window in some circumstances. It need not repeat information in the PrimaryDescription.

URL: A URL which tells us where to find the document. The URL may be absolute or relative. To specify a Sketchpad document with an absolute URL, use the Sketchpad-specific "rdl" protocol (for example, rdl://sample.gsp). Sketchpad interprets this rdl protocol as a request to open the document directly.

This URL may also be a relative URL, in which case it is taken to be relative to the base URL which opened the current Remote Document window. For example, if the RDB file was opened from "http://www.dynamicgeometry.com/documents.rdb", the URL "samples.gsp" would be interpreted as "http://www.dynamicgeometry.com/samples.gsp"

Filename: (optional) The file name to be associated with the document once it is opened in Sketchpad. If not present, Sketchpad will try to guess the name from the URL. The file name should include the ".gsp" extension and follow generally-acceptable principles of file names (e.g. reasonable length, no critical case sensitivities, etc.). If you provide a URL which does not itself correspond to a Sketchpad document (e.g. a CGI script that delivers Sketchpad data streams, rather than HTTP downloaded documents), you should be sure to associate a meaningful Filename key with that stream.

Type: MIME type of file (optional)

Sample RDB File

The sample RDB shown here describes an ordered collection of documents titled "Polygons." The Polygons collection includes a PDF file, a subcollection of quadrilateral documents, a Sketchpad document about equilateral triangles, and another Sketchpad document about isosceles triangles."

 

[CollectionInfo]

Description = "Polygons"

; the following comment is optional

Comment = "This collection includes triangles and quadrilaterals"

 

[Document]

PrimaryDescription = "Polygon Information"

; the following secondary description is optional

SecondaryDescription = "This document describes the different kinds of polygons"

URL = "polygon_info.pdf"

Filename="polygon_info.pdf"

Type = "application/pdf"

 

[Document]

PrimaryDescription = "Quadrilaterals"

; the following secondary description is optional

SecondaryDescription = "Go to this folder for quadrilateral constructions"

URL = "quads/quadrilaterals.rdb"

Filename="quadrilaterals.rdb"

 

[Document]

PrimaryDescription = "Equilateral Triangle"

SecondaryDescription = "This sketch contains an equilateral triangle construction."

URL = "equilateral_tri.gsp"

Filename = "rdl://sample_server.com/polygons/equilateral_tri.gsp"

Type = "application/x-gsp"

 

[Document]

PrimaryDescription = "Isosceles Triangle"

SecondaryDescription = "This sketch contains an isosceles triangle construction."

URL = "rdl://sample_server.com/polygons/isosceles_tri.gsp"

Filename = "isosceles_tri.gsp"

Type = "application/x-gsp"

Using a Link button to open remote documents

Once you've assembled a collection of documents and described them in an rdb file, you can post them on a web site and create a Link button that will open a Remote Document window and display the list of documents.

The Link button's URL should use the Sketchpad-specific rdb:// protocol, so that Sketchpad recognizes it as a Remote Document request. For instance, if the rdb file is named sample.rdb and is stored at www.myserver.com/polygons/sample.rdb, the link button should use this URL: rdb://www.myserver.com/polygons/sample.rdb

You may want to test your collection locally before uploading it to a web server. To perform a local test, use the file:/// protocol in your Link button's URL rather than the rdb:// protocol. For instance, if you've stored the collection locally at documents/testing/polygons, you could use this URL for the Link button: file:///documents/testing/polygons/sample.rdb. When you're satisfied with the collection, upload it to your web site and change the button in the sketch to use the rdb:// protocol. You can then distribute the sketch to enable other users to access your collection.

You can also link directly to a single Sketchpad document on the web, by using the rdl:// protocol. For instance, if there's a sketch on the web at www.myserver.com/polygons/triangle.gsp, you can open it directly using a Link button with this url: rdl://www.myserver.com/polygons/triangle.gsp.