OLD | NEW |
(Empty) | |
| 1 # What is chrome://settings? |
| 2 |
| 3 Chrome (version 10 and above) uses WebUI settings by default for all platforms. |
| 4 Access it via the wrench menu ("Preferences" on Mac and Linux; "Options" on |
| 5 Windows and ChromeOS), or by typing chrome://settings into the address bar. |
| 6 |
| 7 One advantage of chrome://settings over platform-native dialogs is that it is |
| 8 shared by all platforms; therefore, it is easier to add new options UI and to |
| 9 keep all platforms in sync. |
| 10 |
| 11 Note that at the time of this writing, DOMUI is being renamed to WebUI. The two |
| 12 terms will be used interchangeably herein. |
| 13 |
| 14 ## Moving parts |
| 15 |
| 16 ### String resources |
| 17 |
| 18 Strings live in `chrome/app/generated_resources.grd`. There are several rules |
| 19 governing the format of strings: |
| 20 |
| 21 * the **casing of button text** depends on the platform. If your string will |
| 22 be displayed on a button, you need to add it twice, in sentence case and |
| 23 title case. Follow examples inside `<if expr="pp_ifdef('use_titlecase')">` |
| 24 blocks. Do this even if your string is a single word because it may not be a |
| 25 single word in another locale. |
| 26 * strings that are associated with form controls (buttons, checkboxes, |
| 27 dropdowns, etc.) should NOT have **trailing punctuation**. Standalone |
| 28 strings, such as sectional descriptive text, should have trailing |
| 29 punctuation. |
| 30 * strings may be different between Google Chrome and chromium. If they differ |
| 31 only in **product name**, put them in `generated_resources.grd` and use |
| 32 product name placeholders; if they differ more substantially, use |
| 33 `chromium_strings.grd` and `google_chrome_strings.grd`. |
| 34 |
| 35 ### WebUI Handlers |
| 36 |
| 37 The C++ WebUI handler classes for chrome://settings live in |
| 38 `chrome/browser/ui/webui/options/`. These objects both handle messages from and |
| 39 dispatch messages to the page. Each handler is a logical grouping of related |
| 40 functionality. Hence `ContentSettingsHandler` is both the delegate and |
| 41 controller of the content settings subpage. |
| 42 |
| 43 A handler sends a message to the page via `dom_ui_->CallJavascriptFunction()` |
| 44 and registers for messages from the page via |
| 45 `dom_ui_->RegisterMessageCallback()`. |
| 46 |
| 47 ### HTML/CSS/JS |
| 48 |
| 49 The HTML, CSS, and JS resources live in `chrome/browser/resources/options`. They |
| 50 are compiled into one resource at compile time by grit, via `<link>`, `<src>` |
| 51 and `<include>` tags in `options.html`. There is no need to add new files to any |
| 52 `.gyp` file. |
| 53 |
| 54 Some things that are good to know: |
| 55 |
| 56 * JS objects are bound to HTML nodes via `decorate()`. * Javascript calls |
| 57 into C++ via `chrome.send`. * Some automatic preference handling is |
| 58 provided in `preferences.js` and `pref_ui.js`. * Strings defined in a WebUI |
| 59 handler are available via `localStrings.getString()` and friends. |
| 60 |
| 61 ## Example: adding a simple pref |
| 62 |
| 63 Suppose you want to add a pref controlled by a **checkbox**. |
| 64 |
| 65 ### 1. Getting UI approval |
| 66 |
| 67 Ask one of the UI leads where your option belongs. First point of contact should |
| 68 be Alex Ainslie <ainslie at chromium>. |
| 69 |
| 70 ### 2. Adding Strings |
| 71 |
| 72 Add the string to `chrome/app/generated_resources.grd` near related strings. No |
| 73 trailing punctuation; sentence case. |
| 74 |
| 75 ### 3. Changing WebUI Handler |
| 76 |
| 77 For simple prefs, the UI is kept in sync with the value automagically (see |
| 78 `CoreOptionsHandler`). Find the handler most closely relevant to your pref. The |
| 79 only action we need take here is to make the page aware of the new string. |
| 80 Locate the method in the handler called `GetLocalizedStrings` and look at its |
| 81 body for examples of `SetString` usage. The first parameter is the javascript |
| 82 name for the string. |
| 83 |
| 84 ### 4. HTML/CSS/JS |
| 85 |
| 86 An example of the form a checkbox should take in html: |
| 87 |
| 88 ```html |
| 89 <label class="checkbox"> |
| 90 <input id="clear-cookies-on-exit" |
| 91 pref="profile.clear_site_data_on_exit" type="checkbox"> |
| 92 <span i18n-content="clearCookiesOnExit"></span> |
| 93 </label> |
| 94 ``` |
| 95 |
| 96 Of note: |
| 97 |
| 98 * the `checkbox` class allows us to style all checkboxes the same via CSS |
| 99 * the class and ID are in dash-form * the i18n-content value is in camelCase |
| 100 * the pref attribute matches that which is defined in |
| 101 `chrome/common/pref_names.cc` and allows the prefs framework to |
| 102 automatically keep it in sync with the value in C++ |
| 103 * the `i18n-content` value matches the string we defined in the WebUI handler. |
| 104 The `textContent` of the `span` will automatically be set to the associated |
| 105 text. |
| 106 |
| 107 In this example, no additional JS or CSS are needed. |
OLD | NEW |