Skip to content

Commit 4c24e73

Browse files
aarongustafsonaarongustafson
authored
Add shortcuts feature to the explainer and spec (#768)
Adding shortcuts to the explainer
1 parent 32ce484 commit 4c24e73

File tree

2 files changed

+249
-0
lines changed

2 files changed

+249
-0
lines changed

‎explainer.md

+56
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,62 @@ TBW: using description and screenshots.
194194
## Theme color and background color
195195
TBW...
196196

197+
## Adding shortcuts
198+
Numerous operating systems grant native applications the ability to add menu items to the app icon itself. These often provide quick access to key tasks for an app. Typically, these are exposed via a right click, long tap, or a similar context menu-triggering action. For web applications, you can define a set of shortcuts to be exposed when the app is installed. Each shortcut item must have a name and a target URL. You may also include additional information, such as a shorter name, a description for the action, and one or more icons.
199+
200+
```JSON
201+
"shortcuts": [
202+
{
203+
"name": "Play Later",
204+
"description": "View the list of podcasts you saved for later",
205+
"url": "/play-later",
206+
"icons": [
207+
{
208+
"src": "/icons/play-later.svg",
209+
"type": "image/svg+xml",
210+
"purpose": "any"
211+
}
212+
]
213+
},
214+
{
215+
"name": "Subscriptions",
216+
"description": "View the list of podcasts you listen to",
217+
"url": "/subscriptions",
218+
"icons": [
219+
{
220+
"src": "/icons/subscriptions.svg",
221+
"type": "image/svg+xml",
222+
"purpose": "any"
223+
}
224+
]
225+
},
226+
{
227+
"name": "Search",
228+
"description": "Search for new podcasts to listen to",
229+
"url": "/search",
230+
"icons": [
231+
{
232+
"src": "/icons/search.svg",
233+
"type": "image/svg+xml",
234+
"purpose": "any"
235+
}
236+
]
237+
},
238+
{
239+
"name": "Discover",
240+
"description": "Browse for new podcasts to listen to",
241+
"url": "/discover",
242+
"icons": [
243+
{
244+
"src": "/icons/discover.svg",
245+
"type": "image/svg+xml",
246+
"purpose": "any"
247+
}
248+
]
249+
}
250+
]
251+
```
252+
197253
## How can I detect if the user "installed" my app?
198254
The spec provides a way for you to detect when the user installs your apps by registering for "appinstalled" events.
199255

‎index.html

+193
Original file line numberDiff line numberDiff line change
@@ -1558,6 +1558,10 @@ <h3>
15581558
<var>manifest</var>["<a>serviceworker</a>"], <var>manifest URL</var>,
15591559
and <var>serviceworker</var>.
15601560
</li>
1561+
<li>Set <var>manifest</var>["<a>shortcuts</a>"] to the result of
1562+
running <a>processing the <code>shortcuts</code> member</a> given
1563+
<var>manifest URL</var>, and <code>"shortcuts"</code>.
1564+
</li>
15611565
<li>
15621566
<a>Extension point</a>: process any proprietary and/or other
15631567
supported members at this point in the algorithm.
@@ -1634,6 +1638,7 @@ <h2>
16341638
ServiceWorkerRegistrationObject serviceworker;
16351639
sequence&lt;ExternalApplicationResource&gt; related_applications;
16361640
boolean prefer_related_applications = "false";
1641+
sequence&lt;ShortcutItem&gt; shortcuts;
16371642
};
16381643
</pre>
16391644
<p>
@@ -2403,6 +2408,102 @@ <h3>
24032408
can get their games and apps rated with IARC</a>.
24042409
</p>
24052410
</section>
2411+
<section>
2412+
<h3>
2413+
<code>shortcuts</code> member
2414+
</h3>
2415+
<p>
2416+
The <dfn>shortcuts</dfn> member is an <a>array</a> of
2417+
<a>ShortcutItem</a>s that provide access to key tasks within a web
2418+
application.
2419+
</p>
2420+
<p class="note">
2421+
Shortcuts could, for instance, be used to link directly to a user's
2422+
timeline within a social media application or to their recent orders
2423+
in an e-commerce context.
2424+
</p>
2425+
<p>
2426+
How shortcuts are presented, and how many of them are shown to the
2427+
user, is at the discretion of the user agent and/or operating system.
2428+
</p>
2429+
<p class="note">
2430+
Developers are encouraged to order their shortcuts by priority, with
2431+
the most critical shortcuts appearing first in the array.
2432+
</p>
2433+
<p>
2434+
The steps for <dfn>processing the <code>shortcuts</code> member</dfn>
2435+
are given by the following algorithm. The algorithm takes a
2436+
<a data-cite=
2437+
"WEBIDL#sequence-type">sequence</a>&lt;<a>ShortcutItem</a>&gt;
2438+
<var>shortcuts</var> as an argument. This algorithm returns an
2439+
<a data-cite=
2440+
"WEBIDL#sequence-type">sequence</a>&lt;<a>ShortcutItem</a>&gt;. For
2441+
each <var>shortcut</var> (<a>ShortcutItem</a>) in the sequence, set
2442+
<var>shortcut.icons</var> to the result of running <a>processing
2443+
`ImageResource` members</a> given <var>shortcut.icons</var> and
2444+
<var>manifest URL</var>. For each <var>shortcut</var>
2445+
(<a>ShortcutItem</a>) in the sequence, parse
2446+
<var>shortcut</var>["<a>url</a>"] using <var>manifest URL</var> as
2447+
the base URL.
2448+
</p>
2449+
<p>
2450+
A user agent SHOULD expose shortcuts via interactions that are
2451+
consistent with exposure of an application icon's context menu in the
2452+
host operating system (e.g., right click, long press). A user agent
2453+
SHOULD render the shortcuts in the same order as they are provided in
2454+
the manifest. A user agent SHOULD represent the shortcuts in a manner
2455+
consistent with exposure of an application icon's context menu in the
2456+
host operating system. A user agent MAY truncate the list of
2457+
shortcuts presented in order to remain consistent with the
2458+
conventions or limitations of the host operating system.
2459+
</p>
2460+
<div class="example">
2461+
<p>
2462+
In the following example, the developer has included two shortcuts.
2463+
Assuming the the manifest's URL is
2464+
<samp>https://example.com/manifest.webmanifest</samp>:
2465+
</p>
2466+
<ul>
2467+
<li>The first shortcut would be displayed with the text "Play
2468+
Later". If the operating system supports icons for context menu
2469+
items and it also supports SVG images for that purpose, the user
2470+
agent would present
2471+
<samp>https://example.com/icons/play-later.svg</samp> next to the
2472+
text. When launched, the user agent would instantiate a new
2473+
<a>top-level browsing context</a> and navigate to
2474+
<samp>https://example.com/play-later</samp>.
2475+
</li>
2476+
<li>The first shortcut would be displayed with the text
2477+
"Subscriptions". When launched, the user agent would instantiate a
2478+
new <a>top-level browsing context</a> and navigate to
2479+
<samp>https://example.com/subscriptions?sort=desc</samp>.
2480+
</li>
2481+
</ul>
2482+
<pre class="example json">
2483+
{
2484+
"shortcuts": [
2485+
{
2486+
"name": "Play Later",
2487+
"description": "View the list of podcasts you saved for later",
2488+
"url": "/play-later",
2489+
"icons": [
2490+
{
2491+
"src": "/icons/play-later.svg",
2492+
"type": "image/svg+xml",
2493+
"purpose": "any"
2494+
}
2495+
]
2496+
},
2497+
{
2498+
"name": "Subscriptions",
2499+
"description": "View the list of podcasts you listen to",
2500+
"url": "/subscriptions?sort=desc"
2501+
}
2502+
]
2503+
}
2504+
</pre>
2505+
</div>
2506+
</section>
24062507
</section>
24072508
<section>
24082509
<h2>
@@ -2953,6 +3054,98 @@ <h3>
29533054
</ol>
29543055
</section>
29553056
</section>
3057+
<section>
3058+
<h2>
3059+
<dfn>ShortcutItem</dfn> and its members
3060+
</h2>
3061+
<pre class="idl">
3062+
dictionary ShortcutItem {
3063+
required USVString name;
3064+
USVString short_name;
3065+
USVString description;
3066+
required USVString url;
3067+
sequence&lt;ImageResource&gt; icons;
3068+
};
3069+
</pre>
3070+
<p>
3071+
Each <a>ShortcutItem</a> represents a link to a key task or page within
3072+
a web app. A user agent can use these values to assemble a context menu
3073+
to be displayed by the operating system when a user engages with the
3074+
web app's icon. When the user invokes a shortcut from the operating
3075+
system menu, the user agent SHOULD run <a>Launching a shortcut</a>.
3076+
</p>
3077+
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
3078+
<h3>
3079+
<code>name</code> member
3080+
</h3>
3081+
<p>
3082+
The <dfn>name</dfn> member of a <a>ShortcutItem</a> is a
3083+
<a>string</a> that represents the name of the shortcut as it is
3084+
usually displayed to the user in a context menu.
3085+
</p>
3086+
</section>
3087+
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
3088+
<h3>
3089+
<code>short_name</code> member
3090+
</h3>
3091+
<p>
3092+
The <dfn>short_name</dfn> member of a <a>ShortcutItem</a> is a
3093+
<a>string</a> that represents a short version of the name of the
3094+
shortcut. It is intended to be used where there is insufficient space
3095+
to display the full name of the shortcut.
3096+
</p>
3097+
</section>
3098+
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
3099+
<h3>
3100+
<code>description</code> member
3101+
</h3>
3102+
<p>
3103+
The <dfn>description</dfn> member of a <a>ShortcutItem</a> is a
3104+
<a>string</a> that allows the developer to describe the purpose of
3105+
the shortcut. User agents MAY expose this information to assistive
3106+
technology.
3107+
</p>
3108+
</section>
3109+
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
3110+
<h3>
3111+
<code>url</code> member
3112+
</h3>
3113+
<p>
3114+
The <dfn>url</dfn> member of a <a>ShortcutItem</a> is the <a>URL</a>
3115+
that opens when the associated shortcut is activated.
3116+
</p>
3117+
</section>
3118+
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
3119+
<h3>
3120+
<dfn>icons</dfn> member
3121+
</h3>
3122+
<p>
3123+
The <a>icons</a> member of an <a>ShortcutItem</a> member is an
3124+
<a>array</a> of <a>ImageResource</a>s that can serve as iconic
3125+
representations of the shortcut in various contexts.
3126+
</p>
3127+
</section>
3128+
<section>
3129+
<h3>
3130+
<dfn>Launching a shortcut</dfn>
3131+
</h3>
3132+
<p>
3133+
When <a>ShortcutItem</a> <var>shortcut</var> having
3134+
<a>WebAppManifest</a> <var>manifest</var> is invoked, run the
3135+
following steps:
3136+
</p>
3137+
<ol>
3138+
<li>Let <var>url</var> be <var>shortcut.url</var>.
3139+
</li>
3140+
<li>Let <var>browsing context</var> be the result of creating a new
3141+
<a>top-level browsing context</a>.
3142+
</li>
3143+
<li>
3144+
<a>Navigate</a> <var>browsing context</var> to <var>url</var>.
3145+
</li>
3146+
</ol>
3147+
</section>
3148+
</section>
29563149
<section>
29573150
<h2>
29583151
Multi-purpose members

0 commit comments

Comments
 (0)