0

WebUI Documentation: Indicate WebUIConfig should be preferred

Make it more clear in the WebUI docs that the WebUIConfig method should
be preferred to the ChromeWebUIControllerFactory for registering new
WebUIControllers.

Bug: 1317510
Change-Id: I1e505987c94d3440accc617e721e75f1ba46329a
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5029812
Reviewed-by: Demetrios Papadopoulos <dpapad@chromium.org>
Commit-Queue: Rebekah Potter <rbpotter@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1224975}
This commit is contained in:
Rebekah Potter
2023-11-15 16:15:38 +00:00
committed by Chromium LUCI CQ
parent 8a68da1fc8
commit 017ed5447f
2 changed files with 30 additions and 16 deletions

@ -88,23 +88,30 @@ factories contain a list of valid host names. A valid hostname generates a
controller.
In the case of `chrome:` URLs, these factories are registered early in the
browser process lifecycle.
browser process lifecycle. Before the first `WebUIConfig` is registered, the
`WebUIConfigMap` instance is created. This map creates and registers a
factory (`WebUIConfigMapWebUIControllerFactory`) in its constructor.
This factory looks at the global `WebUIConfigMap`, which maps hosts to
`WebUIConfig`s, to see if any of the configs handle the requested URL. It calls
the method on the config to create the corresponding controller if it finds a
config to handle the URL.
```c++
// ChromeBrowserMainParts::PreMainMessageLoopRunImpl():
// Legacy WebUIControllerFactory registration
content::WebUIControllerFactory::RegisterFactory(
ChromeWebUIControllerFactory::GetInstance());
// Factory for all WebUIs using WebUIConfig will be created here.
RegisterChromeWebUIConfigs();
RegisterChromeUntrustedWebUIConfigs();
```
When a URL is requested, a new renderer is created to load the URL, and a
corresponding class in the browser is set up to handle messages from the
renderer to the browser (a `RenderFrameHost`).
One factory that serves WebUI URLs is `WebUIConfigMapWebUIControllerFactory`.
This factory looks at a global map from hosts to `WebUIConfig`s to see if any
of the configs handle the requested URL, and calls a method to create the
corresponding controller if so.
```c++
auto* config = config_map_->GetConfig(browser_context, url);
if (!config)

@ -10,10 +10,7 @@
}
</style>
# Creating WebUI Interfaces outside components/
This guide is based on
[Creating WebUI Interfaces in components](webui_in_components.md).
# Creating WebUI Interfaces
[TOC]
A WebUI page is made of a Polymer single-page application, which communicates
@ -274,11 +271,13 @@ static_library("ui") {
}
```
### Option 1: Add a WebUIConfig class and put it in the WebUIConfigMap
### Preferred method: Add a WebUIConfig class and put it in the WebUIConfigMap
`WebUIConfig`s contain minimal information about the host and scheme served
by the `WebUIController` subclass. You can create a `WebUIConfig` subclass
and register it in the `WebUIConfigMap` to ensure your request handler is
instantiated and used to handle any requests to the desired scheme + host.
by the `WebUIController` subclass. It also can enable or disable the UI for
different conditions (e.g. feature flag status). You can create a
`WebUIConfig` subclass and register it in the `WebUIConfigMap` to ensure your
request handler is instantiated and used to handle any requests to the desired
scheme + host.
`chrome/browser/ui/webui/hello_world/hello_world_ui.h`
```c++
@ -309,6 +308,9 @@ HelloWorldUIConfig::CreateWebUIController(content::WebUI* web_ui,
}
```
Register your config in `chrome_web_ui_configs.cc`, for trusted UIs, or
`chrome_untrusted_web_ui_configs.cc` for untrusted UIs.
`chrome/browser/ui/webui/chrome_web_ui_configs.cc`
```c++
+ #include "chrome/browser/ui/webui/hello_world/hello_world_ui.h"
@ -316,9 +318,14 @@ HelloWorldUIConfig::CreateWebUIController(content::WebUI* web_ui,
+map.AddWebUIConfig(std::make_unique<hello_world::HelloWorldUIConfig>());
```
### Option 2: Add your WebUI request handler to the Chrome WebUI factory
### Old method: Add your WebUI request handler to the Chrome WebUI factory
The Chrome WebUI factory is another way to setup your new request handler.
The Chrome WebUI factory is another way to setup your new request handler. This
is how many older WebUIs in Chrome are registered, since not all UIs have been
migrated to use the newer `WebUIConfig` (see
[migration bug](https://crbug.com/1317510)). Only use this method for a new UI
if the approach above using `WebUIConfig` does not work, and notify WebUI
`PLATFORM_OWNERS`.
`chrome/browser/ui/webui/chrome_web_ui_controller_factory.cc:`
```c++