docs/chrome_settings.md

   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.