| OLD | NEW |
| 1 This file describes steps and files needed when adding a new API to Chrome. | 1 This file describes steps and files needed when adding a new API to Chrome. |
| 2 Before you start coding your new API, though, make sure you follow the process | 2 Before you start coding your new API, though, make sure you follow the process |
| 3 described at: | 3 described at: |
| 4 http://www.chromium.org/developers/design-documents/extensions/proposed-change
s/apis-under-development | 4 http://www.chromium.org/developers/design-documents/extensions/proposed-change
s/apis-under-development |
| 5 | 5 |
| 6 Two approaches are available for writing your API specification. The original | 6 Two approaches are available for writing your API specification. The original |
| 7 approach relies on JSON specification files. The more recent and simpler system | 7 approach relies on JSON specification files. The more recent and simpler system |
| 8 uses Web IDL files, but does not yet support all the features of the JSON files. | 8 uses Web IDL files, but does not yet support all the features of the JSON files. |
| 9 Discuss with a member of the extensions team (aa@chromium.org) before you decide | 9 Discuss with a member of the extensions team (aa@chromium.org) before you decide |
| 10 which approach is better suited to your API. | 10 which approach is better suited to your API. |
| 11 | 11 |
| 12 The following steps suppose you're writing an experimental API called "Foo". | 12 The following steps suppose you're writing an experimental API called "Foo". |
| 13 | 13 |
| 14 -------------------------------------------------------------------------------- | 14 -------------------------------------------------------------------------------- |
| 15 APPROACH 1: JSON FILES | 15 APPROACH 1: JSON FILES |
| 16 | 16 |
| 17 1) Write your API specification. | 17 1) Write your API specification. |
| 18 Create "chrome/common/extensions/api/experimental_foo.json". For inspiration | 18 Create "chrome/common/extensions/api/experimental_foo.json". For inspiration |
| 19 look at the "app" API. Include descriptions fields to generate the | 19 look at the "app" API. Include descriptions fields to generate the |
| 20 documentation. | 20 documentation. |
| 21 | 21 |
| 22 2) Add your API specification to extensions_api_resources.grd. | 22 2) Add your API specification to api.gyp. |
| 23 Add an "<include ...>" line with your JSON specification file to | 23 Add "experimental_foo.json" to the "schema_files" section in |
| 24 "chrome/common/extensions_api_resources.grd". | |
| 25 | |
| 26 3) Add your API specification to api.gyp. | |
| 27 Add "experimental_foo.json" to the "json_schema_files" section in | |
| 28 "chrome/common/extensions/api/api.gyp". | 24 "chrome/common/extensions/api/api.gyp". |
| 29 | 25 |
| 30 4) Write the API function handlers. | 26 3) Write the API function handlers. |
| 31 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You | 27 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You |
| 32 should use the JSON Schema Compiler. Look at the "permissions_api.cc" for | 28 should use the JSON Schema Compiler. Look at the "permissions_api.cc" for |
| 33 details on how to do that. | 29 details on how to do that. |
| 34 | 30 |
| 35 5) Register function handlers. | |
| 36 In "chrome/browser/extensions/extension_function_registry.cc" include foo_api.h | |
| 37 and instantiate a RegisterFunction for each function you created in (3). | |
| 38 | |
| 39 -------------------------------------------------------------------------------- | 31 -------------------------------------------------------------------------------- |
| 40 APPROACH 2: IDL FILES | 32 APPROACH 2: IDL FILES |
| 41 | 33 |
| 42 1) Write your API specification. | 34 1) Write your API specification. |
| 43 Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look | 35 Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look |
| 44 at "alarms.idl". Include comments, they will be used to automatically generate | 36 at "alarms.idl". Include comments, they will be used to automatically generate |
| 45 the documentation. | 37 the documentation. |
| 46 | 38 |
| 47 2) Add your API specification to api.gyp. | 39 2) Add your API specification to api.gyp. |
| 48 Add "experimental_foo.idl" to the "idl_schema_files" section in | 40 Add "experimental_foo.idl" to the "schema_files" section in |
| 49 "chrome/common/extensions/api/api.gyp". | 41 "chrome/common/extensions/api/api.gyp". |
| 50 | 42 |
| 51 3) Write the API function handlers. | 43 3) Write the API function handlers. |
| 52 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You | 44 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You |
| 53 should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on | 45 should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on |
| 54 how to do that. | 46 how to do that. |
| 55 | 47 |
| 56 4-5) Nothing to do! Function handlers are automatically registered for you. | |
| 57 | |
| 58 -------------------------------------------------------------------------------- | 48 -------------------------------------------------------------------------------- |
| 59 STEPS COMMON TO BOTH APPROACHES | 49 STEPS COMMON TO BOTH APPROACHES |
| 60 | 50 |
| 61 6) Write support classes for your API | 51 6) Write support classes for your API |
| 62 If your API needs any support classes add them to | 52 If your API needs any support classes add them to |
| 63 "chrome/browser/extensions/api/foo". Some old APIs added their support classes | 53 "chrome/browser/extensions/api/foo". Some old APIs added their support classes |
| 64 directly to chrome/browser/extensions. Don't do that. | 54 directly to chrome/browser/extensions. Don't do that. |
| 65 | 55 |
| 66 7) Update the project with your new files. | 56 7) Update the project with your new files. |
| 67 The files you created in (3) and (5) should be added to | 57 The files you created in (3) and (5) should be added to |
| 68 "chrome/chrome_browser_extensions.gypi". | 58 "chrome/chrome_browser_extensions.gypi". |
| 69 | 59 |
| 70 -------------------------------------------------------------------------------- | 60 -------------------------------------------------------------------------------- |
| 71 GENERATING DOCUMENTATION | 61 GENERATING DOCUMENTATION |
| 72 | 62 |
| 73 8) Build the project. (Only required if you used IDL files.) | 63 8) Add a stub template in ../docs/templates/public corresponding to your API. |
| 74 If you used IDL files, you need to build the project once in order for the | 64 See other templates for inspiration. |
| 75 documentation to be properly generated. Do this now. (This is required in order | |
| 76 to generate the JSON file used to generate documentation.) | |
| 77 | 65 |
| 78 9) Add your JSON file to the documentation controller | 66 9) Run ../docs/templates/server2/preview.py to view the generated documentation. |
| 79 Open "chrome/common/extensions/docs/js/api_page_generator.js" and add a line | |
| 80 referring to "../api/experimental_foo.json". Do this even if you used the IDL | |
| 81 approach as this JSON file has been generated in (7). | |
| 82 | |
| 83 10) Write the static HTML page. | |
| 84 Write a small snippet of static HTML describing your API in | |
| 85 "chrome/common/extensions/docs/static/experimental.foo.html". For the moment, | |
| 86 just include the following in this file, adjusting it to describe your API: | |
| 87 | |
| 88 <div id="pageData-name" class="pageData">Experimental Foo APIs</div> | |
| 89 | |
| 90 <!-- BEGIN AUTHORED CONTENT --> | |
| 91 <p>The current methods allow applications to...</p> | |
| 92 <!-- END AUTHORED CONTENT --> | |
| 93 | |
| 94 11) Build the documentation. | |
| 95 You will need to build DumpRenderTree once before you can build the | |
| 96 documentation. Once this is done, from "chrome/common/extensions/docs" run | |
| 97 "build/build.py". For more information on building documentation see README.txt | |
| 98 in "chrome/common/extensions/docs". | |
| 99 | 67 |
| 100 -------------------------------------------------------------------------------- | 68 -------------------------------------------------------------------------------- |
| 101 WRITING TESTS | 69 WRITING TESTS |
| 102 | 70 |
| 103 12) Write a unit test for your API. | 71 12) Write a unit test for your API. |
| 104 Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of | 72 Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of |
| 105 your API methods. See "alarms_api_unittest.cc" for details. Once done add your | 73 your API methods. See "alarms_api_unittest.cc" for details. Once done add your |
| 106 .cc to "chrome/chrome_tests.gypi". | 74 .cc to "chrome/chrome_tests.gypi". |
| OLD | NEW |