Skip to content

App Launch Fragments

Sobamail Desktop shows an app's page at

soba://<instid>.<replica>.instance/#<fragment>

where <instid> is the instance id and <replica> the uuid of the mailbox the instance belongs to, both as 26 base32hex digits. The fragment, the part after the #, is how the client tells the app what to show: an app reads location.hash when it loads and on every hashchange, acts on it, and drops it from the URL (history.replaceState) once acted on, so that a reload of the page does not apply it again. A fragment the app does not understand is dropped the same way. The Chat app keeps a fragment in the URL instead, the one that names the room it shows; see its section below.

The client opens the same instance in one place at a time: a launch on a fragment while the instance already has a tab switches to that tab and changes its fragment, which the app sees as a hashchange.

How the fragment is written

The fragment is a path, optionally followed by ? and a query. The client encodes the query with Qt's QUrlQuery in its fully encoded form: a space is %20, & is %26, < and > are %3C and %3E, : and @ stay as they are, and a + stays a literal +. An app decodes each item with decodeURIComponent, never with URLSearchParams, which would turn that + into a space (as in user+tag@example.com). A uuid rides braced, the way the platform spells one, percent-encoded as %7B...%7D.

Fragments the client sends

Every app: pane/<pane>[,<pane>]

The side bar of the main window shows an app's left pane in a narrow web view. It opens the app on pane/left, and the app shows the named panes alone, leaving out the rest of its layout. Unlike the other fragments this one stays in the URL, so a reload keeps the panes. The pane names are the app's own; the Contacts and Calendar apps know left and right, the Chat app left alone: its sidebar, the list of rooms with the search box atop it. A room picked there opens in the app's tab.

An app shown so opens the whole of itself with window.open("#<fragment>", "_blank"): the client takes a new window on the app's own document to the app's tab, made when it has none, on that fragment. A new window on any other URL is refused.

Contacts: person/show, person/new

Fragment Opens
person/show?email=<address>&name=<display name> The person holding the address, or the add screen prefilled with the address and name. The reader's Open contact card sends it; an empty name is left out.
person/show?uuid=<uuid> The card with that uuid. The app's own narrow list sends it to open the full app on a contact.
person/new An empty new contact card.

Calendar: <date>/agenda/search/<text>

<YYYY-MM-DD>/agenda/search/<text> opens the agenda at the date with the search box holding <text>, percent-encoded. The contact view's Show events sends it with the contact's address, which matches the guests of the contact's events. The app's full fragment grammar is [pane/<pane>[,<pane>]/]<YYYY-MM-DD>[/<view>[/event/<id>]].

Chat: channel/<name>, dm/<address>, message/<uuid>

The Chat app's fragment names the room on screen. The app writes it whenever the room changes, and opens the room a fragment names when it loads and on every hashchange, so a reload comes back to the same room. Going from one room to another adds a history entry (history.pushState): back and forward go through the rooms.

Shown alone in the reader pane's place, the app offers Chat about <subject>, which opens the whole of it on the room shown: window.open on the room's fragment, message/<message uuid>?view=full for a room about a mail message.

Fragment Room
channel/<name> The channel of that name. Two channels of the same name are told apart by a uuid item: channel/<name>?uuid=<channel uuid>.
dm/<address> The private chat with the person at that address; the address percent-encoded, its @ kept. The contact view's Open in Chat sends it with the contact's first address.
message/<message uuid> The room about that mail message, shown alone, as in the reader pane's place.
message/<message uuid>?view=full The same room in the whole of the app's layout.

A fragment opens a room the user is already in and never makes one: one that names no such room, or that the app does not understand, changes nothing on screen and is replaced with the fragment of the room shown. A dm/<address> with someone the user has no private chat with also opens the app's dialog that starts one, the address filled in; the chat is made only when the user confirms. The other exception is the launch below, which leads to a new room through the app's picker; while the picker is up the fragment stays as the client sent it.

message/<message uuid>?subject=<subject>&person=<Name <address>>&person=<address>

Chat About This on a mail message opens the Chat app on it, in the reader pane's place. The uuid is the mail message's; the app keeps it as the anchor of the room about the message, so a second launch on the same message opens the room the user already has. subject is the mail's subject, the room's name; it is left out when blank. Each person item is someone in the message's thread, as a header named them: Name <address> when the header carried a name, the bare address otherwise, each address once, the user's own left out. The app lists them in its picker and starts the room with the ones the user ticks. An app has no way to read the mailbox, which is why the people travel in the fragment.

message/<message uuid>?view=full&subject=<subject>&person=...

In the message list, a message the user is in a room about carries a chat mark, and a click on the mark opens the Chat app in its tab on the same fragment with one more item, view=full, ahead of the others. It says that the app has a tab to itself: the app opens the room in the whole of its layout, where without the item it shows the room alone, as fits the reader pane. The rest of the fragment is the same, so a room that is gone by the time of the click leaves the app with its picker.

Fragments the client answers

An app cannot read the mailbox, so it cannot show a mail message; the client can. A new window on the app's own document on one of the fragments below is answered by the client, and the app is not launched on it.

Every app: mail/<uuid>

mail/<message uuid>

The client shows the mail message with that uuid in the mailbox the app's instance belongs to. The uuid is braced or bare, percent-encoded or as it is, and nothing follows it. An app writes it as a link:

<a href="#mail/%7B0a0a0a0a-0000-4000-8000-000000000007%7D" target="_blank">Q3 numbers</a>

When the app stands in the reader pane's place on that very message, as the Chat app does after Chat About This, the reader pane comes back with the message. Otherwise the message opens in a tab, or the tab that already shows it is switched to. A uuid the mailbox does not hold opens nothing, and the status bar says that the message is not in this mailbox: someone invited to a Chat room about a message may never have received the message.

The Chat app links the subject of a room about a message this way.