- From: Evan Stade <notifications@github.com>
- Date: Fri, 17 Sep 2021 16:19:36 -0700
- To: w3c/manifest <manifest@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <w3c/manifest/pull/1005/review/757897907@github.com>
@evanstade requested changes on this pull request.
> @@ -1012,6 +1012,158 @@ <h3>
conventions or limitations of the host operating system.
</p>
</section>
+ <section>
+ <h3>
+ `file_handlers` member
+ </h3>
+ <p>
+ The [=manifest's=] <code><dfn data-export="" data-dfn-for=
+ "manifest">`file_handlers`</dfn></code> member is a [=list=] that
+ represents URLs within the app that handles launches of given [=file
s/handles/handle ?
Also, not sure how to best word this, but I might have written something along the lines of:
> The manifest's file_handers member is a list that provides instructions for how the app handles file-opening actions that originate outside of the app itself.
> @@ -1012,6 +1012,158 @@ <h3>
conventions or limitations of the host operating system.
</p>
</section>
+ <section>
+ <h3>
+ `file_handlers` member
+ </h3>
+ <p>
+ The [=manifest's=] <code><dfn data-export="" data-dfn-for=
+ "manifest">`file_handlers`</dfn></code> member is a [=list=] that
+ represents URLs within the app that handles launches of given [=file
+ types=].
+ </p>
+ <p>
+ A <dfn>file type</dfn> refers to file that has a [=mime type=] and/or
Maybe,
> A file type can be defined by a mime type and/or file name extension. A file belongs to a file type if the OS determines it to have a mime type and/or its name ends with a certain extension.
> + |json|["file_handlers"] is not a [=list=], return.
+ </li>
+ <li>[=list/For each=] |entry:ordered map| of |json|["file_handlers"]:
+ <ol>
+ <li>Let |file_handler:ordered map| be [=process a file handler
+ item=] with |entry|.
+ </li>
+ <li>If |file_handler| is failure, continue.
+ </li>
+ <li>[=list/Append=] |file_handler| to |processedFileHandlers|.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ On [=installation=], a user agent SHOULD register the file handlers
I'm not sure what the technical definition of SHOULD is. For example, on Linux some of these things don't happen, i.e. we don't intend to support iconography on Linux. Does that fit within the definition of SHOULD?
> + <li>[=file handler/action=]
+ </li>
+ <li>[=file handler/name=]
+ </li>
+ <li>[=file handler/accepts=]
+ </li>
+ <li>[=file handler/icons=]
+ </li>
+ </ul>
+ <p>
+ A user agent can use these members to associate the web application
+ with [=file type=] on the operating system.
+ </p>
+ <aside class="note">
+ <p>
+ The disambiguation of file handlers and selecting of default file
When I first read this, I thought by disambiguation of file handlers it meant which file handler specifically to use, if more than one applies. That's actually handled in the user agent. (Chrome code [here](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/web_applications/web_app_file_handler_manager.cc;l=292;drc=c4d0e9c06b437234e8fb297ce3273dad1891e8d4;bpv=1;bpt=1)) And may be something we want to discuss?
But I gather this actually means "selection among different apps registered as capable of handling files"
> + "file handler">action</dfn></code> member is a <a>string</a> that
+ represents a relative URL of the [=manifest/start_url=] origin that
+ is [=manifest/within scope=] of a [=Document/processed manifest=].
+ This URL will be navigated to in the steps to [=execute a file
+ handler launch=].
+ </p>
+ </section>
+ <section>
+ <h3>
+ `name` member
+ </h3>
+ <p>
+ The [=file handler's=] <code><dfn data-dfn-for=
+ "file handler">name</dfn></code> member is a <a>string</a> that
+ represents a name to be provided to the user's operating system for
+ use with "Open with..." UX flows. This MAY be replaced by the user
this is just one example of a place this could be used.
See, for example, how Linux uses it: crbug.com/1249217
> + represents a relative URL of the [=manifest/start_url=] origin that
+ is [=manifest/within scope=] of a [=Document/processed manifest=].
+ This URL will be navigated to in the steps to [=execute a file
+ handler launch=].
+ </p>
+ </section>
+ <section>
+ <h3>
+ `name` member
+ </h3>
+ <p>
+ The [=file handler's=] <code><dfn data-dfn-for=
+ "file handler">name</dfn></code> member is a <a>string</a> that
+ represents a name to be provided to the user's operating system for
+ use with "Open with..." UX flows. This MAY be replaced by the user
+ agent for privacy & security reasons.
I'm not aware of privacy/security issues with the name member, did you have particular issues in mind?
> @@ -1787,6 +1942,147 @@ <h2>
</ol>
</section>
</section>
+ <section>
+ <h2>
+ File Handler Items
+ </h2>
+ <p>
+ Each <dfn data-local-lt="file handler's">file handler</dfn> represents
+ a URL in the scope of the application that can handle launches with
+ [=file types=] it accepts. It has the following members:
+ </p>
+ <ul>
+ <li>[=file handler/action=]
+ </li>
+ <li>[=file handler/name=]
+ </li>
+ <li>[=file handler/accepts=]
nit: accept (here and several other places)
> + `accept` member
+ </h3>
+ <p>
+ The [=file handler's=] <code><dfn data-dfn-for=
+ "file handler">accept</dfn></code> member is a <a>dictionary</a>
+ mapping [=MIME types=] to a list of extensions. Extensions have to be
+ strings that start with a "." and only contain [=valid suffix code
+ points=]. Additionally extensions are limited to a length of 16 code
+ points.
+ </p>
+ <p>
+ In addition to complete MIME types, "*" can be used as the subtype of
+ a MIME type to match, for example, all image formats with "image/*".
+ </p>
+ <p>
+ Websites SHOULD always provide both [=MIME types=] and file
mime type is required
> + </p>
+ </section>
+ <section>
+ <h3>
+ `accept` member
+ </h3>
+ <p>
+ The [=file handler's=] <code><dfn data-dfn-for=
+ "file handler">accept</dfn></code> member is a <a>dictionary</a>
+ mapping [=MIME types=] to a list of extensions. Extensions have to be
+ strings that start with a "." and only contain [=valid suffix code
+ points=]. Additionally extensions are limited to a length of 16 code
+ points.
+ </p>
+ <p>
+ In addition to complete MIME types, "*" can be used as the subtype of
should we link to the definition of a parseable mime type?
Also, I don't think we want to handle mime type parameters, and it's worth noting that the type must be one of these: https://source.chromium.org/chromium/chromium/src/+/main:net/base/mime_util.cc;l=587-591?q=IsValidTopLevelMimeType&ss=chromium
> + Processing file handler items
+ </h2>
+ <p>
+ To <dfn>process a file handler item</dfn>, given [=ordered map=]
+ |item:ordered map|, [=URL=] |start_url:URL|, [=URL=] |scope:URL|, and
+ [=URL=] |manifest URL:URL|.
+ </p>
+ <ol class="algorithm">
+ <li>Return failure if it's the case that:
+ <ul>
+ <li>|item| is not [=ordered map=].
+ </li>
+ <li>|item|["action"] doesn't [=map/exist=] or is not a
+ [=string=].
+ </li>
+ <li>|item|["name"] doesn't [=map/exist=] or is the empty string.
name should be optional
> + <li>If |url| is failure, return failure.
+ </li>
+ <li>If |url| is not [=manifest/within scope=] of |scope|, return
+ failure.
+ </li>
+ <li>TODO - process "accepts"
+ </li>
+ <li>Let |file_handler:ordered map| be |ordered map| «[ "action" →
+ |url|, "name" → |item|["name"] ]».
+ </li>
+ <li>[=Process image resources=] passing |item|["icons"],
+ |file_handler|, |manifest URL|, and "icons".
+ </li>
+ <li>The user agent MAY replace |file_handler|["icons"] and
+ |file_handler|["name"] with the application icon and a string
+ containing the application name, respectively.
The user agent should not replace `name` with the application's name. It may fall back to something else, such as "\<Application name\> file", but the application name by itself is a bad fallback.
Also this fallback is more intended for a missing `name`; I don't think there's a reason to ever replace the name provided by the app.
> + </li>
+ </ol>
+ <p>
+ On [=installation=], a user agent SHOULD register the file handlers
+ with the operating system via interactions that are consistent with:
+ </p>
+ <ul>
+ <li>The [=file handler/icon=] and [=file handler/name=] appear in the
+ host operating system surfaces presenting options for opening files,
+ for example within "Open with..." context menus for associated file
+ types.
+ </li>
+ <li>The [=file handler/icon=] appears as the icon of associated files
+ in the host operating system.
+ </li>
+ <li>File types with multiple possible handlers can be disambiguated
I think instead of "disambiguated" I would choose a different word here.
The OS allows the user to *select* which app should open a file, and also allows the user to set a default app.
> + <p>
+ When a [=file type=] is registered with a web app and one or more
+ of these registered files are launched on the platform, run the
+ following steps, given the launched {{FrozenArray}} of
+ {{FileSystemHandle}}s |files:FrozenArray<FileSystemHandle>|
+ and the corresponding [=file handler|file_handler=].
+ </p>
+ <ol>
+ <li>Let |url| be the |file_handler|.[=file handler/action=].
+ </li>
+ <li>Let |browsing context| be the result of creating a new
+ [=top-level browsing context=].
+ </li>
+ <li>[=Navigate=] |browsing context| to |url|.
+ </li>
+ <li>XXX Wait for navigation to be complete?
We do wait for the navigation to "complete", whatever that means technically.
Currently we also have to wait for the user to approve the action (at least sometimes).
However, we're interested in changing this such that user approval, if any, occurs before the creation of the browsing context and subsequent navigation. This sidesteps concerns like what happens after a navigation has occurred, but the user has not allowed the open-file action. It sounds like you're describing this potential future improvement rather than the current state of Chrome. Is that accurate?
> + </li>
+ <li>Iterate through every {{LaunchConsumer}} set by
+ {{LaunchQueue/setConsumer}} and execute the function with |params|.
+ </li>
+ </ol>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Default [=file handler=].
+ </h3>
+ <p>
+ Depending on the operating system capabilities, the [=manifest/file
+ handler=] could become a 'default' handler (e.g. handling launches
+ of a given file type automatically) of a given [=file type=]
+ without the explicit knowledge of the user. To protect against
+ possible mis-use, user agents MAY choose to offer the user the
maybe,
> MAY require explicit user consent to proceed with the launch action when an app is launched by handling a file.
> + {{LaunchQueue/setConsumer}} and execute the function with |params|.
+ </li>
+ </ol>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Default [=file handler=].
+ </h3>
+ <p>
+ Depending on the operating system capabilities, the [=manifest/file
+ handler=] could become a 'default' handler (e.g. handling launches
+ of a given file type automatically) of a given [=file type=]
+ without the explicit knowledge of the user. To protect against
+ possible mis-use, user agents MAY choose to offer the user the
+ functionality to not launch the web application, or even unregister
+ a given file handler for a web application.
> If consent is denied, the user agent MAY remove the web application's OS registration as a file handling entity.
--
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/pull/1005#pullrequestreview-757897907
Received on Friday, 17 September 2021 23:19:50 UTC