chrome/common/extensions/docs/external_extensions.html - Issue 10642015: Basic setup for generating app docs

Side by Side Diff: chrome/common/extensions/docs/external_extensions.html

Issue 10642015: Basic setup for generating app docs (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: Created 8 years, 6 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch | Annotate | Revision Log

OLD	NEW
	(Empty)
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:

2 1) The <head> information in this page is significant, should be uniform

3 across api docs and should be edited only with knowledge of the

4 templating mechanism.

5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a

6 browser, it will be re-generated from the template, json schema and

7 authored overview content.

8 4) The <body>.innerHTML is also generated by an offline step so that this

9 page may easily be indexed by search engines.

10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>

11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">

13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print">

14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js">

15 </script>

16 <script type="text/javascript" src="../../../../third_party/json_minify/mini fy-sans-regexp.js">

17 </script>

18 <script type="text/javascript" src="js/api_page_generator.js"></script>

19 <script type="text/javascript" src="js/bootstrap.js"></script>

20 <script type="text/javascript" src="js/sidebar.js"></script>

21 <title>Other Deployment Options - Google Chrome Extensions - Google Code</titl e></head>

22 <body> <div id="devModeWarning" class="displayModeWarning">

23 You are viewing extension docs in chrome via the 'file:' scheme: are you exp ecting to see local changes when you refresh? You'll need run chrome with --allo w-file-access-from-files.

24 </div>

25 <div id="branchWarning" class="displayModeWarning">

26 <span>WARNING: This is the <span id="branchName">BETA</span> documentation.

27 It may not work with the stable release of Chrome.</span>

28 <select id="branchChooser">

29 <option>Choose a different version...

30 </option><option value="">Stable

31 </option><option value="beta">Beta

32 </option><option value="dev">Dev

33 </option><option value="trunk">Trunk

34 </option></select>

35 </div>

36 <div id="unofficialWarning" class="displayModeWarning">

37 <span>WARNING: This is unofficial documentation. It may not work with the

38 current release of Chrome.</span>

39 <button id="goToOfficialDocs">Go to the official docs</button>

40 </div>

41 <div id="gc-container" class="labs">

42 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->

43 <!-- In particular, sub-templates that recurse, must be used by allowing

44 jstemplate to make a copy of the template in this section which

45 are not operated on by way of the jsskip="true" -->

46 <!-- /SUBTEMPLATES -->

47 <a id="top"></a>

48 <div id="skipto">

49 <a href="#gc-pagecontent">Skip to page content</a>

50 <a href="#gc-toc">Skip to main navigation</a>

51 </div>

52 <!-- API HEADER -->

53 <table id="header" width="100%" cellspacing="0" border="0">

54 <tbody><tr>

55 <td valign="middle"><a href="http://code.google.com/"><img src="images/c ode_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border: 0; margin:0;"></a></td>

56 <td valign="middle" width="100%" style="padding-left:0.6em;">

57 <form action="http://www.google.com/cse" id="cse" style="margin-top:0. 5em">

58 <div id="gsc-search-box">

59 <input type="hidden" name="cx" value="002967670403910741006:61_cvz fqtno">

60 <input type="hidden" name="ie" value="UTF-8">

61 <input type="text" name="q" value="" size="55">

62 <input class="gsc-search-button" type="submit" name="sa" value="Se arch">

63 <br>

64 <span class="greytext">e.g. "page action" or "tabs"</span>

65 </div>

66 </form>

67 <script type="text/javascript" src="https://www.google.com/jsapi"></sc ript>

68 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>

69 <script type="text/javascript" src="https://www.google.com/coop/cse/t1 3n?form=cse&t13n_langs=en"></script>

70 <script type="text/javascript" src="https://www.google.com/coop/cse/br and?form=cse&lang=en"></script>

71 </td>

72 </tr>

73 </tbody></table>

74 <div id="codesiteContent" class="">

75 <a id="gc-topnav-anchor"></a>

76 <div id="gc-topnav">

77 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Lab s</a>)</h1>

