Lurch web app user interface

Class

WebFileSystem

A subclass of FileSystem that represents browsing and downloading files from the web as a file system. Because it is a read-only file system, all features related to saving are not implemented.

In fact, only one method is supported, open(), the details of which are documented below. Technically, we could also implement list() in some cases, but that functionality is subsumed under open() in this class.

Warning: CORS policies on most websites severely restrict the ability of a website to load content from another website. So providing a URL that lets a student load a Lurch document from the web is very hard to do unless you control the website that's hosting the file and you can set the CORS policy to permit the Lurch app to fetch your file. An easier way to handle this is to check out a copy of the Lurch repo onto your web server and host the app yourself, so that when you provide URLs to your students, they are going to the same website as the app, and thus no CORS policies come into play.

Constructor

new WebFileSystem()

Source

Methods

fileChooserItems() → {Array.<Object>}

Override the base class implementation to fit the needs of this class. The parent class requires the file system to be able to list its files, but a web-based file system cannot do so, because of course there are an enormous number of web pages and this app cannot know them all. Therefore, this file system needs a different UI than the one the parent class provides.

Here, we provide three ways for a user to transfer a file from the web into this app. This function returns a collection of dialog items that provide such functionality, as follows.

  • One dialog item is a text box into which the user can type the URL of a file on the web. A note appears beneath this blank pointing out that many websites on the Internet do not allow for cross-site file transfer, so beware that this has limited applicability.
  • If the user enters a file into that blank and chooses to fetch it, the app will do so, and if it finds that the result is a Lurch document, it will be opened in the app. However, if it finds that the result is not a Lurch document, it will be treated as a collection of links to be shown to the user like a folder for browsing. The user can click any such link to follow it and browse the resulting "folder," etc. This allows instructors to set up nested collections of Lurch documents, organized into folders, on a website, just by writing tiny web pages with links in them (or allowing the web server to auto-generate the folder lists as pages, which many servers do).
  • The second dialog item, below the first, is a list of bookmarks. When a user is browsing any "folder" in the sense defined above, they can mark it as a bookmark to add it to this list. Each bookmark will also have an "unbookmark this" button when visiting it. This is so that a student user can visit the webpage for a course's Lurch documents, bookmark it, and never need to enter the URL again. The instructor may even update the content throughout the semester, and the user will always have it bookmarked.

If the user chooses a document, when this function calls the selectFile() method in the dialog, it will pass a file object with its file contents loaded, and the caller will not need to fetch the data itself.

Returns

  • Array.<Object>

    an array of dialog items representing the UI described above

Source

list(fileObject) → {Promise}

Override the base class implementation to fit the needs of this class. The parent class requires the file system to be able to list its files, but a web-based file system cannot do so, because of course there are an enormous number of web pages and this app cannot know them all. So instead, it provides a slightly different interpretation of the idea of "listing" files.

If browsing the "root" of the web file system, the resulting list of links is the set of bookmarks the user has saved. If browsing a different path, that path must be a URL from which a webpage will be downloaded, and all links in that page treated as the contents of a virtual "folder" at that path.

Parameters

  • fileObject Object

    as documented in the FileSystem, but with its path being either empty or a valid URL, as described above

Returns

Source

read(fileObject) → {Promise}

Implement this abstract method from the base class, in this case so that it downloads files from a given URL on the web. As long as the given file object's filename property is not undefined, this method will try to use it as a valid URL and fetch the file at that URL. If the filename is a full URL, it will be used as-is, but if it is a relative file path, it will be made absolute by considering the folder in which sits the page that launched the app.

It is an error to call this method with a file object that specifies a path. The caller should put the entire URL into the filename field instead.

Parameters

  • fileObject Object

    as documented in the FileSystem class

Returns

  • Promise

    a promise that resolves to the file object that was passed in, with its contents property set to the contents of the downloaded file, or rejects with an error if the download fails

Source