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

fix(manifest): Update manifest member pages to follow the same format #35557

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

fix(manifest): Update manifest member pages to follow the same format #35557

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
21cb098
update to follow the same template
dipikabh Aug 22, 2024
efc79ea
update syntax
dipikabh Aug 22, 2024
71af715
Merge branch 'main' into manifest-sync-template
dipikabh Sep 3, 2024
4fc1702
update placeholder values
dipikabh Sep 4, 2024
beede57
update placeholder values
dipikabh Sep 4, 2024
e61783e
update placeholder values
dipikabh Sep 4, 2024
ad01be7
Merge branch 'main' into manifest-sync-template
dipikabh Sep 17, 2024
4efa5f0
remove syntax blocks
dipikabh Sep 17, 2024
2b6d13b
revert changes to files in other PRs
dipikabh Sep 17, 2024
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
17 changes: 8 additions & 9 deletions files/en-us/web/manifest/background_color/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,21 @@ browser-compat: html.manifest.background_color

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>String</code></td>
</tr>
</tbody>
</table>
The `background_color` member defines a placeholder background color for the application page to display before its stylesheet is loaded.

The `background_color` member defines a placeholder background color for the application page to display before its stylesheet is loaded. This value is used by the user agent to draw the background color of a shortcut when the manifest is available before the stylesheet has loaded.
This value is used by the user agent to draw the background color of a shortcut when the manifest is available before the stylesheet has loaded.

Therefore `background_color` should match the {{cssxref("background-color")}} CSS property in the site's stylesheet for a smooth transition between launching the web application and loading the site's content.

> [!NOTE]
> The `background_color` member is only meant to improve the user experience while the main stylesheet is loading from the network or the storage media; it is not used by the user agent as the {{cssxref("background-color")}} CSS property when the progressive web app stylesheet is available.

## Syntax

```json
"background_color": "colorValue"
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
```

## Examples

```json
Expand Down
19 changes: 9 additions & 10 deletions files/en-us/web/manifest/categories/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,21 @@ browser-compat: html.manifest.categories

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>Array</code> of <code>String</code>s</td>
</tr>
</tbody>
</table>
The `categories` member is an array of strings defining the names of categories that the application supposedly belongs to.

The `categories` member is an array of strings defining the names of categories that the application supposedly belongs to. There is no standard list of possible values, but the W3C maintains [a list of known categories](https://github.com/w3c/manifest/wiki/Categories).
There is no standard list of possible values, but the W3C maintains [a list of known categories](https://github.com/w3c/manifest/wiki/Categories).

> **Note:** `categories` are used only as hints for catalogs or stores listing web applications. Like search engines and meta keywords, catalogs and stores are free to ignore them.

> **Note:** `categories` values are lower-cased by the stores and catalogs before processing, so "News" and "news" are treated as the same value. Developers are encouraged to use lower case in the first place.

## Example
## Syntax

```json
"categories": ["category1", "category2", "category3"]
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
```

## Examples

```json
"categories": ["books", "education", "medical"]
Expand Down
4 changes: 2 additions & 2 deletions files/en-us/web/manifest/display/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ The `display` manifest member is used to specify your preferred display mode for
## Syntax

```json
"display": "standalone"
"display": "fullscreen" | "standalone" | "minimal-ui" | "browser"
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
```

### Values

The value of the `display` member is a string. The possible values include `fullscreen`, `standalone`, `minimal-ui`, and `browser`. If a browser does not support the specified display mode, it follows a pre-defined fallback chain: `fullscreen` → `standalone` → `minimal-ui` → `browser`. If `display` is not specified, the default value `browser` is used.
The value of the `display` member is a string that can take one of the following values, listed in the order of fallback if a browser does not support the specified mode:

- `fullscreen`

Expand Down
109 changes: 38 additions & 71 deletions files/en-us/web/manifest/display_override/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,84 +9,51 @@ browser-compat: html.manifest.display_override

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>Array</code></td>
</tr>
</tbody>
</table>

The [`display`](/en-US/docs/Web/Manifest/display) member is used to determine the developer's preferred display mode for a website. It follows a process where the browser falls back to the next display mode if the requested one is not supported. In some advanced use cases, this fallback process might not be enough.

The `display_override` member solves this by letting the developer provide a sequence of display modes that the browser will consider before using the `display` member. Its value is an array of display modes that are considered in-order, and the first supported display mode is applied.

## Values
## Syntax

```json
"display_override": ["modeKeyword1", "modeKeyword2", "modeKeyword3"]
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
```

### Values

Display override objects are display-mode strings, the possible values are:

