User Guide - TJohn2017/Laputa GitHub Wiki

Overview

Welcome to Laputa! We'll help you get started. This page will provide a general introduction to the Laputa app, and how to use it.

App Flow

Here we will walk through the main parts of Laputa, starting with the main page.

Main Page

In the main page, we have two major column sections that are used to display a list of the user's created and saved "hosts" or "canvases". In Laputa, these are the two main objects that a user interacts with. A "host" refer to the SSH host configurations that have been saved from the user --- much like a SSH configuration file, Laputa saves all the connection information for a particular host so that a user can quickly connect to that host in a terminal / SSH client whenever they need to. A "canvas" refers to an annotatable, blank page where the user can mark up the page using the Apple Pencil while also managing and annotating "cards" that contain user-saved terminal outputs.

On the Main Page, the user can easily toggle between the Hosts and Canvases lists to view the saved entities and potentially launch a session from any given entity. One can tap the "settings" icon right next to each canvas or host entity to present different options like deleting the entity or editing its content. By clicking on the "plus" button in the upper-righthand corner, a user can quickly add a new host configuration or create a new, blank canvas depending on which page they are on:

Session Page --- Selecting a Host from Main Page

When the user taps on a host entity from the Main Page, Laputa launches into a terminal-only session where it tries to connect to the given host and starts up a terminal for the user to interact with:

From here, the user can interact with the terminal as they would in a computer, running programs, opening files, navigating through the filesystem, etc. One can use Laputa in either landscape or portrait mode and either with the native IOS keyboard or a connected physical keyboard. In the event of a failure to connect, Laputa throws an error screen:

Additionally, we have the option to add more than one terminal to our current session that we can then switch to and from using a new tab bar. To do this, we can tap the "plus" menu button in the upper-righthand corner to present the "Add Terminal" button from which we can choose a terminal to add from our existing list or choose to create and add a brand new host:

Session Page --- Selecting a Canvas from Main Page

When the user taps on a canvas entity from the Main Page, Laputa launches into a canvas-only session where the user is free to markup the canvas with an Apple Pencil as they would on any note-taking app while also being able to move around any cards that are associated with the given canvas. One can navigate around the canvas by dragging the screen and they can zoom in and out of certain sections by pinching in and out. To re-center your canvas view, one can press the red "target" button. To switch between annotation and interaction mode in the canvas (in annotation mode one can annotate the screen with an Apple Pencil; in interaction mode, one can move code cards around), a user can either the tap the black button or double tap the screen with their fingers. Additionally, users can resize any canvas card by tapping the yellow "resize" icon on any code card and dragging around the corner --- to delete a card, a user can long-press on any card and a delete button will appear. Any annotations or code cards that are added to or moved in a canvas will be saved and preserved when a user leaves the session.

Session Page --- Terminal / Canvas Split

In addition to the canvas-only or terminal-only session states, there is one other major session configuration that Laputa allows namely a "split" session where we are hosting a canvas and at least one terminal at the same time in a split screen fashion. There are multiple ways for the user to get into this state. The first way is from the main page: the user can tap the "settings" icon menu button next to each canvas or host entity which presents a "Open with a canvas" or "Open with a host" button (among the other settings options) --- by tapping this button, the user will then be presented with a list of possible options to choose to start a split session with immediately:

The other way for the user to enter into a split session is by directly adding a canvas or a terminal from a terminal-only or canvas-only session state. The user can do this by tapping the "plus" menu button in the upper-right hand corner of the session page which presents an "Add Terminal" and "Add Canvas" button (in the canvas-only case, "Add Canvas" is not presented since Laputa doesn't support multiple canvases in one session at the moment). Tapping either button prompts the user to select a corresponding canvas or terminal option (in a sheet view like the one above) to initiate a split session with.

Once the user has started a split session, they will see a state like the following:

If a user had multiple terminals in a terminal-only view or adds another terminal from a split-session, they will also see the tab bar:

From a split session, the user can now interact with both a canvas and one or more terminals at the same time! If they need to increase the terminal or canvas window more, they can adjust a slider at the top of the terminal component as needed. The last large interactive feature that Laputa presents is creating code cards in a split session! To do so, a user taps the "add card" icon button in the bottom-righthand corner of the terminal component at which point they can manually highlight any text in the terminal page (which is indicated visually by a grey highlight) --- when the user lifts their finger off the screen, any highlighted text in the terminal component will be read into a code card and added and saved to the canvas. We can see this in the example below:

With these tools in mind, Users are free to work in the terminal as needed, switching between different connections, and adding annotations to a main canvas page and saving code and terminal outputs in code cards as needed. We hope Laputa presents an interesting experiment in different interactive design when it comes to the terminal workflow! Interested in learning more about how the app works? Continue on the Developer Guide page!