The docket file sets various options for desks with a tile and (usually) a browser-based front-end of some kind. Mainly it configures the appearance of an app's tile, the source of its glob, and some additional metadata.
The docket file is read by the
%docket agent when a desk is
%docket agent will fetch the glob if applicable and create the tile as specified on the homescreen. If the desk is published with
:treaty|publish, the information specified in the docket file will also be displayed for others who are browsing apps to install on your ship.
The docket file is optional in the general case. If it is omitted, however, the app cannot have a tile in the homescreen, nor can it be published with the
%treaty agent, so others will not be able to browse for it from their homescreens.
The docket file must be named
mark is versioned to facilitate changes down the line, so the
-0 suffix may be incremented in the future.
The file must contain a
hoon list with a series of clauses. The clauses are defined in
+$ clause$% [%title title=@t][%info info=@t][%color color=@ux][%glob-http url=cord hash=@uvH][%glob-ames =ship hash=@uvH][%image =url][%site =path][%base base=term][%version =version][%website website=url][%license license=cord]==
%image clause is optional. It is mandatory to have exactly one of either
%glob-ames. All other clauses are mandatory.
Here's what a typical docket file might look like:
:~title+'Foo'info+'An app that does a thing.'color+0xf9.8e40glob-ames+[~zod 0v0]image+'https://example.com/tile.svg'base+'foo'version+[0 0 1]license+'MIT'website+'https://example.com'==
Details of each clause and their purpose are described below.
%title field specifies the name of the app. The title will be the name shown on the app's tile, as well as the name of the app when others search for it.
%info field is a brief summary of what the app does. It will be shown as the subtitle in App Info.
info+'A Bitcoin Wallet that lets you send and receive Bitcoin directly to and from other Urbit users'
%color field specifies the color of the app tile as an
@ux-formatted hex value.
exactly one of either this, glob-ames or site is required
%glob-http field specifies the URL and hash of the app's glob if it is distributed via HTTP.
[%glob-http url=cord hash=@uvH]
exactly one of either this, glob-http or site is required
%glob-ames field specifies the ship and hash of the app's glob if it is distributed from a ship over Ames. If the glob will be distributed from our ship, the hash can initially be
0v0 as it will be overwritten with the hash produced by the Globulator.
[%glob-ames =ship hash=@uvH]
exactly one of either this, glob-ames or glob-http is required
It's possible for an app to handle HTTP requests from the client directly rather than with a separate glob. In that case, the
%site field specifies the
path of the Eyre endpoint the app will bind. If
%site is used, clicking the app's tile will simply open a new tab with a GET request to the specified Eyre endpoint.
For more information on direct HTTP handling with a Gall agent or generator, see the Eyre Internal API Reference documentation.
%image field specifies the URL of an image to be displayed on the app's tile. This field is optional and may be omitted entirely.
The given image will be displayed on top of the colored tile. The app title (and hamburger menu upon hover) will be displayed on top of the given image, in small rounded boxes with the same background color as the main tile. The given image will be displayed at 100% of the width of the tile. The image's corners will be hidden by the rounded corners of the tile, so the image itself needn't have rounded corners. The tile is a perfect square, so if the image should occupy the whole tile, it should also be a perfect square. If the image should be a smaller icon in the center of the tile (like the bitcoin tile), it should just have a square of transparent negative space around it.
It may be tempting to set the image URL as a root-relative path like
/apps/myapp/img/tile.svg and bundle it in the glob. While this would work locally, it means the image would fail to load for those browsing apps to install. Therefore, the image should be hosted somewhere globally available.
url type is a simple
+$ url cord
%base field specifies the base of the URL path of the glob resources. In the browser, the path will begin with
/apps, then the specified base, then the rest of the path to the particular glob resource like
http://localhost:8080/apps/my-base/index.html. Note the
paths of the glob contents themselves should not include this base element.
%version field specifies the current version of the app. It's a triple of three
@ud numbers representing the major version, minor version and patch version. In the client,
[1 2 3] will be rendered as
1.2.3. You would typically increase the appropriate number each time you published a change to the app.
version type is just a triple of three numbers:
+$ version[major=@ud minor=@ud patch=@ud]
version+[0 0 1]
%website field is for a link to a relevant website. This might be a link to the app's github repo, company website, or whatever is appropriate. This field will be displayed when people are browsing apps to install.
url type is a simple
+$ url cord
%license field specifies the license for the app in question. It would typically be a short name like
GPLv2, or what have you. The field just takes a
cord so any license can be specified.