<table class="fullwidth-table standard-table">
<thead>
<tr>
<th scope="col">Display Mode</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>browser</code></td>
<td>
The application opens in a conventional browser tab or new window,
depending on the browser and platform. This is the default.
</td>
</tr>
<tr>
<td><code>fullscreen</code></td>
<td>
All of the available display area is used and no user agent
{{Glossary("chrome")}} is shown.
</td>
</tr>
<tr>
<td><code>minimal-ui</code></td>
<td>
The application will look and feel like a standalone application with
a minimal set of UI elements for controlling navigation. The
elements will vary by browser.
</td>
</tr>
<tr>
<td><code>standalone</code></td>
<td>
The application will look and feel like a standalone application. This
can include the application having a different window, its own icon in
the application launcher, etc. In this mode, the user agent will exclude
UI elements for controlling navigation, but can include other UI
elements such as a status bar.
</td>
</tr>
<tr>
<td><code>tabbed</code></td>
<td>
The application can contain multiple application contexts inside a single OS-level window. Supporting browsers can choose how to display these contexts, but a common approach is to provide a tab bar to switch between them.
</td>
</tr>
<tr>
<td><code>window-controls-overlay</code></td>
<td>
This display mode only applies when the application is in a separate PWA
window and on a desktop operating system. The application will opt-in to
the Window Controls Overlay feature, where the full window surface area
will be available for the app's web content and the window control buttons
(maximize, minimize, close, and other PWA-specific buttons) will appear
as an overlay above the web content.
</td>
</tr>
</tbody>
</table>

## Example
- `browser`

- : The application opens in a conventional browser tab or new window, depending on the browser and platform.
This is the default.

- `fullscreen`

- : All of the available display area is used and no user agent {{Glossary("chrome")}} is shown.

- `minimal-ui`

- : The application will look and feel like a standalone application with a minimal set of UI elements for controlling navigation.
The elements will vary by browser.

- `standalone`

- : The application will look and feel like a standalone application.
This can include the application having a different window, its own icon in the application launcher, etc.
In this mode, the user agent will exclude UI elements for controlling navigation, but can include other UI elements such as a status bar.

- `tabbed`

- : The application can contain multiple application contexts inside a single OS-level window.
Supporting browsers can choose how to display these contexts, but a common approach is to provide a tab bar to switch between them.

- `window-controls-overlay`

- : This display mode only applies when the application is in a separate PWA window and on a desktop operating system.
The application will opt-in to the Window Controls Overlay feature, where the full window surface area will be available for the app's web content and the window control buttons (maximize, minimize, close, and other PWA-specific buttons) will appear as an overlay above the web content.

## Examples

In the example below, the browser will consider the following display-mode fallback chain in this order: `fullscreen` → `minimal-ui` → `standalone`.

Expand Down
66 changes: 27 additions & 39 deletions files/en-us/web/manifest/file_handlers/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,6 @@ browser-compat: html.manifest.file_handlers

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>Array</code></td>
</tr>
</tbody>
</table>

The `file_handlers` member specifies an array of objects representing the types of files an installed [progressive web app (PWA)](/en-US/docs/Web/Progressive_web_apps) can handle.