78 <ul id="home" class="gc-topnav-tabs">

79 <li id="home_link">

80 <a href="index.html" title="Google Chrome Extensions home page">Home </a>

81 </li>

82 <li id="docs_link">

83 <a href="docs.html" title="Official Google Chrome Extensions documen tation">Docs</a>

84 </li>

85 <li id="faq_link">

86 <a href="faq.html" title="Answers to frequently asked questions abou t Google Chrome Extensions">FAQ</a>

87 </li>

88 <li id="samples_link">

89 <a href="samples.html" title="Sample extensions (with source code)"> Samples</a>

90 </li>

91 <li id="group_link">

92 <a href="http://groups.google.com/a/chromium.org/group/chromium-exte nsions" title="Google Chrome Extensions developer forum">Group</a>

93 </li>

94 <li id="so_link">

95 <a href="http://stackoverflow.com/questions/tagged/google-chrome-ext ension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a>

96 </li>

97 </ul>

98 </div> <!-- end gc-topnav -->

99 <div class="g-section g-tpl-170">

100 <!-- SIDENAV -->

101 <div class="g-unit g-first" id="gc-toc">

102 <ul>

103 <li><a href="getstarted.html">Getting Started</a></li>

104 <li><a href="overview.html">Overview</a></li>

105 <li><a href="whats_new.html">What's New?</a></li>

106 <li><h2><a href="devguide.html">Developer's Guide</a></h2>

107 <ul>

108 <li>Browser UI

109 <ul>

110 <li><a href="browserAction.html">Browser Actions</a></li>

111 <li><a href="contextMenus.html">Context Menus</a></li>

112 <li><a href="notifications.html">Desktop Notifications</a></li >

113 <li><a href="omnibox.html">Omnibox</a></li>

114 <li><a href="options.html">Options Pages</a></li>

115 <li><a href="override.html">Override Pages</a></li>

116 <li><a href="pageAction.html">Page Actions</a></li>

117 </ul>

118 </li>

119 <li>Browser Interaction

120 <ul>

121 <li><a href="bookmarks.html">Bookmarks</a></li>

122 <li><a href="cookies.html">Cookies</a></li>

123 <li><a href="devtools.html">Developer Tools</a></li>

124 <li><a href="events.html">Events</a></li>

125 <li><a href="history.html">History</a></li>

126 <li><a href="management.html">Management</a></li>

127 <li><a href="tabs.html">Tabs</a></li>

128 <li><a href="windows.html">Windows</a></li>

129 </ul>

130 </li>

131 <li>Implementation

132 <ul>

133 <li><a href="a11y.html">Accessibility</a></li>

134 <li><a href="background_pages.html">Background Pages</a></li>

135 <li><a href="content_scripts.html">Content Scripts</a></li>

136 <li><a href="xhr.html">Cross-Origin XHR</a></li>

137 <li><a href="i18n.html">Internationalization</a></li>

138 <li><a href="messaging.html">Message Passing</a></li>

139 <li><a href="permissions.html">Optional Permissions</a></li>

140 <li><a href="npapi.html">NPAPI Plugins</a></li>

141 </ul>

142 </li>

143 <li>Finishing

144 <ul>

145 <li><a href="hosting.html">Hosting</a></li>

146 <li class="leftNavSelected">Other Deployment Options</li>

147 </ul>

148 </li>

149 </ul>

150 </li>

151 <li><h2><a href="apps.html">Packaged Apps</a></h2></li>

152 <li><h2><a href="tutorials.html">Tutorials</a></h2>

153 <ul>

154 <li><a href="tut_debugging.html">Debugging</a></li>

155 <li><a href="tut_analytics.html">Google Analytics</a></li>

156 <li><a href="tut_oauth.html">OAuth</a></li>

157 </ul>

158 </li>

159 <li><h2>Reference</h2>

160 <ul>

161 <li>Formats

162 <ul>

163 <li><a href="manifest.html">Manifest Files</a></li>

