(num_donuts));
}
```
Can be triggered in JavaScript with this example code:
```js
$('bakeDonutsButton').onclick = function() {
chrome.send('bakeDonuts', [5]); // bake 5 donuts!
};
```
## Data Sources
### WebUIDataSource::Create()
This is a factory method required to create a WebUIDataSource instance. The
argument to `Create()` is typically the host name of the page. Caller owns the
result.
### WebUIDataSource::Add()
Once you've created and added some things to a data source, it'll need to be
"added". This means transferring ownership. In practice, the data source is
created in the browser process on the UI thread and transferred to the IO
thread. Additionally, calling `Add()` will overwrite any existing data source
with the same name.
It's unsafe to keep references to a WebUIDataSource
after calling
Add()
. Don't do this.
### WebUIDataSource::AddLocalizedString()
Using an int reference to a grit string (starts with "IDS" and lives in a .grd
or .grdp file), adding a string with a key name will be possible to reference
via the `$i18n{}` syntax (and will be replaced when requested) or later
dynamically in JavaScript via `loadTimeData.getString()` (or `getStringF`).
### WebUIDataSource::AddResourcePath()
Using an int reference to a grit resource (starts with "IDR" and lives in a .grd
or .grdp file), adds a resource to the UI with the specified path.
It's generally a good idea to call AddResourcePath()
with the empty
path and a resource ID that should be served as the "catch all" resource to
respond with. This resource will be served for requests like "chrome://history",
or "chrome://history/pathThatDoesNotExist". It will not be served for requests
that look like they are attempting to fetch a specific file, like
"chrome://history/file\_that\_does\_not\_exist.js". This is so that if a user
enters a typo when trying to load a subpage like "chrome://history/syncedTabs"
they will be redirected to the main history page, instead of seeing an error,
but incorrect imports in the source code will fail, so that they can be more
easily found and corrected.
### WebUIDataSource::AddBoolean()
Often a page needs to know whether a feature is enabled. This is a good use case
for `WebUIDataSource::AddBoolean()`. Then, in the Javascript, one can write
code like this:
```js
if (loadTimeData.getBoolean('myFeatureIsEnabled')) {
...
}
```
Data sources are not recreated on refresh, and therefore values that are dynamic
(i.e. that can change while Chrome is running) may easily become stale. It may
be preferable to use cr.sendWithPromise()
to initialize dynamic
values and call FireWebUIListener()
to update them.
If you really want or need to use AddBoolean()
for a dynamic value,
make sure to call WebUIDataSource::Update()
when the value changes.
## WebUI utils for working with data sources
chrome/browser/ui/webui/webui\_util.\* contains a number of methods to simplify
common configuration tasks.
### WebUIDataSource::AddLocalizedStrings()
Many Web UI data sources need to be set up with a large number of localized
strings. Instead of repeatedly calling AddLocalizedString()
, create
an array of all the strings and use AddLocalizedStrings()
:
```c++
static constexpr webui::LocalizedString kStrings[] = {
// Localized strings (alphabetical order).
{"actionMenuDescription", IDS_HISTORY_ACTION_MENU_DESCRIPTION},
{"ariaRoleDescription", IDS_HISTORY_ARIA_ROLE_DESCRIPTION},
{"bookmarked", IDS_HISTORY_ENTRY_BOOKMARKED},
};
source->AddLocalizedStrings(kStrings);
```
### WebUIDataSource::AddResourcePaths()
Similar to the localized strings, many Web UIs need to add a large number of
resource paths. In this case, use AddResourcePaths()
to
replace repeated calls to AddResourcePath()
.
```c++
static constexpr webui::ResourcePath kPdfResources[] = {
{"pdf/browser_api.js", IDR_PDF_BROWSER_API_JS},
{"pdf/constants.js", IDR_PDF_CONSTANTS_JS},
{"pdf/controller.js", IDR_PDF_CONTROLLER_JS},
};
source->AddResourcePaths(kStrings);
```
The same method can be leveraged for cases that directly use constants defined
by autogenerated grit resources map header files. For example, the autogenerated
print\_preview\_resources\_map.h header defines a
webui::ResourcePath
array named kPrintPreviewResources
and a size\_t kPrintPreviewResourcesSize
. All the resources in this
resource map can be added as follows:
```c++
source->AddResourcePaths(
base::make_span(kPrintPreviewResources, kPrintPreviewResourcesSize));
```
### webui::SetupWebUIDataSource()
This method performs common configuration tasks on a data source for a Web UI
that uses JS modules. When creating a Web UI that uses JS modules, use this
utility instead of duplicating the configuration steps it performs elsewhere.
Specific setup steps include:
* Setting the content security policy to allow the data source to load only
resources from its own host (e.g. chrome://history), chrome://resources, and
chrome://test (used to load test files).
* Enabling i18n template replacements by calling UseStringsJs()
and
EnableReplaceI18nInJS()
on the data source.
* Adding the test loader files to the data source, so that test files can be
loaded as JS modules.
* Setting the resource to load for the empty path.
* Adding all resources from a GritResourceMap.
## Browser (C++) → Renderer (JS)
### WebUIMessageHandler::AllowJavascript()
A tab that has been used for settings UI may be reloaded, or may navigate to an
external origin. In both cases, one does not want callbacks from C++ to
Javascript to run. In the former case, the callbacks will occur when the
Javascript doesn't expect them. In the latter case, sensitive information may be
delivered to an untrusted origin.
Therefore each message handler maintains
[a boolean](https://cs.chromium.org/search/?q=WebUIMessageHandler::javascript_allowed_)
that describes whether delivering callbacks to Javascript is currently
appropriate. This boolean is set by calling `AllowJavascript`, which should be
done when handling a call from Javascript, because that indicates that the page
is ready for the subsequent callback. (See
[design doc](https://drive.google.com/open?id=1z1diKvwgMmn4YFzlW1kss0yHmo8yy68TN_FUhUzRz7Q).)
If the tab navigates or reloads,
[`DisallowJavascript`](https://cs.chromium.org/search/?q=WebUIMessageHandler::DisallowJavascript)
is called to clear the flag.
Therefore, before each callback from C++ to Javascript, the flag must be tested
by calling
[`IsJavascriptAllowed`](https://cs.chromium.org/search/?q=WebUIMessageHandler::IsJavascriptAllowed).
If false, then the callback must be dropped. (When the flag is false, calling
[`ResolveJavascriptCallback`](https://cs.chromium.org/search/?q=WebUIMessageHandler::ResolveJavascriptCallback)
will crash. See
[design doc](https://docs.google.com/document/d/1udXoW3aJL0-l5wrbsOg5bpYWB0qOCW5K7yXpv4tFeA8).)
Also beware of [ABA](https://en.wikipedia.org/wiki/ABA_problem) issues: Consider
the case where an asynchronous operation is started, the settings page is
reloaded, and the user triggers another operation using the original message
handler. The `javascript_allowed_` boolean will be true, but the original
callback should still be dropped because it relates to a operation that was
discarded by the reload. (Reloading settings UI does _not_ cause message handler
objects to be deleted.)
Thus a message handler may override
[`OnJavascriptDisallowed`](https://cs.chromium.org/search/?q=WebUIMessageHandler::OnJavascriptDisallowed)
to learn when pending callbacks should be canceled.
In the JS:
```js
window.onload = function() {
app.initialize();
chrome.send('startPilotLight');
};
```
In the C++:
```c++
void OvenHandler::HandleStartPilotLight(cont base::ListValue* /*args*/) {
AllowJavascript();
// CallJavascriptFunction() and FireWebUIListener() are now safe to do.
GetOven()->StartPilotLight();
}
```
Relying on the 'load'
event or browser-side navigation callbacks to
detect page readiness omits application-specific initialization, and a
custom 'initialized'
message is often necessary.
### WebUIMessageHandler::CallJavascriptFunction()
When the browser process needs to tell the renderer/JS of an event or otherwise
execute code, it can use `CallJavascriptFunction()`.
Javascript must be
allowed to use
CallJavscriptFunction()
.
```c++
void OvenHandler::OnPilotLightExtinguished() {
CallJavascriptFunction("app.pilotLightExtinguished");
}
```
This works by crafting a string to be evaluated in the renderer. Any arguments
to the call are serialized to JSON and the parameter list is wrapped with
```
// See WebUI::GetJavascriptCall() for specifics:
"functionCallName(" + argumentsAsJson + ")"
```
and sent to the renderer via a `FrameMsg_JavaScriptExecuteRequest` IPC message.
While this works, it implies that:
* a global method must exist to successfully run the Javascript request
* any method can be called with any parameter (far more access than required in
practice)
^ These factors have resulted in less use of `CallJavascriptFunction()` in the
webui codebase. This functionality can easily be accomplished with the following
alternatives:
* [`FireWebUIListener()`](#FireWebUIListener) allows easily notifying the page
when an event occurs in C++ and is more loosely coupled (nothing blows up if
the event dispatch is ignored). JS subscribes to notifications via
[`cr.addWebUIListener`](#cr_addWebUIListener).
* [`ResolveJavascriptCallback`](#ResolveJavascriptCallback) and
[`RejectJavascriptCallback`](#RejectJavascriptCallback) are useful
when Javascript requires a response to an inquiry about C++-canonical state
(i.e. "Is Autofill enabled?", "Is the user incognito?")
### WebUIMessageHandler::FireWebUIListener()
`FireWebUIListener()` is used to notify a registered set of listeners that an
event has occurred. This is generally used for events that are not guaranteed to
happen in timely manner, or may be caused to happen by unpredictable events
(i.e. user actions).
Here's some example to detect a change to Chrome's theme:
```js
cr.addWebUIListener("theme-changed", refreshThemeStyles);
```
This Javascript event listener can be triggered in C++ via:
```c++
void MyHandler::OnThemeChanged() {
FireWebUIListener("theme-changed");
}
```
Because it's not clear when a user might want to change their theme nor what
theme they'll choose, this is a good candidate for an event listener.
If you simply need to get a response in Javascript from C++, consider using
[`cr.sendWithPromise()`](#cr_sendWithPromise) and
[`ResolveJavascriptCallback`](#ResolveJavascriptCallback).
### WebUIMessageHandler::OnJavascriptAllowed()
`OnJavascriptDisallowed()` is a lifecycle method called in response to
[`AllowJavascript()`](#AllowJavascript). It is a good place to register
observers of global services or other callbacks that might call at unpredictable
times.
For example:
```c++
class MyHandler : public content::WebUIMessageHandler {
MyHandler() {
GetGlobalService()->AddObserver(this); // <-- DON'T DO THIS.
}
void OnGlobalServiceEvent() {
FireWebUIListener("global-thing-happened");
}
};
```
Because browser-side C++ handlers are created before a renderer is ready, the
above code may result in calling [`FireWebUIListener`](#FireWebUIListener)
before the renderer is ready, which may result in dropped updates or
accidentally running Javascript in a renderer that has navigated to a new URL.
A safer way to set up communication is:
```c++
class MyHandler : public content::WebUIMessageHandler {
public:
MyHandler() : observer_(this) {}
void OnJavascriptAllowed() override {
observer_.Add(GetGlobalService()); // <-- DO THIS.
}
void OnJavascriptDisallowed() override {
observer_.RemoveAll(); // <-- AND THIS.
}
ScopedObserver observer_; // <-- ALSO HANDY.
```
when a renderer has been created and the
document has loaded enough to signal to the C++ that it's ready to respond to
messages.
### WebUIMessageHandler::OnJavascriptDisallowed()
`OnJavascriptDisallowed` is a lifecycle method called when it's unclear whether
it's safe to send JavaScript messsages to the renderer.
There's a number of situations that result in this method being called:
* renderer doesn't exist yet
* renderer exists but isn't ready
* renderer is ready but application-specific JS isn't ready yet
* tab refresh
* renderer crash
Though it's possible to programmatically disable Javascript, it's uncommon to
need to do so.
Because there's no single strategy that works for all cases of a renderer's
state (i.e. queueing vs dropping messages), these lifecycle methods were
introduced so a WebUI application can implement these decisions itself.
Often, it makes sense to disconnect from observers in
`OnJavascriptDisallowed()`:
```c++
void OvenHandler::OnJavascriptDisallowed() {
scoped_oven_observer_.RemoveAll()
}
```
Because `OnJavascriptDisallowed()` is not guaranteed to be called before a
`WebUIMessageHandler`'s destructor, it is often advisable to use some form of
scoped observer that automatically unsubscribes on destruction but can also
imperatively unsubscribe in `OnJavascriptDisallowed()`.
### WebUIMessageHandler::RejectJavascriptCallback()
This method is called in response to
[`cr.sendWithPromise()`](#cr_sendWithPromise) to reject the issued Promise. This
runs the rejection (second) callback in the [Promise's
executor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
and any
[`catch()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch)
callbacks in the chain.
```c++
void OvenHandler::HandleBakeDonuts(const base::ListValue* args) {
AllowJavascript();
if (!GetOven()->HasGas()) {
RejectJavascriptCallback(args->GetList()[0],
base::StringValue("need gas to cook the donuts!"));
}
```
This method is basically just a
[`CallJavascriptFunction()`](#CallJavascriptFunction) wrapper that calls a
global "cr.webUIResponse" method with a success value of false.
```c++
// WebUIMessageHandler::RejectJavascriptCallback():
CallJavascriptFunction("cr.webUIResponse", callback_id, base::Value(false),
response);
```
See also: [`ResolveJavascriptCallback`](#ResolveJavascriptCallback)
### WebUIMessageHandler::ResolveJavascriptCallback()
This method is called in response to
[`cr.sendWithPromise()`](#cr_sendWithPromise) to fulfill an issued Promise,
often with a value. This results in runnings any fulfillment (first) callbacks
in the associate Promise executor and any registered
[`then()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then)
callbacks.
So, given this JS code:
```js
cr.sendWithPromise('bakeDonuts').then(function(numDonutsBaked) {
shop.donuts += numDonutsBaked;
});
```
Some handling C++ might do this:
```c++
void OvenHandler::HandleBakeDonuts(const base::ListValue* args) {
AllowJavascript();
double num_donuts_baked = GetOven()->BakeDonuts();
ResolveJavascriptCallback(args->GetList()[0], num_donuts_baked);
}
```
## Renderer (JS) → Browser (C++)
### chrome.send()
When the JavaScript `window` object is created, a renderer is checked for [WebUI
bindings](#bindings).
```c++
// RenderFrameImpl::DidClearWindowObject():
if (enabled_bindings_ & BINDINGS_POLICY_WEB_UI)
WebUIExtension::Install(frame_);
```
If the bindings exist, a global `chrome.send()` function is exposed to the
renderer:
```c++
// WebUIExtension::Install():
v8::Local chrome = GetOrCreateChromeObject(isolate, context);
chrome->Set(gin::StringToSymbol(isolate, "send"),
gin::CreateFunctionTemplate(
isolate,
base::BindRepeating(&WebUIExtension::Send))->GetFunction());
```
The `chrome.send()` method takes a message name and argument list.
```js
chrome.send('messageName', [arg1, arg2, ...]);
```
The message name and argument list are serialized to JSON and sent via the
`FrameHostMsg_WebUISend` IPC message from the renderer to the browser.
```c++
// In the renderer (WebUIExtension::Send()):
render_frame->Send(new FrameHostMsg_WebUISend(render_frame->GetRoutingID(),
frame->GetDocument().Url(),
message, *content));
```
```c++
// In the browser (WebUIImpl::OnMessageReceived()):
IPC_MESSAGE_HANDLER(FrameHostMsg_WebUISend, OnWebUISend)
```
The browser-side code does a map lookup for the message name and calls the found
callback with the deserialized arguments:
```c++
// WebUIImpl::ProcessWebUIMessage():
message_callbacks_.find(message)->second.Run(&args);
```
### cr.addWebUIListener()
WebUI listeners are a convenient way for C++ to inform JavaScript of events.
Older WebUI code exposed public methods for event notification, similar to how
responses to [chrome.send()](#chrome_send) used to work. They both
resulted in global namespace pollution, but it was additionally hard to stop
listening for events in some cases. **cr.addWebUIListener** is preferred in new
code.
Adding WebUI listeners creates and inserts a unique ID into a map in JavaScript,
just like [cr.sendWithPromise()](#cr_sendWithPromise).
```js
// addWebUIListener():
webUIListenerMap[eventName] = webUIListenerMap[eventName] || {};
webUIListenerMap[eventName][createUid()] = callback;
```
The C++ responds to a globally exposed function (`cr.webUIListenerCallback`)
with an event name and a variable number of arguments.
```c++
// WebUIMessageHandler:
template
void FireWebUIListener(const std::string& event_name, const Values&... values) {
CallJavascriptFunction("cr.webUIListenerCallback", base::Value(event_name),
values...);
}
```
C++ handlers call this `FireWebUIListener` method when an event occurs that
should be communicated to the JavaScript running in a tab.
```c++
void OvenHandler::OnBakingDonutsFinished(size_t num_donuts) {
FireWebUIListener("donuts-baked", base::FundamentalValue(num_donuts));
}
```
JavaScript can listen for WebUI events via:
```js
var donutsReady = 0;
cr.addWebUIListener('donuts-baked', function(numFreshlyBakedDonuts) {
donutsReady += numFreshlyBakedDonuts;
});
```
### cr.sendWithPromise()
`cr.sendWithPromise()` is a wrapper around `chrome.send()`. It's used when
triggering a message requires a response:
```js
chrome.send('getNumberOfDonuts'); // No easy way to get response!
```
In older WebUI pages, global methods were exposed simply so responses could be
sent. **This is discouraged** as it pollutes the global namespace and is harder
to make request specific or do from deeply nested code.
In newer WebUI pages, you see code like this:
```js
cr.sendWithPromise('getNumberOfDonuts').then(function(numDonuts) {
alert('Yay, there are ' + numDonuts + ' delicious donuts left!');
});
```
On the C++ side, the message registration is similar to
[`chrome.send()`](#chrome_send) except that the first argument in the
message handler's list is a callback ID. That ID is passed to
`ResolveJavascriptCallback()`, which ends up resolving the `Promise` in
JavaScript and calling the `then()` function.
```c++
void DonutHandler::HandleGetNumberOfDonuts(const base::ListValue* args) {
AllowJavascript();
const base::Value& callback_id = args->GetList()[0];
size_t num_donuts = GetOven()->GetNumberOfDonuts();
ResolveJavascriptCallback(callback_id, base::FundamentalValue(num_donuts));
}
```
Under the covers, a map of `Promise`s are kept in JavaScript.
The callback ID is just a namespaced, ever-increasing number. It's used to
insert a `Promise` into the JS-side map when created.
```js
// cr.sendWithPromise():
var id = methodName + '_' + uidCounter++;
chromeSendResolverMap[id] = new PromiseResolver;
chrome.send(methodName, [id].concat(args));
```
The corresponding number is used to look up a `Promise` and reject or resolve it
when the outcome is known.
```js
// cr.webUIResponse():
var resolver = chromeSendResolverMap[id];
if (success)
resolver.resolve(response);
else
resolver.reject(response);
```
This approach still relies on the C++ calling a globally exposed method, but
reduces the surface to only a single global (`cr.webUIResponse`) instead of
many. It also makes per-request responses easier, which is helpful when multiple
are in flight.
## Security considerations
Because WebUI pages are highly privileged, they are often targets for attack,
since taking control of a WebUI page can sometimes be sufficient to escape
Chrome's sandbox. To make sure that the special powers granted to WebUI pages
are safe, WebUI pages are restricted in what they can do:
* WebUI pages cannot embed http/https resources
* WebUI pages cannot issue http/https fetches
In the rare case that a WebUI page really needs to include web content, the safe
way to do this is by using an `