Adding User Preferences #57
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -495,6 +495,288 @@ <h2> | |||||
| </p> | ||||||
| </section> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h2> | ||||||
| <code><dfn>user_preferences</dfn></code> member | ||||||
| </h2> | ||||||
| <p> | ||||||
| The `user_preferences` member of the [=application manifest=] is an | ||||||
| object that can be used to override values of manfiest members depending | ||||||
| on which user preferences are set. It has the following members: | ||||||
| </p> | ||||||
| <ul> | ||||||
| <li>[=user_preferences/color_scheme=] | ||||||
|
There was a problem hiding this comment. I've added it as a note for now - happy to instead add it to the list if you prefer. I guess it'll need its own section if I add it to the list. Would we just want There was a problem hiding this comment. I dig the note. |
||||||
| </li> | ||||||
| </ul> | ||||||
| <p class="note"> | ||||||
| This list of members is expected to expand in the future to include | ||||||
| other <a data-cite="mediaqueries-5/#mf-user-preferences">user | ||||||
|
There was a problem hiding this comment. Try to avoid hard links ( Also, please avoid link to complete sections in the CSS spec. If we need to share concepts, we should try to specify that. |
||||||
| preference media features</a> such as <a data-cite= | ||||||
| "mediaqueries-5/#prefers-contrast">contrast</a> and | ||||||
| <a data-cite="mediaqueries-5/#forced-colors">forced-colors</a>, | ||||||
| as defined in CSS. | ||||||
| </p> | ||||||
| <p> | ||||||
| The user agent SHOULD use the override values instead of the value of | ||||||
| the corresponding member defined at the top level of the manifest. | ||||||
| </p> | ||||||
| <p> | ||||||
| To <dfn>process the `user_preferences` member</dfn>, given | ||||||
| [=ordered map=] |json:ordered_map|, [=ordered map=] |manifest:ordered map|, | ||||||
| run the following during the [=application manifest/processing | ||||||
| extension-point=] in [=processing a manifest=]: | ||||||
| </p> | ||||||
| <ol class="algorithm"> | ||||||
| <li>If |json|["user_preferences"] does not [=map/exist=], return. | ||||||
|
There was a problem hiding this comment. This should happen in the main processing steps. |
||||||
| </li> | ||||||
| <li>If the type of |json|["user_preferences"] is not [=ordered map=], | ||||||
| return. | ||||||
| </li> | ||||||
| <li>Set |manifest|["user_preferences"] to a new [=ordered map=]. | ||||||
| </li> | ||||||
| <li>[=Process the `color_scheme` member=] passing | ||||||
| |json|["user_preferences"] and |manifest|["user_preferences"]. | ||||||
| </li> | ||||||
| </ol> | ||||||
| <section> | ||||||
| <h3> | ||||||
| <code><dfn data-dfn-for="user_preferences">color_scheme</dfn></code> | ||||||
| member | ||||||
| </h3> | ||||||
| <p> | ||||||
| The [=user_preferences=] `color_scheme` member is an object that | ||||||
| contains the overrides for color scheme preferences. It has the | ||||||
| following members: | ||||||
| </p> | ||||||
| <p> | ||||||
| The <code><dfn data-dfn-for="color_scheme">dark</dfn></code> member | ||||||
| specifies the manifest overrides to use when the user prefers a | ||||||
| dark theme. | ||||||
| </p> | ||||||
| <p> | ||||||
| The <code><dfn data-dfn-for="color_scheme">light</dfn></code> member | ||||||
| specifies the manifest overrides to use when the user prefers a | ||||||
| light theme. | ||||||
| </p> | ||||||
| <p> | ||||||
| To <dfn>process the `color_scheme` member</dfn>, given [=ordered map=] | ||||||
| |json_user_preferences:ordered_map|, [=ordered map=] | ||||||
| |manifest_user_preferences:ordered map|, run the following: | ||||||
| </p> | ||||||
| <ol class="algorithm"> | ||||||
| <li>If |json_user_preferences|["color_scheme"] does not [=map/exist=], | ||||||
| return. | ||||||
| </li> | ||||||
| <li>If the type of |json_user_preferences|["color_scheme"] is not | ||||||
| [=ordered map=], return. | ||||||
| </li> | ||||||
| <li>Set |manifest_user_preferences|["color_scheme"] to a new | ||||||
| [=ordered map=]. | ||||||
| </li> | ||||||
| <li>[=list/For each=] |member:string| of [=list=] « "dark", "light" »: | ||||||
| <ol> | ||||||
| <li>Let |overrides:ordered map| be the result of processing a | ||||||
| manifest override object. | ||||||
| </li> | ||||||
| <li>Set |manifest_user_preferences|["color_scheme"][|member:string|] | ||||||
| to |overrides|. | ||||||
| </li> | ||||||
| </ol> | ||||||
| </li> | ||||||
| </ol> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| Overridable properties | ||||||
| </h3> | ||||||
| <p> | ||||||
| The proterties that [=user_preferences=] can override in the | ||||||
| [=manifest override object=] are: | ||||||
| </p> | ||||||
| <ul> | ||||||
| <li>[=manifest/theme_color=] member. | ||||||
| </li> | ||||||
| <li>[=manifest/background_color=] member. | ||||||
| </li> | ||||||
| <li><a data-cite="appmanifest/#shortcut-items">Shortcut item's</a> | ||||||
| <a data-cite="appmanifest#icons-member-0">icons</a> | ||||||
| <a data-cite="image-resource/#dfn-src">src</a> member. | ||||||
| </li> | ||||||
| <li><a data-cite="appmanifest/#shortcut-items">Shortcut item's</a> | ||||||
| <a data-cite="appmanifest#icons-member-0">icons</a> | ||||||
| <a data-cite="image-resource/#dfn-type">type</a> member. | ||||||
| </li> | ||||||
| <li>[=manifest/icons=] <a data-cite= | ||||||
| "image-resource/#dfn-src">src</a> member. | ||||||
| </li> | ||||||
| <li>[=manifest/icons=] <a data-cite= | ||||||
| "image-resource/#dfn-type">type</a> member. | ||||||
| </li> | ||||||
| </ul> | ||||||
| </section> | ||||||
| </section> | ||||||
| <section data-cite="image-resource"> | ||||||
| <h2> | ||||||
| Manifest override objects | ||||||
| </h2> | ||||||
| <p> | ||||||
| Each <dfn>manifest override object</dfn> is a generic object value | ||||||
| that allows for certain manifest properties to be overridden within | ||||||
| a particular context. | ||||||
| </p> | ||||||
| <p>The structure of a [=manifest override object=] is as follows:</p> | ||||||
| <pre class="json"> | ||||||
| { | ||||||
| "context_key": { | ||||||
| "property": "new value" | ||||||
| } | ||||||
| } | ||||||
| </pre> | ||||||
| <p> | ||||||
| Each manifest property that accepts a [=manifest override object=] | ||||||
| as its value will define the contexts it supports and which | ||||||
| properties it supports overriding. User agents MUST ignore any contexts | ||||||
| that are not supported by the property as well as any override | ||||||
| properties not explicitly allowed within it. | ||||||
| </p> | ||||||
| <p> | ||||||
| When the manifest property’s context is applicable, the value of each | ||||||
| allowable override will be used in place of the original value defined | ||||||
| in the Manifest. | ||||||
| </p> | ||||||
| <p> | ||||||
| Redefined array items will be overridden in the order they are authored. | ||||||
| When redefining objects (e.g., [=manifest/shortcuts=], [=manifest/icons=]), | ||||||
| authors will only be able to redefine specific properties of that object. | ||||||
| In order to ensure all overrides are applied correctly, the order must | ||||||
| match the original array (i.e., each [=manifest/shortcut=] must be redefined | ||||||
| in order, as must their icons, if they also require re-definition). | ||||||
| </p> | ||||||
| Redefined array items must also be equal in number to the array being | ||||||
| overridden. If there is a mismatch in the number of items in either array, | ||||||
| any excess items will be ignored. This is only an issue if the original | ||||||
| array has more items than the override array, because any excess items | ||||||
| within the original array will not be re-defined. | ||||||
| </p> | ||||||
| <p> | ||||||
| When there is a conflict because two different properties are attempting | ||||||
| to override the same value in their respective active contexts, the one | ||||||
| defined last will win. By way of example, consider the following: | ||||||
| </p> | ||||||
| <pre class="json"> | ||||||
| { | ||||||
| "lang": "en-US", | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon.png", | ||||||
| "sizes": "128x128", | ||||||
| "type": "image/png" | ||||||
| } | ||||||
| ], | ||||||
| "translations": { | ||||||
| "es": { | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon-es.png" | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| }, | ||||||
| "user_preferences": { | ||||||
| "color_scheme": { | ||||||
| "dark": { | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon-dark.png" | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| </pre> | ||||||
| <p> | ||||||
| In this example, if the user’s primary language is Español, but | ||||||
| their preferred color scheme was set to "dark", the icon supplied | ||||||
| would be the dark version and not the localized one. For this reason, | ||||||
| it is imperative that properties taking a [=manifest override object=] | ||||||
| as their value consider whether any other properties that also enable | ||||||
| overrides should be able to be redefined within them. In the above | ||||||
| example, the author’s intent would likely have been better realized | ||||||
| if `user_preferences` was put before `translations` and the localized | ||||||
| context block redefined the `user_preferences` value for that language: | ||||||
| </p> | ||||||
| <pre class="json"> | ||||||
| { | ||||||
| "lang": "en-US", | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon.png", | ||||||
| "sizes": "128x128", | ||||||
| "type": "image/png" | ||||||
| } | ||||||
| ], | ||||||
| "user_preferences": { | ||||||
| "color_scheme": { | ||||||
| "dark": { | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon-dark.png" | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "translations": { | ||||||
| "es": { | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon-es.png" | ||||||
| } | ||||||
| ], | ||||||
| "user_preferences": { | ||||||
| "color_scheme": { | ||||||
| "dark": { | ||||||
| "icons": [ | ||||||
| { | ||||||
| "src": "icon-es-dark.png" | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
|
|
||||||
| } | ||||||
| </pre> | ||||||
| <p> | ||||||
| User agents MAY ignore any override properties they do not support. | ||||||
| </p> | ||||||
| <p> | ||||||
| To <dfn>apply a manifest override object</dfn>, given [=ordered_map=] | ||||||
| |overrides:json|, [=ordered map=] | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| |manifest:ordered map|, and [=array=] |allowed_properties:array| run the following: | ||||||
| </p> | ||||||
| <ol class="algorithm"> | ||||||
| <li>Let |allowed_overrides| be a new [=ordered map=]. | ||||||
| </li> | ||||||
| <li>[=list/For each=] |member:string| of |overrides|: | ||||||
| <ol> | ||||||
| <li>If |member| is not in |allowed_properties|, continue. | ||||||
| </li> | ||||||
| <li>Set |allowed_overrides|[|member|] to |overrides[|member|]|. | ||||||
| </li> | ||||||
| </ol> | ||||||
| </li> | ||||||
| <li>Let |overriden_manifest| be the result of creating a new [=ordered map=] | ||||||
|
There was a problem hiding this comment. @marcoscaceres I’m not sure the best way to express this, but in JavaScript it would be merging the objects using the spread operator: let overriden_manifest = {
…manifest,
…allowed_overrides
};There was a problem hiding this comment. See map/iterate ... something like:
Should do it. There was a problem hiding this comment. I don’t think that handles nested objects as neatly as spread, but I should be able to recursively call it if the value is an object. |
||||||
| by merging |manifest| with |allowed_overrides|. | ||||||
| </li> | ||||||
| <li> | ||||||
| Set |manifest| to |overriden_manifest|. | ||||||
| </li> | ||||||
| </ol> | ||||||
| </section> | ||||||
| <section data-cite="DOM"> | ||||||
| <h2> | ||||||
| Installation prompts | ||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For:
We should check the language that CSS uses for this, as it's not clear what "user preferences" means.