Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add shortcuts feature to the explainer and spec #768

Merged
merged 25 commits into from
Nov 4, 2019
Merged

Add shortcuts feature to the explainer and spec #768

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
a9179a1
example: update example to reflect modern times.
Jan 28, 2017
83bfb5b
fix: respec dfn errors
marcoscaceres Jan 28, 2017
1df16d7
fix: autopub on master, not gh-pages (#544)
Jan 29, 2017
3383ea7
meaningless change, trying to get Travis working (#545)
Jan 29, 2017
2e7ac23
Removed six occurrences of superfluous spaces after quotes.
tomayac Sep 22, 2017
4e3e90b
Merge pull request #615 from tomayac/patch-2
anssiko Sep 22, 2017
3e967e0
Adding shortcuts to the explainer
aarongustafson Jun 14, 2019
5a9e33d
Progress on shortcuts spec
aarongustafson Jun 20, 2019
a885c67
Fixing a Respec issue with ImageResource
aarongustafson Jun 20, 2019
863a417
Addressing the last of the Respec errrs
aarongustafson Jun 20, 2019
7be9fd2
Content tweaks for readability & such
aarongustafson Jun 20, 2019
60703f5
Tidy
aarongustafson Jun 20, 2019
54b7a69
Remediations per @kenchris
aarongustafson Jun 21, 2019
87529c3
Adding a note about parsing ShortcutItem icons.
aarongustafson Jun 21, 2019
82eb288
Merge branch 'gh-pages' into adding-shortcuts
Sep 9, 2019
b76a266
Changes per @mguica
aarongustafson Sep 10, 2019
8265ea7
Merge branch 'adding-shortcuts' of github.com:aarongustafson/manifest…
aarongustafson Sep 10, 2019
de5e0da
More changes per @mguica
aarongustafson Sep 10, 2019
6909d17
Manual merge from source
aarongustafson Sep 10, 2019
ab7d68c
Manual merge from source/master
aarongustafson Sep 10, 2019
9ee0e1b
Removing RequestParams/shortcut.params
aarongustafson Sep 16, 2019
41d88f3
Resolves @mgiuca’s review
aarongustafson Nov 3, 2019
708c3b7
Merge branch 'gh-pages' into adding-shortcuts
aarongustafson Nov 3, 2019
4120edf
Resolves @mgiuca’s remaining change requests
aarongustafson Nov 4, 2019
59eaa7a
Merge branch 'adding-shortcuts' of github.com:aarongustafson/manifest…
aarongustafson Nov 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions explainer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,62 @@ TBW: using description and screenshots.
## Theme color and background color
TBW...

## Adding shortcuts
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.

```JSON
"shortcuts": [
{
"name": "Play Later",
"description": "View the list of podcasts you saved for later",
"url": "/play-later",
"icons": [
{
"src": "/icons/play-later.svg",
"type": "image/svg+xml",
"purpose": "any"
}
]
},
{
"name": "Subscriptions",
"description": "View the list of podcasts you listen to",
"url": "/subscriptions",
"icons": [
{
"src": "/icons/subscriptions.svg",
"type": "image/svg+xml",
"purpose": "any"
}
]
},
{
"name": "Search",
"description": "Search for new podcasts to listen to",
"url": "/search",
"icons": [
{
"src": "/icons/search.svg",
"type": "image/svg+xml",
"purpose": "any"
}
]
},
{
"name": "Discover",
"description": "Browse for new podcasts to listen to",
"url": "/discover",
"icons": [
{
"src": "/icons/discover.svg",
"type": "image/svg+xml",
"purpose": "any"
}
]
}
]
```

## How can I detect if the user "installed" my app?
The spec provides a way for you to detect when the user installs your apps by registering for "appinstalled" events.

Expand Down
193 changes: 193 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1558,6 +1558,10 @@ <h3>
<var>manifest</var>["<a>serviceworker</a>"], <var>manifest URL</var>,
and <var>serviceworker</var>.
</li>
<li>Set <var>manifest</var>["<a>shortcuts</a>"] to the result of
running <a>processing the <code>shortcuts</code> member</a> given
<var>manifest URL</var>, and <code>"shortcuts"</code>.
</li>
<li>
<a>Extension point</a>: process any proprietary and/or other
supported members at this point in the algorithm.
Expand Down Expand Up @@ -1634,6 +1638,7 @@ <h2>
ServiceWorkerRegistrationObject serviceworker;
sequence&lt;ExternalApplicationResource&gt; related_applications;
boolean prefer_related_applications = "false";
sequence&lt;ShortcutItem&gt; shortcuts;
};
</pre>
<p>
Expand Down Expand Up @@ -2403,6 +2408,102 @@ <h3>
can get their games and apps rated with IARC</a>.
</p>
</section>
<section>
<h3>
<code>shortcuts</code> member
</h3>
<p>
The <dfn>shortcuts</dfn> member is an <a>array</a> of
<a>ShortcutItem</a>s that provide access to key tasks within a web
application.
</p>
<p class="note">
Shortcuts could, for instance, be used to link directly to a user's
timeline within a social media application or to their recent orders
in an e-commerce context.
</p>
<p>
How shortcuts are presented, and how many of them are shown to the
user, is at the discretion of the user agent and/or operating system.
</p>
<p class="note">
Developers are encouraged to order their shortcuts by priority, with
the most critical shortcuts appearing first in the array.
</p>
<p>
The steps for <dfn>processing the <code>shortcuts</code> member</dfn>
are given by the following algorithm. The algorithm takes a
<a data-cite=
"WEBIDL#sequence-type">sequence</a>&lt;<a>ShortcutItem</a>&gt;
<var>shortcuts</var> as an argument. This algorithm returns an
<a data-cite=
"WEBIDL#sequence-type">sequence</a>&lt;<a>ShortcutItem</a>&gt;. For
each <var>shortcut</var> (<a>ShortcutItem</a>) in the sequence, set
<var>shortcut.icons</var> to the result of running <a>processing
`ImageResource` members</a> given <var>shortcut.icons</var> and
<var>manifest URL</var>. For each <var>shortcut</var>
(<a>ShortcutItem</a>) in the sequence, parse
<var>shortcut</var>["<a>url</a>"] using <var>manifest URL</var> as
the base URL.
</p>
<p>
A user agent SHOULD expose shortcuts via interactions that are
consistent with exposure of an application icon's context menu in the
host operating system (e.g., right click, long press). A user agent
SHOULD render the shortcuts in the same order as they are provided in
the manifest. A user agent SHOULD represent the shortcuts in a manner
consistent with exposure of an application icon's context menu in the
host operating system. A user agent MAY truncate the list of
shortcuts presented in order to remain consistent with the
conventions or limitations of the host operating system.
</p>
<div class="example">
<p>
In the following example, the developer has included two shortcuts.
Assuming the the manifest's URL is
<samp>https://example.com/manifest.webmanifest</samp>:
</p>
<ul>
<li>The first shortcut would be displayed with the text "Play
Later". If the operating system supports icons for context menu
items and it also supports SVG images for that purpose, the user
agent would present
<samp>https://example.com/icons/play-later.svg</samp> next to the
text. When launched, the user agent would instantiate a new
<a>top-level browsing context</a> and navigate to
<samp>https://example.com/play-later</samp>.
</li>
<li>The first shortcut would be displayed with the text
"Subscriptions". When launched, the user agent would instantiate a
new <a>top-level browsing context</a> and navigate to
<samp>https://example.com/subscriptions?sort=desc</samp>.
aarongustafson marked this conversation as resolved.
Show resolved Hide resolved
</li>
</ul>
<pre class="example json">
{
"shortcuts": [
{
"name": "Play Later",
"description": "View the list of podcasts you saved for later",
"url": "/play-later",
"icons": [
{
"src": "/icons/play-later.svg",
"type": "image/svg+xml",
"purpose": "any"
}
]
},
{
"name": "Subscriptions",
"description": "View the list of podcasts you listen to",
"url": "/subscriptions?sort=desc"
}
]
}
</pre>
</div>
</section>
</section>
<section>
<h2>
Expand Down Expand Up @@ -2953,6 +3054,98 @@ <h3>
</ol>
</section>
</section>
<section>
<h2>
<dfn>ShortcutItem</dfn> and its members
</h2>
<pre class="idl">
dictionary ShortcutItem {
required USVString name;
USVString short_name;
USVString description;
required USVString url;
sequence&lt;ImageResource&gt; icons;
};
</pre>
<p>
Each <a>ShortcutItem</a> represents a link to a key task or page within
a web app. A user agent can use these values to assemble a context menu
to be displayed by the operating system when a user engages with the
web app's icon. When the user invokes a shortcut from the operating
system menu, the user agent SHOULD run <a>Launching a shortcut</a>.
</p>
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
<h3>
<code>name</code> member
</h3>
<p>
The <dfn>name</dfn> member of a <a>ShortcutItem</a> is a
<a>string</a> that represents the name of the shortcut as it is
usually displayed to the user in a context menu.
</p>
</section>
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
<h3>
<code>short_name</code> member
</h3>
<p>
The <dfn>short_name</dfn> member of a <a>ShortcutItem</a> is a
<a>string</a> that represents a short version of the name of the
shortcut. It is intended to be used where there is insufficient space
to display the full name of the shortcut.
</p>
</section>
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
<h3>
<code>description</code> member
</h3>
<p>
The <dfn>description</dfn> member of a <a>ShortcutItem</a> is a
<a>string</a> that allows the developer to describe the purpose of
the shortcut. User agents MAY expose this information to assistive
technology.
</p>
</section>
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
<h3>
<code>url</code> member
</h3>
<p>
The <dfn>url</dfn> member of a <a>ShortcutItem</a> is the <a>URL</a>
that opens when the associated shortcut is activated.
</p>
</section>
<section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
<h3>
<dfn>icons</dfn> member
</h3>
<p>
The <a>icons</a> member of an <a>ShortcutItem</a> member is an
<a>array</a> of <a>ImageResource</a>s that can serve as iconic
representations of the shortcut in various contexts.
</p>
</section>
<section>
<h3>
<dfn>Launching a shortcut</dfn>
aarongustafson marked this conversation as resolved.
Show resolved Hide resolved
</h3>
<p>
When <a>ShortcutItem</a> <var>shortcut</var> having
<a>WebAppManifest</a> <var>manifest</var> is invoked, run the
following steps:
</p>
<ol>
<li>Let <var>url</var> be <var>shortcut.url</var>.
aarongustafson marked this conversation as resolved.
Show resolved Hide resolved
</li>
<li>Let <var>browsing context</var> be the result of creating a new
aarongustafson marked this conversation as resolved.
Show resolved Hide resolved
<a>top-level browsing context</a>.
</li>
<li>
<a>Navigate</a> <var>browsing context</var> to <var>url</var>.
</li>
</ol>
</section>
</section>
<section>
<h2>
Multi-purpose members
Expand Down