The `file_handlers` member is read by the browser when the PWA is installed and used to associate the application with a given set of file types at the operating system level.
Expand All @@ -27,39 +18,36 @@ For example, a PWA can be registered to handle files that match the `text/plain`
> [!NOTE]
> While the `file_handlers` member is used to register a PWA with a given set of file types, this only results in the operating system launching the PWA when a matching file is opened. The PWA then needs to actually handle the file using JavaScript code. See [Handling the files](#handling_the_files) for more information.

## Values
## Syntax

```json
"file_handlers": [
{
"action": "actionURL",
"accept": {
"mimeType1": ["fileExtension1", "fileExtension2"],
"mimeType2": ["fileExtension3", "fileExtension4"]
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
}
}
]
```

### Values

An array of objects. Each object in the array must contain the following values (`action` and `accept` are required):

<table class="fullwidth-table standard-table">
<thead>
<tr>
<th scope="col">Member</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>action</code></td>
<td>
A string containing the URL to navigate to when a file is handled.<br>
This URL must be within the navigation scope of the PWA, which is the set of URLs that the PWA can navigate to. The navigation scope of a PWA defaults to its <a href="/en-US/docs/Web/Manifest/start_url"><code>start_url</code></a> member, but can also be defined by using the <a href="/en-US/docs/Web/Manifest/scope"><code>scope</code></a> member.
</td>
</tr>
<tr>
<td><code>accept</code></td>
<td>
An object. For each property in the object:
<ul>
<li>The property key is a MIME type.</li>
<li>The property value is an array of strings representing file extensions associated with that MIME type.</li>
</ul>
</td>
</tr>
</tbody>
</table>

## Example
- `action`

- : A string containing the URL to navigate to when a file is handled.
This URL must be within the navigation scope of the PWA, which is the set of URLs that the PWA can navigate to. The navigation scope of a PWA defaults to its [`start_url`](/en-US/docs/Web/Manifest/start_url) member, but can also be defined by using the [`scope`](/en-US/docs/Web/Manifest/scope) member.

- `accept`

- : An object. For each property in the object:
- The property key is a MIME type.
- The property value is an array of strings representing file extensions associated with that MIME type.

## Examples

In this example, a web app manifest declares one file handler that registers the app to handle audio files. Other manifest members such as `name`, or `icons` are not included in this example for brevity:

Expand Down
15 changes: 6 additions & 9 deletions files/en-us/web/manifest/id/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,6 @@ browser-compat: html.manifest.id

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>String</code></td>
</tr>
</tbody>
</table>

The `id` member is a string that represents the _identity of the web application_ — the unique identifier for the web application. If the web application ID does not match an existing ID, the application will be treated as a unique identity even if it is from the same URL.

A valid `id` needs to be same-origin with `start_url`. If the `id` is a relative URL, it is resolved using the origin of [`start_url`](/en-US/docs/Web/Manifest/start_url). The fragment is always ignored.
Expand All @@ -25,6 +16,12 @@ If the `id` is unspecified or invalid in any way (such as not a string, not a va
> [!NOTE]
> The `id` member can be used to uniquely identify applications. The `id` member is processed like a `start_url` but can be out of [scope](/en-US/docs/Web/Manifest/scope) because it does not point to a resource that can be navigated to.

## Syntax

```json
"id": "identifierString"
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
```

## Examples

```json
Expand Down
56 changes: 21 additions & 35 deletions files/en-us/web/manifest/launch_handler/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,46 +9,32 @@ browser-compat: html.manifest.launch_handler

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>Object</code></td>
</tr>
</tbody>
</table>

The `launch_handler` member defines values that control the launch of a web application. Currently it can only contain a single value, `client_mode`, which specifies the context in which the app should be loaded when launched. For example, in an existing web app client containing an instance of the app, or in a new web app client. This leaves scope for more `launch_handler` values to be defined in the future.

## launch_handler item values
## Syntax

```json
"launch_handler": {
"client_mode": ["contextKeyword1", "contextKeyword2", "contextKeyword3"]
dipikabh marked this conversation as resolved.
Show resolved Hide resolved
}
```

### Values

`launch_handler` objects may contain the following values:

<table class="fullwidth-table standard-table">
<thead>
<tr>
<th scope="col">Member</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>client_mode</code></td>
<td><p>A string, or comma-separated array of strings, which specifies the context in which the app should be loaded when launched. If an array of strings is provided, the first valid value is used. Possible values are:</p>
<dl>
<dt><code>auto</code></dt>
<dd>The user agent decides what context makes sense for the platform to load the app in. For example, <code>navigate-existing</code> might make more sense on mobile, where single app instances are commonplace, whereas <code>navigate-new</code> might make more sense in a desktop context. This is the default value used if all the provided values are invalid.</dd>
<dt><code>focus-existing</code></dt>
<dd>If the app is already loaded in a web app client, it is brought into focus but not navigated to the launch target URL. The target URL is made available via {{domxref("Window.launchQueue")}} to allow custom launch navigation handling to be implemented. If the app is not already loaded in a web app client, <code>navigate-new</code> behavior is used instead.</dd>
<dt><code>navigate-existing</code></dt>
<dd>If the app is already loaded in a web app client, it is brought into focus and navigated to the specified launch target URL. The target URL is made available via {{domxref("Window.launchQueue")}} to allow additional custom launch navigation handling to be implemented. If the app is not already loaded in a web app client, <code>navigate-new</code> behavior is used instead.</dd>
<dt><code>navigate-new</code></dt>
<dd>The app is loaded inside a new web app client. The target URL is made available via {{domxref("Window.launchQueue")}} to allow additional custom launch navigation handling to be implemented.</dd>
</dl>
</td>
</tr>
</tbody>
</table>
- `client_mode`

- : A string, or comma-separated array of strings, which specifies the context in which the app should be loaded when launched. If an array of strings is provided, the first valid value is used.
Possible values are:</p>
- `auto`
- : The user agent decides what context makes sense for the platform to load the app in. For example, `navigate-existing` might make more sense on mobile, where single app instances are commonplace, whereas `navigate-new` might make more sense in a desktop context. This is the default value used if all the provided values are invalid.
- `focus-existing`
- : If the app is already loaded in a web app client, it is brought into focus but not navigated to the launch target URL. The target URL is made available via {{domxref("Window.launchQueue")}} to allow custom launch navigation handling to be implemented. If the app is not already loaded in a web app client, `navigate-new` behavior is used instead.
- `navigate-existing`
- : If the app is already loaded in a web app client, it is brought into focus and navigated to the specified launch target URL. The target URL is made available via {{domxref("Window.launchQueue")}} to allow additional custom launch navigation handling to be implemented. If the app is not already loaded in a web app client, `navigate-new` behavior is used instead.
- `navigate-new`
- : The app is loaded inside a new web app client. The target URL is made available via {{domxref("Window.launchQueue")}} to allow additional custom launch navigation handling to be implemented.

## Examples

Expand Down
Loading