Docserver manifest follow up (rewrite)

chrome/common/extensions/docs/templates/articles/manifest.html

 <h1>Formats: Manifest Files</h1>
 
 
 <p>
 Every extension, installable web app, and theme has a
 <a href="http://www.json.org">JSON</a>-formatted manifest file,
 named <code>manifest.json</code>,
 that provides important information.
 </p>
 
 <h2 id="overview"> Field summary </h2>
 
 <p>
 The following code shows the supported manifest fields,
 with links to the page that discusses each field.
 The only fields that are always required
 are <b>name</b> and <b>version</b>.
 </p>
 
-<pre>
-{
-  <em>// Required</em>
-  "<a href="#name">name</a>": "<em>My Extension</em>",
-  "<a href="#version">version</a>": "<em>versionString</em>",
-  "<a href="#manifest_version">manifest_version</a>": 2,
-{{?is_apps}}
-  "<a href="#app">app</a>": {...},
-{{/is_apps}}
-
-  <em>// Recommended</em>
-  "<a href="#description">description</a>": "<em>A plain text description</em>",
-  "<a href="#icons">icons</a>": { ... },
-  "<a href="#default_locale">default_locale</a>": "<em>en</em>",
-{{^is_apps}}
-
-  <em>// Pick one (or none)</em>
-  "<a href="browserAction.html">browser_action</a>": {...},
-  "<a href="pageAction.html">page_action</a>": {...},
-  "<a href="themes.html">theme</a>": {...},
-  "<a href="#app">app</a>": {...},
-{{/is_apps}}
-
-  <em>// Add any of these that you need</em>
-  "<a href="event_pages.html">background</a>": {"persistent": false, ...},
-  "<a href="background_pages.html">background</a>": {"persistent": true, ...},
-{{^is_apps}}
-  "<a href="override.html">chrome_url_overrides</a>": {...},
-{{/is_apps}}
-  "<a href="content_scripts.html">content_scripts</a>": [...],
-  "<a href="contentSecurityPolicy.html">content_security_policy</a>": "<em>policyString</em>",
-  "<a href="fileBrowserHandler.html">file_browser_handlers</a>": [...],
-  "<a href="#file_handlers">file_handlers</a>": {...},
-  "<a href="#homepage_url">homepage_url</a>": "http://<em>path/to/homepage</em>",
-  "<a href="#incognito">incognito</a>": "spanning" <em>or</em> "split",
-  "<a href="#key">key</a>": "<em>publicKey</em>",
-  "<a href="#minimum_chrome_version">minimum_chrome_version</a>": "<em>versionString</em>",
-
-  "<a href="#nacl_modules">nacl_modules</a>": [...],
-  "<a href="#kiosk_enabled">kiosk_enabled</a>": true,
-  "<a href="#offline_enabled">offline_enabled</a>": true,
-  "<a href="omnibox.html">omnibox</a>": { "keyword": "<em>aString</em>" },
-{{^is_apps}}
-  "<a href="options.html">options_page</a>": "<em>aFile</em>.html",
-{{/is_apps}}
-  "<a href="declare_permissions.html">permissions</a>": [...],
-  "<a href="npapi.html">plugins</a>": [...],
-  "<a href="#requirements">requirements</a>": {...},
-  "<a href="autoupdate.html">update_url</a>": "http://<em>path/to/updateInfo</em>.xml",
-  "<a href="#web_accessible_resources">web_accessible_resources</a>": [...],
-  "<a href="#sandbox">sandbox</a>": [...]
-}
-</pre>
-
-
-<h2 id="field_details">Field details</h2>
-
-<p>
-This section covers fields that aren't described in another page.
-For a complete list of fields,
-with links to where they're described in detail,
-see the <a href="#overview">Field summary</a>.
-</p>
-
-
-<h3 id="app">app</h3>
-
-<p>
-Used by <a href="../apps/app_lifecycle.html#eventpage">packaged apps</a>
-to specify the app's background scripts.
-Also used by <a href="https://developers.google.com/chrome/apps/docs/developers_guide#live">hosted apps</a>
-to specify the URLs that the app uses.
-</p>
-
-<h3 id="default_locale">default_locale</h3>
-
-<p>
-Specifies the subdirectory of <code>_locales</code>
-that contains the default strings for this extension.
-This field is <b>required</b> in extensions
-that have a <code>_locales</code> directory;
-it <b>must be absent</b> in extensions
-that have no <code>_locales</code> directory.
-For details, see
-<a href="i18n.html">Internationalization</a>.
-</p>
-
-<h3 id="description">description</h3>
-
-<p>
-A plain text string
-(no HTML or other formatting;
-no more than 132 characters)
-that describes the extension.
-The description should be suitable for both
-the browser's extension management UI
-and the <a href="https://chrome.google.com/webstore">Chrome Web Store</a>.
-You can specify locale-specific strings for this field;
-see <a href="i18n.html">Internationalization</a> for details.
-</p>
-
-<h3 id="file_handlers">file_handlers</h3>
-
-<p>
-Used by <a href="../apps/app_lifecycle.html#eventpage">packaged apps</a>
-to specify what types of files the app can handle. An app can have multiple <code>file_handlers</code>, with each one having an identifier, a list of MIME types and/or a list of file extensions that can be handled, and
-a title. The app can handle a file if it either has a matching file extension or
-has a matching MIME type.
-You can use a wildcard <code>"*"</code> in <code>types</code> or
-<code>extensions</code> to indicate that the app can handle any file type or
-<code>"<em>type</em>/*"</code> in <code>types</code> to indicate that the app
-can handle any file with a MIME type of <code><em>type</em></code>.
-Here's an example of specifying file handlers:
-</p>
-
-<pre>
-"file_handlers": {
-  "text": {
-    "types": [
-      "text/*"
-    ],
-    "title": "Text editor"
-  },
-  "image": {
-    "types": [
-      "image/png",
-      "image/jpeg"
-    ],
-    "extensions": [
-      "tiff"
-    ]
-    "title": "Image editor"
-  },
-  "any": {
-    "extensions": [
-      "*"
-    ]
-    "title": "Any file type editor"
-  }
-}
-</pre>
-
-<p>
-To handle files, apps also need to declare the $ref:fileSystem
-permission. Apps can then be passed files in the $ref:app.runtime.onLaunched
-event - either from the system
-file manager (currently supported on ChromeOS only) or by providing
-a path on the <a href="../apps/first_app.html#open">command line</a>.
-</p>
-
-<h3 id="homepage_url">homepage_url</h3>
-
-<p>
-The URL of the homepage for this extension. The extensions management page (chrome://extensions)
-will contain a link to this URL.  This field is particularly useful if you
-<a href="hosting.html">host the extension on your own site</a>. If you distribute your
-extension using the <a href="https://chrome.google.com/webstore">Chrome Web Store</a>,
-the homepage URL defaults to the extension's own page.
-</p>
-
-<h3 id="icons">icons</h3>
-
-<p>
-One or more icons that represent the extension, app, or theme.
-You should always provide a 128x128 icon;
-it's used during installation and by the Chrome Web Store.
-Extensions should also provide a 48x48 icon,
-which is used in the extensions management page
-(chrome://extensions).
-You can also specify a 16x16 icon to be used as the favicon
-for an extension's pages.
-The 16x16 icon is also displayed in the experimental extension
-<a href="infobars.html">infobar</a>
-feature.
-</p>
-
-<p>
-Icons should generally be in PNG format,
-because PNG has the best support for transparency.
-They can, however, be in any format supported by WebKit,
-including BMP, GIF, ICO, and JPEG.
-Here's an example of specifying the icons:
-</p>
-
-<pre>
-"icons": { "16": "icon16.png",
-           "48": "icon48.png",
-          "128": "icon128.png" },
-</pre>
-
-<p class="note">
-You may provide icons of any other size you wish, and Chrome will attempt to use
-the best size where appropriate. For example, Windows often requires 32-pixel
-icons, and if the app includes a 32-pixel icon, Chrome will choose that instead
-of shrinking a 48-pixel icon down. However, you should ensure that all of your
-icons are square, or unexpected behavior may result.
-</p>
-
-<p>
-If you upload your extension, app, or theme using the
-<a href="https://chrome.google.com/webstore/developer/dashboard">Chrome Developer Dashboard</a>,
-you'll need to upload additional images,
-including at least one screenshot of your extension.
-For more information,
-see the
-<a href="http://code.google.com/chrome/webstore/">Chrome Web Store
-developer documentation</a>.
-</p>
-
-<h3 id="incognito">incognito</h3>
-
-<p>
-Either "spanning" or "split", to specify how this extension will
-behave if allowed to run in incognito mode.
-</p>
-
-<p>
-The default for extensions is "spanning", which means that the extension
-will run in a single shared process. Any events or messages from an incognito
-tab will be sent to the shared process, with an <em>incognito</em> flag
-indicating where it came from. Because incognito tabs cannot use this shared
-process, an extension using the "spanning" incognito mode will not be able to
-load pages from its extension package into the main frame of an incognito tab.
-</p>
-
-<p>
-The default for installable web apps is "split",
-which means that all app pages in
-an incognito window will run in their own incognito process. If the app or extension contains a background page, that will also run in the incognito process.
-This incognito process runs along side the regular process, but has a separate
-memory-only cookie store. Each process sees events and messages only from its
-own context (for example, the incognito process will see only incognito tab updates).
-The processes are unable to communicate with each other.
-</p>
-
-<p>
-As a rule of thumb, if your extension or app needs to load a tab in an incognito browser, use
-<em>split</em> incognito behavior. If your extension or app needs to be logged
-into a remote server or persist settings locally, use <em>spanning</em>
-incognito behavior.
-</p>
-
-<h3 id="key">key</h3>
-
-<p>
-This value can be used to control
-the unique ID of an extension, app, or theme when
-it is loaded during development.
-</p>
-
-<p class="note">
-<b>Note:</b> You don't usually need to
-use this value. Instead, write your
-code so that the key value doesn't matter
-by using <a href="../extensions/overview.html#relative-urls">relative paths</a>
-and $ref:runtime.getURL.
-</p>
-
-<p>
-To get a suitable key value, first
-install your extension from a <code>.crx</code> file
-(you may need to
-<a href="https://chrome.google.com/webstore/developer/dashboard">upload your extension</a>
-or <a href="packaging.html">package it manually</a>).
-Then, in your
-<a href="http://www.chromium.org/user-experience/user-data-directory">user
-data directory</a>, look in the file
-<code>Default/Extensions/<em>&lt;extensionId&gt;</em>/<em>&lt;versionString&gt;</em>/manifest.json</code>.
-You will see the key value filled in there.
-</p>
-
-<h3 id="minimum_chrome_version">minimum_chrome_version</h3>
-
-<p>
-The version of Chrome that your extension, app, or theme requires, if any.
-The format for this string is the same as for the
-<a href="#version">version</a> field.
-
-<h3 id="name">name</h3>
-
-<p>
-A short, plain text string
-(no more than 45 characters)
-that identifies the extension.
-The name is used in the install dialog,
-extension management UI,
-and the <a href="https://chrome.google.com/webstore">store</a>.
-You can specify locale-specific strings for this field;
-see <a href="i18n.html">Internationalization</a> for details.
-</p>
-
-<h3 id="nacl_modules">nacl_modules</h3>
-
-<p>
-One or more mappings from MIME types to the Native Client module
-that handles each type.
-For example, the bold code in the following snippet
-registers a Native Client module as the content handler
-for the OpenOffice spreadsheet MIME type.
-</p>
-
-<pre>
-{
-  "name": "Native Client OpenOffice Spreadsheet Viewer",
-  "version": "0.1",
-  "description": "Open OpenOffice spreadsheets, right in your browser.",
-  <b>"nacl_modules": [{
-    "path": "OpenOfficeViewer.nmf",
-    "mime_type": "application/vnd.oasis.opendocument.spreadsheet"
-  }]</b>
-}
-</pre>
-
-<p>
-The value of "path" is the location of a Native Client manifest
-(a <code>.nmf</code> file)
-within the extension directory.
-For more information on Native Client and <code>.nmf</code> files, see the
-<a href="http://code.google.com/chrome/nativeclient/docs/technical_overview.html">Native Client Technical Overview</a>.
-</p>
-
-<p>
-Each MIME type can be associated with only one <code>.nmf</code> file,
-but a single <code>.nmf</code> file might handle multiple MIME types.
-The following example shows an extension
-with two <code>.nmf</code> files
-that handle three MIME types.
-</p>
-
-<pre>
-{
-  "name": "Spreadsheet Viewer",
-  "version": "0.1",
-  "description": "Open OpenOffice and Excel spreadsheets, right in your browser.",
-  "nacl_modules": [{
-    "path": "OpenOfficeViewer.nmf",
-    "mime_type": "application/vnd.oasis.opendocument.spreadsheet"
-  },
-  {
-    "path": "OpenOfficeViewer.nmf",
-    "mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
-  },
-  {
-    "path": "ExcelViewer.nmf",
-    "mime_type": "application/excel"
-  }]
-}
-</pre>
-
-<p class="note">
-<strong>Note:</strong>
-You can use Native Client modules in extensions
-without specifying "nacl_modules".
-Use "nacl_modules" only if you want the browser
-to use your Native Client module
-to display a particular type of content.
-</p>
-
-<h3 id="kiosk_enabled">kiosk_enabled</h3>
-
-<p>
-Whether the packaged app is designed to expected to work in ChromeOS kiosk mode.
-In kiosk mode, the platform app window will cover the entire surface of the
-display (forced full screen). The kiosk-enabled apps are expected to be designed
-with this constraint in mind.
-</p>
-
-<h3 id="offline_enabled">offline_enabled</h3>
-
-<p>
-Whether the app or extension is expected to work offline. When Chrome detects
-that it is offline, apps with this field set to true will be highlighted
-on the New Tab page.
-</p>
-
-<h3 id="requirements">requirements</h3>
-
-<p>
-Technologies required by the app or extension.
-Hosting sites such as the Chrome Web Store may use this list
-to dissuade users from installing apps or extensions
-that will not work on their computer.
-Supported requirements currently include "3D" and "plugins";
-additional requirements checks may be added in the future.
-</p>
-
-<p>
-The "3D" requirement denotes GPU hardware acceleration.
-The "webgl" requirement refers to the
-<a href="http://www.khronos.org/webgl/">WebGL API</a>.
-For more information on Chrome 3D graphics support,
-see the help article on
-<a href="http://www.google.com/support/chrome/bin/answer.py?answer=1220892">WebGL and 3D graphics</a>.
-You can list the 3D-related features your app requires,
-as demonstrated in the following example:
-</p>
-
-<pre>
-"requirements": {
-  "3D": {
-    "features": ["webgl"]
-  }
-}
-</pre>
-
-<p>
-The "plugins" requirement indicates
-if an app or extension requires NPAPI to run.
-This requirement is enabled by default
-when the manifest includes the
-<a href="npapi.html">"plugins" field</a>.
-For apps and extensions that still work when plugins aren't available,
-you can disable this requirement
-by setting NPAPI to false.
-You can also enable this requirement manually,
-by setting NPAPI to true,
-as shown in this example:
-</p>
-
-<pre>
-"requirements": {
-  "plugins": {
-    "npapi": true
-  }
-}
-</pre>
-
-
-<h3 id="version">version</h3>
-
-<p>
-One to four dot-separated integers
-identifying the version of this extension.
-A couple of rules apply to the integers:
-they must be between 0 and 65535, inclusive,
-and non-zero integers can't start with 0.
-For example, 99999 and 032 are both invalid.
-</p>
-
-<p>
-Here are some examples of valid versions:
-</p>
-
-<ul>
-  <li> <code>"version": "1"</code> </li>
-  <li> <code>"version": "1.0"</code> </li>
-  <li> <code>"version": "2.10.2"</code> </li>
-  <li> <code>"version": "3.1.2.4567"</code> </li>
-</ul>
-
-<p>
-The autoupdate system compares versions
-to determine whether an installed extension
-needs to be updated.
-If the published extension has a newer version string
-than the installed extension,
-then the extension is automatically updated.
-</p>
-
-<p>
-The comparison starts with the leftmost integers.
-If those integers are equal,
-the integers to the right are compared,
-and so on.
-For example, 1.2.0 is a newer version than 1.1.9.9999.
-</p>
-
-<p>
-A missing integer is equal to zero.
-For example, 1.1.9.9999 is newer than 1.1.
-</p>
-
-<p>
-For more information, see
-<a href="autoupdate.html">Autoupdating</a>.
-</p>
-
-
-
-<h3 id="manifest_version">manifest_version</h3>
-
-<p>
-One integer specifying the version of the manifest file format your package
-requires. As of Chrome 18, developers <em>should</em> specify <code>2</code>
-(without quotes) to use the format as described by this document:
-</p>
-
-<pre>"manifest_version": 2</pre>
-
-<p>
-Consider manifest version 1 <em>deprecated</em> as of Chrome 18. Version 2 is
-not yet <em>required</em>, but we will, at some point in the not-too-distant
-future, stop supporting packages using deprecated manifest versions. Extensions,
-applications, and themes that aren't ready to make the jump to the new manifest
-version in Chrome 18 can either explicitly specify version <code>1</code>, or
-leave the key off entirely.
-</p>
-
-<p>
-The changes between version 1 and version 2 of the manifest file format are
-described in detail in <a href="manifestVersion.html">the
-<code>manifest_version</code> documentation.</a>
-</p>
-
-<p class="caution">
-  Setting <code>manifest_version</code> 2 in Chrome 17 or lower is not
-  recommended. If your extension needs to work in older versions of Chrome,
-  stick with version 1 for the moment. We'll give you ample warning before
-  version 1 stops working.
-</p>
-
-<h3 id="web_accessible_resources">web_accessible_resources</h3>
-
-<p>
-An array of strings specifying the paths (relative to the package root) of
-packaged resources that are expected to be usable in the context of a web page.
-For example, an extension that injects a content script with the intention of
-building up some custom interface for <code>example.com</code> would whitelist
-any resources that interface requires (images, icons, stylesheets, scripts,
-etc.) as follows:
-</p>
-
-<pre>{
-  ...
-  "web_accessible_resources": [
-    "images/my-awesome-image1.png",
-    "images/my-amazing-icon1.png",
-    "style/double-rainbow.css",
-    "script/double-rainbow.js"
-  ],
-  ...
-}</pre>
-
-<p>
-These resources would then be available in a webpage via the URL
-<code>chrome-extension://[PACKAGE ID]/[PATH]</code>, which can be generated with
-the $ref:runtime.getURL method. Whitelisted resources are served with appropriate
-<a href="http://www.w3.org/TR/cors/">CORS</a> headers, so they're available via
-mechanisms like XHR.
-</p>
-
-<p>
-Injected content scripts themselves do not need to be whitelisted.
-</p>
-
-<p>
-Prior to manifest version 2 all resources within an extension could be accessed
-from any page on the web. This allowed a malicious website to
-<a href="http://en.wikipedia.org/wiki/Device_fingerprint">fingerprint</a> the
-extensions that a user has installed or exploit vulnerabilities (for example
-<a href="http://en.wikipedia.org/wiki/Cross-site_scripting">XSS bugs</a>)within
-installed extensions. Limiting availability to only resources which are
-explicitly intended to be web accessible serves to both minimize the available
-attack surface and protect the privacy of users.
-</p>
-
-<h4 id="availability">Default Availability</h4>
-
-<p>
-Resources inside of packages using <a href="#manifest_version"><code>manifest_version</code></a>
-2 or above are <strong>blocked by default</strong>, and must be whitelisted
-for use via this property.
-</p>
-
-<p>
-Resources inside of packages using <code>manifest_version</code> 1 are available
-by default, but <em>if</em> you do set this property, then it will be treated as
-a complete list of all whitelisted resources. Resources not listed will be
-blocked.
-</p>
-
-<h3 id="sandbox">sandbox</h3>
-
-<p>
-Defines an collection of app or extension pages that are to be served
-in a sandboxed unique origin, and optionally a Content Security Policy to use
-with them. Being in a sandbox has two implications:
-</p>
-
-<ol>
-<li>A sandboxed page will not have access to extension or app APIs, or
-direct access to non-sandboxed pages (it may communicate with them via
-<code>postMessage()</code>).</li>
-<li>
-  <p>A sandboxed page is not subject to the
-  <a href="../extensions/contentSecurityPolicy.html">Content Security Policy
-  (CSP)</a> used by the rest of the app or extension (it has its own separate
-  CSP value). This means that, for example, it can use inline script and
-  <code>eval</code>.</p>
-
-  <p>For example, here's how to specify that two extension pages are to be
-  served in a sandbox with a custom CSP:</p>
-
-  <pre>{
-  ...
-  "sandbox": {
-    "pages": [
-      "page1.html",
-      "directory/page2.html"
-    ]
-    <i>// content_security_policy is optional.</i>
-    "content_security_policy":
-        "sandbox allow-scripts; script-src https://www.google.com"
-  ],
-  ...
-}</pre>
-
-  <p>
-  If not specified, the default <code>content_security_policy</code> value is
-  <code>sandbox allow-scripts allow-forms</code>. You can specify your CSP
-  value to restrict the sandbox even further, but it must have the <code>sandbox</code>
-  directive and may not have the <code>allow-same-origin</code> token (see
-  <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#attr-iframe-sandbox">the
-  HTML5 specification</a> for possible sandbox tokens).
-  </p>
-</li>
-</ol>
-
-<p>
-Note that you only need to list pages that you expected to be loaded in
-windows or frames. Resources used by sandboxed pages (e.g. stylesheets or
-JavaScript source files) do not need to appear in the
-<code>sandboxed_page</code> list, they will use the sandbox of the page
-that embeds them.
-</p>
-
-<p>
-<a href="sandboxingEval.html">"Using eval in Chrome Extensions. Safely."</a>
-goes into more detail about implementing a sandboxing workflow that enables use
-of libraries that would otherwise have issues executing under extension's
-<a href="../extensions/contentSecurityPolicy.html">default Content Security
-Policy</a>.
-</p>
-
-<p>
-Sandboxed page may only be specified when using
-<a href="#manifest_version"><code>manifest_version</code></a> 2 or above.
-</p>
+{{+partials.manifest_example manifest_source:manifest_source}}