164 <li><a href="match_patterns.html">Match Patterns</a></li>

165 </ul>

166 </li>

167 <li><a href="permission_warnings.html">Permission Warnings</a></li >

168 <li><a href="api_index.html">chrome.* APIs</a></li>

169 <li><a href="api_other.html">Other APIs</a></li>

170 </ul>

171 </li>

172 <li><h2><a href="samples.html">Samples</a></h2></li>

173 <div class="line"> </div>

174 <li><h2>More</h2>

175 <ul>

176 <li><a href="http://code.google.com/chrome/webstore/docs/index.htm l">Chrome Web Store</a></li>

177 <li><a href="http://code.google.com/chrome/apps/docs/developers_gu ide.html">Hosted Apps</a></li>

178 <li><a href="themes.html">Themes</a></li>

179 </ul>

180 </li>

181 </ul>

182 </div>

183 <script>

184 initToggles();

185 </script>

186 <div class="g-unit" id="gc-pagecontent">

187 <div id="pageTitle">

188 <h1 class="page_title">Other Deployment Options</h1>

189 </div>

190 <!-- TABLE OF CONTENTS -->

191 <div id="toc">

192 <h2>Contents</h2>

193 <ol>

194 <li>

195 <a href="#prereqs">Before you begin</a>

196 <ol>

197 </ol>

198 </li><li>

199 <a href="#preferences">Using a preferences file</a>

200 <ol>

201 <li>

202 <a href="#troubleshooting">Troubleshooting Mac OS permissions problems</a>

203 </li>

204 </ol>

205 </li><li>

206 <a href="#registry">Using the Windows registry</a>

207 <ol>

208 </ol>

209 </li><li>

210 <a href="#updating">Updating and uninstalling</a>

211 <ol>

212 </ol>

213 </li><li>

214 <a href="#faq">FAQ</a>

215 <ol>

216 </ol>

217 </li>

218 </ol>

219 </div>

220 <!-- /TABLE OF CONTENTS -->

221 <!-- Standard content lead-in for experimental API pages -->

222 <!-- STATIC CONTENT PLACEHOLDER -->

223 <div id="static"><div id="pageData-name" class="pageData">Other Deployme nt Options</div>

224 <div id="pageData-showTOC" class="pageData">true</div>

225 <p>

226 Usually, users install their own extensions.

227 But sometimes you might want an extension

228 to be installed automatically.

229 Here are two typical cases:

230 </p>

231 <ul>

232 <li>

233 An extension is associated with some other software,

234 and the extension should be installed

235 whenever the user installs that other software.

236 The extension could also be uninstalled

237 when the user removes that other software.

238 </li>

239 <li>

240 A network admin wants to install the same extensions

241 throughout the company.

242 </li>

243 </ul>

244 <p>

245 An extension that's installed automatically is known as an

246 <em>external extension</em>.

247 Google Chrome supports two ways of

248 installing external extensions:

249 </p>

250 <ul>

251 <li> Using a preferences JSON file </li>

252 <li> Using the Windows registry (Windows only) </li>

253 </ul>

254 <p>

255 Both ways support installing an extension from a <code>.crx</code> extension

256 file on the user's computer. The preferences JSON file also supports installing

257 an extension hosted at an

258 <a href="autoupdate.html#H2-1">update URL</a>.

259 See <a href="hosting.html">hosting</a> for details on hosting an extension.

260 </p>

261 <h2 id="prereqs">Before you begin</h2>

262 <p>

263 First, package a

264 <a href="packaging.html"><code>.crx</code> file</a>

265 and make sure that it installs successfully.

266 </p>

267 <p>

268 If you wish to install from an

269 <a href="autoupdate.html#H2-1">update URL</a>, ensure that the extension

270 is properly <a href="hosting.html">hosted</a>.

271 </p>

272 <p>

273 Then, before you edit the preferences file or the registry,

274 make a note of the following:

275 </p>

276 <ul>

277 <li> The intended <b>location</b> of the extension's <code>.crx</code> file,

