From 1051a77b24f26e5f0a3809d93f7879ff02819f64 Mon Sep 17 00:00:00 2001 From: alancutter Date: Tue, 8 Nov 2022 04:53:07 +0000 Subject: [PATCH] editorial: Define an algorithm for launching a web app (#1056) SHA: a0808b8d894a64dafedc1e70a263b4ea2210a080 Reason: push, by alancutter Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- index.html | 332 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 238 insertions(+), 94 deletions(-) diff --git a/index.html b/index.html index f4020d7ed..4f7702362 100644 --- a/index.html +++ b/index.html @@ -530,9 +530,11 @@

Web Application Manifest

Installable web applications
  1. 5.1 Application's name -
  2. 5.2 +
  3. 5.2 + Launching a web application +
  4. 5.3 Privacy and security considerations -
  5. 5.3 +
  6. 5.4 Uninstallation
  • 6. Navigation scope @@ -2880,18 +2882,10 @@

    Web Application Manifest

    When shortcut item shortcut having - manifest is invoked, run the following steps: + manifest is invoked, run the steps to + launch a web application with manifest and + shortcut.url.

    -
      -
    1. Let url be shortcut.url. -
      2. -
    2. Let browsing context be the result of creating a new - top-level browsing context. -
      3. -
    3. - Navigate browsing context to url. -
      4. -

    3.7 Processing shortcut items @@ -3088,27 +3082,28 @@

    Web Application Manifest

    A common use case of a manifest is for a user agent to install a web application; whereby the user agent - provides the end-user with a means of instantiating a new top-level + provides the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. A web application that is installed is known as a installed web application. That is, the manifest's members, or - their defaults, are in effect on the top-level browsing context. + their defaults, are in effect on the top-level browsing context. This distinguishes an installed web application from a traditional bookmark, as opening a web page from a traditional bookmark will not have the manifest's properties applied to it.

    -

    +

    Note

    For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start - menu. When launched, the manifest is applied by the user agent - to the top-level browsing context prior to the start URL - being loaded. This gives the user agent an opportunity to apply the - relevant values of the manifest, possibly changing the display - mode and screen orientation of the web application. Alternatively, - and again as an example, the user agent could install the web - application into a list of bookmarks within the user agent itself. -

    + menu. When launching a web application, the manifest is + applied by the user agent to the top-level browsing + context prior to the start URL being loaded. This gives the + user agent an opportunity to apply the relevant values of the manifest, + possibly changing the display mode and screen orientation of the + web application. Alternatively, and again as an example, the user agent + could install the web application into a list of bookmarks within + the user agent itself. +

    5.1 Application's name

    @@ -3142,14 +3137,79 @@

    Web Application Manifest

    available underneath an icon).

    -

    5.2 +

    5.2 + Launching a web application +

    + +

    + At the discretion of the operating system or user agent, run the steps + to launch a web application with a + processed manifest. +

    +
    Note

    + This would typically take place when the user selects an installed + web app from an app launching UI surface e.g., a home screen, launcher + or start menu. +

    +

    + The steps to + launch a web + application is given by the following algorithm. The algorithm + takes a processed manifest manifest, + an optional URL target URL, an optional POST resource + POST resource and returns an application context. +

    +

    + target URL, if given, MUST be within scope of + manifest. +

    +

    + Other specifications MAY replace this algorithm's steps with their own + steps. This replacement will take effect for all invocations of + launch a web application. +

    +
    Note

    + This algorithm is replaceable to allow an experimental + launch_handler + manifest field to configure the behavior of all web application + launches. The replacement algorithm invokes create a new application context by default but under certain conditions behaves + differently. +

    +
      +
    1. Return the result of running the steps to create a new application context passing manifest, target URL and + POST resource. +
      2. +
    +

    + The steps to create a new application context + is given by the following algorithm. The algorithm takes a + processed manifest manifest, + an optional URL target URL, an optional POST resource + POST resource and returns an application context. +

    +
      +
    1. If target URL was not given, set target URL to start URL. +
      2. +
    2. Let traversable be the result of running the steps to create a fresh top-level traversable with target URL and + POST resource. +
      3. +
    3. Let browsing context be the traversable's + active browsing context. +
      4. +
    4. Apply manifest to browsing context. +
      5. +
    5. Return browsing context. +
      6. +
    +
    +

    5.3 Privacy and security considerations -

    +

    It is RECOMMENDED that UI that affords the end user the ability to - install a web application also allows inspecting the icon, - name, start URL, origin, etc. pertaining to a web application. + install a web application also allows inspecting the icon, + name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the @@ -3163,13 +3223,13 @@

    Web Application Manifest

    a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web - application is installed - or by using an entirely different + application is installed - or by using an entirely different cache from that used for regular web browsing.

    -

    5.3 +

    5.4 Uninstallation -

    +

    User agents SHOULD provide a mechanism for the user to remove an @@ -3189,11 +3249,11 @@

    Web Application Manifest

    The navigation scope of a manifest is the "scope" item - of a processed manifest. The navigation scope restricts - the set of URLs to which an application context can be - navigated while the manifest is applied. + of a processed manifest. The navigation scope restricts + the set of URLs to which an application context can be + navigated while the manifest is applied.

    -
    Note
    +
    Note

    If the scope member is not present in the manifest, it defaults to the parent path of the start_url member. For @@ -3210,7 +3270,7 @@

    Web Application Manifest

    - A URL target is said to be within scope of URL scope if the + A URL target is said to be within scope of URL scope if the following algorithm returns true:

      @@ -3227,11 +3287,11 @@

      Web Application Manifest

    - A URL target is within scope of a + A URL target is within scope of a manifest if the target is within scope of manifest's navigation scope (i.e., within scope of manifest's scope member).

    -
    Note: Scope is a simple string match
    • -
    Note

    +

    Note

    The above loop is guaranteed to return a value before the assertion, due to the fact that browser is in every mode's fallback chain, and the requirement that all user agents support @@ -3412,7 +3472,7 @@

    Web Application Manifest

    A user agent MUST reflect the applied display mode of the web application in the 'display-mode' media feature [MEDIAQUERIES-5].

    -
    Note

    +

    Note

    A user agent will expose the 'display-mode' media feature irrespective of whether a manifest is being applied to a browsing context. For example, if the end-user puts the application into @@ -3477,8 +3537,8 @@

    Web Application Manifest

    It is RECOMMENDED that UI that affords the end user the ability to - install a web application also allows inspecting the icon, name, - start URL, origin, etc. pertaining to a web application. This is + install a web application also allows inspecting the icon, name, + start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an @@ -3491,7 +3551,7 @@

    Web Application Manifest

    timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is - installed - or by using an entirely different cache from that + installed - or by using an entirely different cache from that used for regular web browsing.

    @@ -3696,7 +3756,7 @@

    Web Application Manifest

    There is only one class of product that can claim conformance to this specification: a user agent.

    -
    Note

    +

    Note

    Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, @@ -3917,7 +3977,7 @@

    Web Application Manifest

    the SchemaStore repository on GitHub.

    -
    Note: Web Manifest JSON Schema