Note Taking: New Note URL field

[phoglenix]

Kia Ora TAG!

I'm requesting a TAG review of note_taking: { new_note_url }, fields being added to the web app manifest.

eg. manifest.json

{
  "name": "My Note Taking App",
  "start_url": "/index.html",
  "note_taking": {
    "new_note_url": "/new_note.html"
  }
}

Web apps lack a semantic way of declaring and defining note-taking capabilities. This specification adds a new note_taking object member to the web app manifest, where note-taking capabilities can be added. It also adds the first such note-taking capability: a new_note_url field in the note_taking object: a URL within scope that can be used to launch the web app in order to take a new note.

• Explainer: https://github.com/WICG/manifest-incubations/blob/gh-pages/note_taking-explainer.md
• Specification URL: https://wicg.github.io/manifest-incubations/index.html#note_taking-member
• Tests: None in WPT yet
• Security and Privacy self-review: Minimal security/privacy effects: if a UA+user chooses to launch the new_note_url then the site can know that the URL was loaded. Identical to loading the URL normally.
• GitHub repo: https://github.com/WICG/manifest-incubations
• Primary contacts (and their relationship to the specification):
  • Glen Robertson (phoglenix), Google Inc
  • Matt Giuca (mgiuca), Google Inc
• Organization(s)/project(s) driving the specification: Google Inc
• Key pieces of existing multi-stakeholder review or discussion of this specification: Add field: note_taking { new_note_url: <URL> } w3c/manifest#965
• External status/issue trackers for this specification: https://chromestatus.com/feature/5205972320518144

Further details:

• ✓ I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: targeting M93 (branching 15 July)
• The group where the work on this specification is currently being done: https://github.com/WICG/manifest-incubations
• The group where standardization of this work is intended to be done: https://github.com/WICG/manifest-incubations
• Major unresolved issues with or opposition to this specification: None
• This work is being funded by: Google Inc

We'd prefer the TAG provide feedback as:
🐛 open issues in our GitHub repo for each point of feedback and @-notify phoglenix

[phoglenix]

Hi there, I see this was in a milestone for last week. Was it discussed at all?

[kenchris]

Explainer: none(!). Seemed like overkill.

I never really think that is overkill. On the other hand this feature feels quite specific and could mean an inflow of similar specific features so I definitely think that an explainer is in place that explains why this warrants a special manifest entry?

Also, I assume that note taking might differ from where it is instantiated within a site or single page app, so how can people do that? Is any state send to the new page (like with web share target) or maybe this makes more sense as a meta tag that can be changed, or replaced per subpage? Such things could be discussed in an explainer.

[phoglenix]

Thanks for the reply.

I've put together a draft explainer here (now in review). It's mostly just the discussion on w3c/manifest#965 that tries to clarify the pros and cons of doing something general vs specific.

The URL is launched in the same way as the start_url, so it is controlled by the existing display settings in the manifest. No extra state/data is sent with the request, but it would be simple to add that later. I have noted these points in the explainer.

[kenchris]

Thanks! Hope we get to look at this soon, but expect delays as people in Europe are starting to go on vacation

[torgo]

Thanks for the explainer @phoglenix! I've put it on the agenda for next week. @marcoscaceres what is the trajectory for manifest incubations like this? Do they eventually become manifest extensions in webapps?

[atanassov]

Hi @phoglenix we took another look at this proposal today.

I hope we have the right explainer linked above. The one you posted was already missing.

Reading through that explainer was hard to understand what the user needs are and how/why this capability will address them. Can you elaborate on these and ideally add them directly into your explainer?

[tomayac]

I tried to summarize the user benefit in a tweet. Maybe it is clearer then?

[phoglenix]

Sorry, the PR for the explainer was merged into manifest-incubations. You found the correct one.

Yes, as @tomayac summarized, the user benefit is tighter (any, really) OS or UA integrations with the note-taking web app. With the current fields the UA can know "this is a note-taking app" and "this is the URL tocreate a new note in the note taking app". What they do with those fields is up to the UA, but possible examples are given at the top of the explainer: the note-taking app could be launched from keyboard shortcuts, OS buttons/tray, customisable keyboard keys, voice assistants. These launcher surfaces exist already, they just do not currently support web apps.

As a concrete example, on Chrome OS note-taking web apps will be shown in the OS stylus tools settings alongside other note-taking apps, can be selected there as the main note-taking app, and then a new note can be created from the stylus tools palette (which launches the new_note_url).

I'll update the explainer with a little more about the user needs / benefit.

[phoglenix]

Hi, are you waiting on me for anything here? I have updated the explainer as mentioned above.

[kenchris]

Thanks for the explainer. Looking at the future considerations section, I am wondering whether this is flexible enough. Why does creating a new note have to result in a URL change? I could imagine a canvas app, where I would just add a graphical overlay (post it notes) on top. Could this be a global event instead where you give the options (including future ones) as part of the event details? It doesn't look like you considered this. We would like to hear your thoughts on this.

[phoglenix]

The API actually serves two (closely-related) purposes: it provides a way for an app to be launched to take a note, and it provides a way for an app to declare its capability as a note-taking app. I don't think an event covers either of these two cases quite as well, or it would need to be paired with a manifest field anyway to declare these capabilities (which seems more complex and error-prone).

Launching:
Opening a URL is a natural way to launch a web app from outside the app (the UA or OS), especially as the app may not be running. An event would need to first launch the app (to the Start URL?), or perhaps find an existing app window, then fire the event at it. What if the app wants to customise this behaviour? This sounds like an entire new spec, and indeed it is: Declarative Link Capturing. I believe an app could use Declarative Link Capturing (specifically "existing-client-event" mode) to achieve the behaviour you mention (and multiple other variations) without complicating this spec.

Declaring Capabilities:
Unlike an event registration, the New Note URL is known as soon as the manifest is parsed, and relatively fixed, so it is clear to the UA when a given app is / isn't self-identifying as a note-taking app.
If new functionality is added to the New Note URL in the future, these could be added with explicit parameters or another URL declared in the manifest, which again acts as a declaration of capabilities. By contrast, an event could be very flexible with a dictionary of parameters passed in, but unless a different event listener is registered, the UA cannot know whether particular parameters are handled (which could be important, eg. take a note with text - you really don't want the extra text parameter to just be dropped).

So I believe the URL declared in the manifest is a better approach. If that sounds reasonable to you I'll update the explainer to mention these points.

[kenchris]

@phoglenix that is a lot of good content, makes a lot of sense. Do you mind to add some of this to the explainer?

[phoglenix]

Will do!

[phoglenix]

Done

[atanassov]

@kenchris and I looked at this again during our Gethen vf2f. Given that all comments and feedback has been addressed we are happy to close the review as satisfied. Thank you for working with us and good luck.