278 or the update URL from which it is served </li>

279 <li> The extension's <b>version</b>

280 (from the manifest file or the <b>chrome://extensions</b> page) </li>

281 <li> The extension's <b>ID</b>

282 (from the <b>chrome://extensions</b> page

283 when you've loaded the packed extension) </li>

284 </ul>

285 <p>

286 The following examples assume the version is <code>1.0</code>

287 and the ID is <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>.

288 </p>

289 <h2 id="preferences">Using a preferences file</h2>

290 <p class="note">

291 <b>Windows note:</b>

292 Until <a href="http://crbug.com/41902">bug 41902</a> is fixed,

293 you might want to use the <a href="#registry">Windows registry</a>

294 instead of the preferences file.

295 </p>

296 <p class="note">

297 <b>Note:</b>

298 Previous versions of Google Chrome used an

299 <code>external_extensions.json</code> file to specify which extensions to

300 install. This file has been deprecated in favor of individual <code>.json</code>

301 files, one per extension.

302 </p>

303 <ol>

304 <li>If you are installing from a file, make the <code>.crx</code> extension

305 file available to the machine you want to install the extension on.

306 (Copy it to a local directory or to a network share for example,

307 <code>\\server\share\extension.crx</code>

308 or <code>/home/share/extension.crx</code>.)

309 </li>

310 <li>Create a file with the following name in one of the folders listed below:

311 <code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code> where the file name (without the extension)

312 corresponds to your extension's ID.

313 The location depends on the operating system.

314 <dl>

315 <dt> Windows: </dt>

316 <dd> <code><em>chrome_root</em>\Application\<em>chrome_version</em>\Extensio ns\</code>

317 <br>

318 Example: <code>c:\Users\Me\AppData\Local\Google\Chrome\Application\6.0.422.0 \Extensions\</code>

319 </dd>

320 <dt> Mac OS X:</dt>

321 <dd>For a specific user: <code>~USERNAME/Library/Application Support/Google/ Chrome/External Extensions/</code><br>

322 For all users: <code>/Library/Application Support/Google/Chrome/External Extensions/</code>

323 <p>The external extension file for all users is read only if every directory in the path is owned by the user <code>root</code>, has the group <code>admin</ code> or <code>wheel</code>, and is not world writable. The path must also be f ree of symbolic links. These restrictions prevent an unprivileged user from cau sing extensions to be installed for all users. See <a href="#troubleshooting">t roubleshooting</a> for details.</p>

324 <p class="note">

325 <b>Note:</b> The above path for all users was added in Chrome 16. Prior ver sions used a different path:<br>

326 <code>/Applications/Google Chrome.app/Contents/Extensions/</code>

327 This path was deprecated in version 17. Support was removed in version 20. Use one of the paths above instead.</p>

328 </dd>

329 <dt> Linux: </dt>

330 <dd> <code>/opt/google/chrome/extensions/</code> <br>

331 </dd>

332 <dd> <code>/usr/share/google-chrome/extensions/</code> <br>

333 <b>Note:</b> Use <code>chmod</code> if necessary

334 to make sure that the <code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code> files

335 are world-readable.

336 </dd>

337 </dl>

338 </li>

339 <li>If you are installing from a file, specify the extension's location and vers ion with fields

340 named "external_crx" and "external_version" in the file created above.

341 <p>

342 Example:

343 </p><pre> {

344 "external_crx": "/home/share/extension.crx",

345 "external_version": "1.0"

346 }

347 </pre>

348 <p></p>

349 <p class="note">

350 <b>Note:</b>

351 You need to escape

352 each <code>\</code> character in the location.

353 For example,

354 <code>\\server\share\extension.crx</code> would be

355 <code>"\\\\server\\share\\extension.crx"</code>.

356 </p>

357 <p>

358 </p><p>

359 If you are installing from an update URL, specify the extension's update URL

360 with field name "external_update_url".

361 </p>

362 Example:

363 <pre>{

364 "external_update_url": "http://myhost.com/mytestextension/updates.xml"

365 }</pre>

366 <p>

367 If you would like to install extension only for some browser locales,

368 you can list supported locales in field name "supported_locale". Locale may

369 specify parent locale like "en", in this case the extension will be

370 installed for all English locales like "en-US", "en-GB", etc.

371 If another browser locale is selected that is not supported by the extension,

372 the external extensions will be uninstalled. If "supported_locales" list

373 is missing, the extension will be installed for any locale.

374 </p>

375 Example:

376 <pre>{

377 "external_update_url": "http://myhost.com/mytestextension/updates.xml",

378 "supported_locales": [ "en", "fr", "de" ]

379 }</pre>

380 </li>

381 <li>Save the JSON file. </li>

382 <li>Launch Google Chrome and go to <b>chrome://extensions</b>;

383 you should see the extension listed. </li>

384 </ol>

385 <h3 id="troubleshooting">Troubleshooting Mac OS permissions problems</h3>

386 <p>On Mac OS, the external extensions files for all users are only read if file system permissions prevent unprivileged users from changing it. If you do not s ee external extensions installed when Chrome is launched, there may be a permiss ions problem with the external extensions preferences files. To see if this is the problem, follow these steps:</p>

387 <ol>

388 <li> Launch the Console program. You can find it under /Applications/Utilitie s/Console. </li>

389 <li> If the leftmost icon in the Console says "Show Log List", click that icon . A second column appears at the left. </li>

390 <li> Click "Console Messages" in the left pane. </li>

391 <li> Search for the string <b>Can not read external extensions</b>. If there is a problem reading the external extensions files, you will see an error messag e. Look for another error message directly above it, which should explain the i ssue. For example, if you see the following error:

392 "Path /Library/Application Support/Google/Chrome is owned by the wrong grou p", you need to use <code>chgrp</code> or the Finder's Get Info dialog to change the directory's group owner to the Administrator group.</li>

393 <li> After fixing the issue, relaunch Chrome. Test that the external extensio n is now installed. It is possible that one permissions error keeps Chrome from detecting a second error. If the external extension was not installed, repeat these steps until you do not see an error in the Console application.

394 </li></ol>

395 <h2 id="registry">Using the Windows registry</h2>

396 <ol>

397 <li>Make the <code>.crx</code> extension file available

398 to the machine you want to install the extension on.

399 (Copy it to a local directory or to a network share —

400 for example, <code>\\server\share\extension.crx</code>.)

401 </li>

402 <li>Find or create the following key in the

403 registry:

404 <ul>

405 <li> 32-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extension s</code> </li>

406 <li> 64-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chro me\Extensions</code> </li>

407 </ul>

408 </li>

409 <li>Create a new key (folder)

410 under the <b>Extensions</b> key with the

411 same name as the ID of your extension

412 (for example, <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>).

413 </li>

414 <li>Create two string values (<code>REG_SZ</code>) named "path" and "version",

415 and set them to the extension's location and version.

416 For example:

417 <ul>

418 <li>path: <code>\\server\share\extension.crx</code> </li>

419 <li>version: <code>1.0</code> </li>

420 </ul>

421 </li>

422 <li>Launch the browser and go to

423 <b>chrome://extensions</b>; you should

424 see the extension listed. </li>

425 </ol>

426 <h2 id="updating">Updating and uninstalling</h2>

427 <p>Google Chrome scans the metadata entries

428 in the preferences and registry

429 each time the browser starts, and makes

430 any necessary changes to the installed

431 external extensions. </p>

432 <p>To update your extension to a new version,

433 update the file, and then update the version

434 in the preferences or registry. </p>

435 <p>To uninstall your extension

436 (for example, if your software is uninstalled),

437 remove your preference file (aaaaaaaaaabbbbbbbbbbcccccccccc.json)

438 or the metadata from the registry. </p>

439 <h2 id="faq">FAQ</h2>

440 <p>

441 This section answers common questions about external extensions.

442 </p>

443 <br>

444 <p><b>Can I specify a URL as a path to the external extension?</b> </p>

445 <p>Yes, if you use a <a href="#preferences">preferences JSON</a> file. The

446 extension must be hosted as explained in <a href="hosting.html">hosting</a>.

447 Use the "external_update_url" property to point to an

448 <a href="autoupdate.html#H2-2">update manifest</a> that has the URL for your

449 extension.</p>

450 <br>

451 <p><b>What are some common mistakes when installing with the preferences

452 file?</b></p>

453 <ul>

454 <li>

455 Not specifying the same id/version

456 as the one listed in the <code>.crx</code> </li>

457 <li>

458 The .json file (<code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code>) is in

459 the wrong location or the ID specified does not match the extension ID.

460 </li><li>

461 Syntax error in JSON file

462 (forgetting to separate entries with comma or

463 leaving a trailing comma somewhere) </li>

464 <li>

465 JSON file entry points to the wrong path

466 to the <code>.crx</code> (or path specified but no filename) </li>

467 <li>

468 Backslashes in UNC path not escaped

469 (for example, <code>"\\server\share\file"</code> is wrong;

470 it should be <code>"\\\\server\\share\\extension"</code>) </li>

471 <li>

472 Permissions problems on a network share </li>

473 </ul>

474 <br>

475 <p><b>What are some common mistakes when installing with the registry?</b> </p>

476 <ul>

477 <li>Not specifying the same id/version

478 as the one listed in the <code>.crx</code> </li>

479 <li>Key created in the wrong location in the registry </li>

480 <li>Registry entry points to the wrong path to the <code>.crx</code> file

481 (or path specified but no filename) </li>

482 <li>Permissions problems on a network share </li>

483 </ul>

484 <br>

485 <p><b>What if the user uninstalls the extension?</b> </p>

486 <p>If the user uninstalls the extension through the UI, it will no

487 longer be installed or updated on each startup. In other words, the

488 external extension is blacklisted. </p>

489 <br>

490 <p><b>How do I get off the blacklist?</b> </p>

491 <p>If the user uninstalls your extension, you should respect that

492 decision. However, if you (the developer) accidentally uninstalled

493 your extension through the UI,

494 you can remove the blacklist tag

495 by installing the extension normally

496 through the UI, and then uninstalling it. </p>

497 </div>

498 <!-- API PAGE -->

499 <!-- /apiPage -->

500 </div> <!-- /gc-pagecontent -->

501 </div> <!-- /g-section -->

502 </div> <!-- /codesiteContent -->

503 <div id="gc-footer" --="">

504 <div class="text">

505 <p>

506 Except as otherwise <a href="http://code.google.com/policies.html#restrictions ">noted</a>,

507 the content of this page is licensed under the <a rel="license" href="http://c reativecommons.org/licenses/by/3.0/">Creative Commons

508 Attribution 3.0 License</a>, and code samples are licensed under the

509 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD Lic ense</a>.

510 </p>

511 <p>

512 ©2011 Google

513 </p>

514 <!-- begin analytics -->

515 <script src="https://www.google-analytics.com/urchin.js" type="text/javascript"> </script>

516 <script src="https://www.google-analytics.com/ga.js" type="text/javascript"></sc ript>

517 <script type="text/javascript">

518 // chrome doc tracking

519 try {

520 var engdocs = _gat._getTracker("YT-10763712-2");

521 engdocs._trackPageview();

522 } catch(err) {}

523 // code.google.com site-wide tracking

524 try {

525 _uacct="UA-18071-1";

526 _uanchor=1;

527 _uff=0;

528 urchinTracker();

529 }

530 catch(e) {/* urchinTracker not available. */}

531 </script>

532 <!-- end analytics -->

533 </div>

534 </div> <!-- /gc-footer -->

535 </div> <!-- /gc-container -->

536 </body></html>

OLD	NEW

« no previous file with comments | « chrome/common/extensions/docs/extensions/xhr.html ('k') | chrome/common/extensions/docs/faq.html » ('j') | no next file with comments »