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 |