diff --git a/files/en-us/web/manifest/background_color/index.md b/files/en-us/web/manifest/background_color/index.md index 538a92bb0cf0aa9..573ba05871541b5 100644 --- a/files/en-us/web/manifest/background_color/index.md +++ b/files/en-us/web/manifest/background_color/index.md @@ -7,16 +7,9 @@ browser-compat: html.manifest.background_color {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeString
- -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. +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. 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. diff --git a/files/en-us/web/manifest/categories/index.md b/files/en-us/web/manifest/categories/index.md index b932c30d5865d6b..c9bdcf45ab635ae 100644 --- a/files/en-us/web/manifest/categories/index.md +++ b/files/en-us/web/manifest/categories/index.md @@ -7,22 +7,15 @@ browser-compat: html.manifest.categories {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeArray of Strings
+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 +## Examples ```json "categories": ["books", "education", "medical"] diff --git a/files/en-us/web/manifest/description/index.md b/files/en-us/web/manifest/description/index.md index 59146e16545a9ab..d8e6923754827fe 100644 --- a/files/en-us/web/manifest/description/index.md +++ b/files/en-us/web/manifest/description/index.md @@ -7,15 +7,6 @@ browser-compat: html.manifest.description {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeString
- The `description` member is a string in which developers can explain what the application does. `description` is directionality-capable, which means it can be displayed left to right or right to left based on the values of the [`dir`](/en-US/docs/Web/Manifest) and [`lang`](/en-US/docs/Web/Manifest) manifest members. ## Examples diff --git a/files/en-us/web/manifest/display_override/index.md b/files/en-us/web/manifest/display_override/index.md index 7b246b2f93c5686..d35e776dfe823c2 100644 --- a/files/en-us/web/manifest/display_override/index.md +++ b/files/en-us/web/manifest/display_override/index.md @@ -9,84 +9,45 @@ browser-compat: html.manifest.display_override {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}} - - - - - - - -
TypeArray
- 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 +### Values Display override objects are display-mode strings, the possible values are: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Display ModeDescription
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. -
- -## 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`. diff --git a/files/en-us/web/manifest/file_handlers/index.md b/files/en-us/web/manifest/file_handlers/index.md index 00661b280234ab6..e876d3fe49b4419 100644 --- a/files/en-us/web/manifest/file_handlers/index.md +++ b/files/en-us/web/manifest/file_handlers/index.md @@ -9,15 +9,6 @@ browser-compat: html.manifest.file_handlers {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}} - - - - - - - -
TypeArray
- 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. @@ -27,39 +18,22 @@ 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 +### Values An array of objects. Each object in the array must contain the following values (`action` and `accept` are required): - - - - - - - - - - - - - - - - - -
MemberDescription
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 member, but can also be defined by using the 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.
    • -
-
- -## 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: diff --git a/files/en-us/web/manifest/id/index.md b/files/en-us/web/manifest/id/index.md index aa0e51f26d4b260..4acee02da8fc468 100644 --- a/files/en-us/web/manifest/id/index.md +++ b/files/en-us/web/manifest/id/index.md @@ -7,15 +7,6 @@ browser-compat: html.manifest.id {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeString
- 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. diff --git a/files/en-us/web/manifest/launch_handler/index.md b/files/en-us/web/manifest/launch_handler/index.md index 2c3392bd4774865..be85551a2c63433 100644 --- a/files/en-us/web/manifest/launch_handler/index.md +++ b/files/en-us/web/manifest/launch_handler/index.md @@ -9,46 +9,24 @@ browser-compat: html.manifest.launch_handler {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}} - - - - - - - -
TypeObject
- 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 +### Values `launch_handler` objects may contain the following values: - - - - - - - - - - - - - -
MemberDescription
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:

-
-
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.
-
-
+- `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:

+ - `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 diff --git a/files/en-us/web/manifest/orientation/index.md b/files/en-us/web/manifest/orientation/index.md index 501889a2eb6d176..9c1b47059bad85a 100644 --- a/files/en-us/web/manifest/orientation/index.md +++ b/files/en-us/web/manifest/orientation/index.md @@ -7,15 +7,6 @@ browser-compat: html.manifest.orientation {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeString
- The `orientation` member defines the default orientation for all the website's top-level {{Glossary("Browsing context", "browsing contexts")}}. > **Note:** `orientation` and/or its specific values might not be supported by a user agent on various display modes because supporting them does not make sense for the particular context. @@ -23,7 +14,7 @@ The `orientation` member defines the default orientation for all the website's t > [!NOTE] > The orientation can be changed at runtime via the [Screen Orientation API](/en-US/docs/Web/API/Screen_Orientation_API). -## Values +### Values `orientation` can take one of the following values: diff --git a/files/en-us/web/manifest/protocol_handlers/index.md b/files/en-us/web/manifest/protocol_handlers/index.md index 338e6c1b482f149..5eb32650ed84fa8 100644 --- a/files/en-us/web/manifest/protocol_handlers/index.md +++ b/files/en-us/web/manifest/protocol_handlers/index.md @@ -9,20 +9,25 @@ browser-compat: html.manifest.protocol_handlers {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}} - - - - - - - -
TypeArray
- The `protocol_handlers` member specifies an array of objects that are protocols which this web app can register and handle. Protocol handlers register the application in an OS's application preferences; the registration associates a specific application with the given protocol scheme. For example, when using the protocol handler `mailto://` on a web page, registered email applications open. After registering a web app as a protocol handler, when a user clicks on a hyperlink with a specific scheme such as `mailto://` or `web+music://` from a browser or native app, the registered PWA would open and receive the URL. -## Example +### Values + +Protocol handlers objects may contain the following values: + +- `protocol` + + - : A required string containing the protocol to be handled; e.g.: `mailto`, `ms-word`, `web+jngl`. + +- `url` + - : Required HTTPS URL within the application [`scope`](/en-US/docs/Web/Manifest/scope) that will handle the + protocol. + The `%s` token will be replaced by the URL starting with the protocol handler's scheme. If `url` is a relative + URL, the base URL will be the URL of the manifest. + +## Examples In this example, a web app manifest declares that the app should be registered to handle the protocols `web+jngl` and `web+jnglstore`. @@ -43,38 +48,6 @@ A developer can add a field in the manifest.json to declare which protocols the Registering applications to handle URL schemes is operating-system dependent. This association is usually done during application install but it can also be done afterwards from an app that has already been installed. -## Values - -Protocol handlers objects may contain the following values: - - - - - - - - - - - - - - - - - - -
MemberDescription
protocol - A required string containing the protocol to be handled; e.g.: - mailto, ms-word, web+jngl. -
url - Required HTTPS URL within the application - scope that will handle the - protocol. The %s token will be replaced by the URL starting - with the protocol handler's scheme. If url is a relative - URL, the base URL will be the URL of the manifest. -
- ## Specifications {{Specifications}} diff --git a/files/en-us/web/manifest/scope/index.md b/files/en-us/web/manifest/scope/index.md index eed4eebfd7ea479..2931d52960d59dc 100644 --- a/files/en-us/web/manifest/scope/index.md +++ b/files/en-us/web/manifest/scope/index.md @@ -7,15 +7,6 @@ browser-compat: html.manifest.scope {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeString
- The `scope` member is a string that defines the navigation scope of this web application's application context. It restricts what web pages can be viewed while the manifest is applied. If the user navigates outside the scope, it reverts to a normal web page inside a browser tab or window. A valid `scope` needs to allow [`start_url`](/en-US/docs/Web/Manifest/start_url) to be in scope. If the `scope` is a relative URL, the base URL will be the URL of the manifest. The query and fragment of the URL are always ignored. diff --git a/files/en-us/web/manifest/screenshots/index.md b/files/en-us/web/manifest/screenshots/index.md index 86a7bc91c268f47..d286812104f342b 100644 --- a/files/en-us/web/manifest/screenshots/index.md +++ b/files/en-us/web/manifest/screenshots/index.md @@ -9,18 +9,9 @@ browser-compat: html.manifest.screenshots {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}} - - - - - - - -
TypeArray
- The `screenshots` member defines an array of screenshots intended to showcase the application. These images are intended to be used by progressive web app stores. -## Properties +### Values The `screenshots` member is an array of objects each representing a screenshot. Each screenshot object may contain the following properties: diff --git a/files/en-us/web/manifest/serviceworker/index.md b/files/en-us/web/manifest/serviceworker/index.md index 94a16d2bacd3dfd..cc14e5dbe19b16c 100644 --- a/files/en-us/web/manifest/serviceworker/index.md +++ b/files/en-us/web/manifest/serviceworker/index.md @@ -10,57 +10,31 @@ browser-compat: html.manifest.serviceworker {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}}{{Non-standard_header}} - - - - - - - -
TypeObject
- The `serviceworker` member specifies a serviceworker that is Just-In-Time (JIT)-installed and registered to run a web-based payment app providing a payment mechanism for a specified payment method in a merchant website. See {{domxref("Payment Handler API", "Payment Handler API", "", "nocode")}} for more details. -## Example +### Values -See [Payment Handler API > Concepts and usage](/en-US/docs/Web/API/Payment_Handler_API#concepts_and_usage). +`serviceworker` objects may contain the following values: -## Values +- `scope` -`serviceworker` objects may contain the following values: + - : A string representing the service worker's registration scope. + +- `src` + + - : A string representing the URL to download the service worker script from. - - - - - - - - - - - - - - - - - - - - - -
MemberDescription
scope - A string representing the service worker's registration scope. -
src - A string representing the URL to download the service worker script from. -
use_cache - A boolean that sets how the HTTP cache is used for service worker script resources during updates. It provides equivalent functionality to certain values of the updateViaCache option provided when a service worker is registered via JavaScript using {{domxref("ServiceWorkerContainer.register()")}}. -
    -
  • true: The HTTP cache will be queried for imports, but the main script will always be updated from the network. If no fresh entry is found in the HTTP cache for the imports, they're fetched from the network. Equivalent to updateViaCache: "imports".
    • -
  • false: The HTTP cache will not be used for the main script or its imports. All service worker script resources will be updated from the network. Equivalent to updateViaCache: "none".
    • -
-
+- `use_cache` + + - : A boolean that sets how the HTTP cache is used for service worker script resources during updates. + It provides equivalent functionality to certain values of the `updateViaCache` option provided when a service worker is registered via JavaScript using {{domxref("ServiceWorkerContainer.register()")}}. + + - `true`: The HTTP cache will be queried for imports, but the main script will always be updated from the network. If no fresh entry is found in the HTTP cache for the imports, they're fetched from the network. Equivalent to `updateViaCache: "imports"`. + - `false`: The HTTP cache will not be used for the main script or its imports. All service worker script resources will be updated from the network. Equivalent to `updateViaCache: "none"`. + +## Examples + +See [Payment Handler API > Concepts and usage](/en-US/docs/Web/API/Payment_Handler_API#concepts_and_usage). ## Specifications diff --git a/files/en-us/web/manifest/share_target/index.md b/files/en-us/web/manifest/share_target/index.md index c98efac371f1c85..500e64ab6608250 100644 --- a/files/en-us/web/manifest/share_target/index.md +++ b/files/en-us/web/manifest/share_target/index.md @@ -9,15 +9,6 @@ browser-compat: html.manifest.share_target {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}{{SeeCompatTable}} - - - - - - - -
TypeObject
- The `share_target` manifest member allows installed {{Glossary("Progressive Web Apps")}} (PWAs) to be registered as a share target in the system's share dialog. Once registered and installed, a PWA that uses the Web Share Target API acts as a content sharing target, along with typical system share targets like email, messengers, and other native apps that can receive shared content. @@ -25,9 +16,9 @@ Once registered and installed, a PWA that uses the Web Share Target API acts as > [!NOTE] > If you want to share data using the Web Share API, see [Web Share API](/en-US/docs/Web/API/Web_Share_API) and [`navigator.share()`](/en-US/docs/Web/API/Navigator/share). -## Properties +### Values -To define how an application can receive share data, a `share_target` object in the manifest may contain the following properties (`action` and `params` are required): +The value of the `share_target` member is an object that defines how an application can receive shared data. This object may contain the following properties (`action` and `params` are required): - `action` - : The URL for the web share target. diff --git a/files/en-us/web/manifest/shortcuts/index.md b/files/en-us/web/manifest/shortcuts/index.md index 9e93481543f0eb9..213336b9f0a0aaa 100644 --- a/files/en-us/web/manifest/shortcuts/index.md +++ b/files/en-us/web/manifest/shortcuts/index.md @@ -7,63 +7,31 @@ browser-compat: html.manifest.shortcuts {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}} - - - - - - - -
TypeArray
- The `shortcuts` member defines an array of shortcuts or links to key tasks or pages within a web app. A user agent can use these values to assemble a context menu to be displayed by the operating system when a user engages with the web app's icon. When user invokes a shortcut, the user agent will navigate to the address given by shortcut's `url` member. -## Shortcut item values +### Values Shortcut objects may contain the following values (only `name` and `url` are required): - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MemberDescription
name A string that can be displayed to the user in a context menu.
short_name - A string that can be displayed where there is insufficient space to - display the full name of the shortcut. -
description - A string that describes the purpose of the shortcut. It may be exposed - to assistive technology. -
url - A URL within the application that opens when the shortcut is activated. -
icons - A set of icons that represent the shortcut. They can be used, e.g., in - the context menu. When included, the icon set must include a 96x96 pixel - icon. -
+- `name` + + - : A string that can be displayed to the user in a context menu. + +- `short_name` {{Optional_Inline}} + + - : A string that can be displayed where there is insufficient space to display the full name of the shortcut. + +- `description` {{Optional_Inline}} + + - : A string that describes the purpose of the shortcut. It may be exposed to assistive technology. + +- `url` + + - : A URL within the application that opens when the shortcut is activated. + +- `icons` {{Optional_Inline}} + - : A set of icons that represent the shortcut. + They can be used, e.g., in the context menu. When included, the icon set must include a 96x96 pixel icon. ## Examples