This guide is based on Creating WebUI Interfaces in components, and comments from reviewers when creating the ChromeOS emoji picker.
WebUI pages live in chrome/browser/resources. You should create a folder for your project chrome/browser/resources/hello_world. When creating WebUI resources, follow the Web Development Style Guide. For a sample WebUI page you could start with the following files:
chrome/browser/resources/hello_world/hello_world.html
<!DOCTYPE HTML> <html> <head> <meta charset="utf-8"> <link rel="stylesheet" href="hello_world.css"> <script type="module" src="hello_world.js"></script> </head> <body> <h1>Hello World</h1> <div id="example-div"></div> </body> </html>
chrome/browser/resources/hello_world/hello_world.css
body { margin: 0; }
chrome/browser/resources/hello_world/hello_world.js
import './strings.m.js'; import {loadTimeData} from 'chrome://resources/js/load_time_data.m.js'; import {$} from 'chrome://resources/js/util.m.js'; function initialize() { const block = document.createElement('div'); block.innerText = loadTimeData.getString('message'); $('example-div').appendChild(block); } document.addEventListener('DOMContentLoaded', initialize);
Add a BUILD.gn file to get Javascript type checking:
chrome/browser/resources/hello_world/BUILD.gn
import("//third_party/closure_compiler/compile_js.gni")
js_library("hello_world") {
deps = [
"//ui/webui/resources/js:load_time_data.m",
"//ui/webui/resources/js:util.m",
]
}
js_type_check("closure_compile") {
uses_js_modules = true
deps = [ ":hello_world" ]
}
Then refer to the new :closure_compile target from chrome/browser/resources/BUILD.gn:
group("closure_compile) {
deps = [
...
"hello_world:closure_compile"
...
]
Finally, create an OWNERS file for the new folder.
Resources for the browser are stored in grd files. Current best practice is to autogenerate a grd file for your component in the BUILD file we created earlier
chrome/browser/resources/hello_world/BUILD.gn
import("//tools/grit/grit_rule.gni")
import("//ui/webui/resources/tools/generate_grd.gni")
resources_grd_file = "$target_gen_dir/resources.grd"
generate_grd("build_grd") {
grd_prefix = "hello_world"
out_grd = resources_grd_file
input_files = [
"hello_world.css",
"hello_world.html",
"hello_world.js",
]
input_files_base_dir = rebase_path(".", "//")
}
grit("resources") {
enable_input_discovery_for_gn_analyze = false
source = resources_grd_file
deps = [ ":build_grd" ]
outputs = [
"grit/hello_world_resources.h",
"grit/hello_world_resources_map.cc",
"grit/hello_world_resources_map.h",
"hello_world_resources.pak",
]
output_dir = "$root_gen_dir/chrome"
}
Then add the new resource target to chrome/browser/resources/BUILD.gn
group("resources") {
public_deps += [
...
"hello_world:resources"
...
]
}
chrome/common/webui_url_constants.cc:
const char kChromeUIHelloWorldURL[] = "chrome://hello-world/"; const char kChromeUIHelloWorldHost[] = "hello-world";
chrome/common/webui_url_constants.h:
extern const char kChromeUIHelloWorldURL[]; extern const char kChromeUIHelloWorldHost[];
Next we need a class to handle requests to this new resource URL. Typically this will subclass WebUIController (WebUI dialogs will also need another class which will subclass WebDialogDelegate, this is shown later).
chrome/browser/ui/webui/hello_world_ui.h
#ifndef CHROME_BROWSER_UI_WEBUI_HELLO_WORLD_HELLO_WORLD_H_ #define CHROME_BROWSER_UI_WEBUI_HELLO_WORLD_HELLO_WORLD_H_ #include "base/macros.h" #include "content/public/browser/web_ui_controller.h" // The WebUI for chrome://hello-world class HelloWorldUI : public content::WebUIController { public: explicit HelloWorldUI(content::WebUI* web_ui); ~HelloWorldUI() override; private: }; #endif // CHROME_BROWSER_UI_WEBUI_HELLO_WORLD_HELLO_WORLD_H_
chrome/browser/ui/webui/hello_world_ui.cc
#include "chrome/browser/ui/webui/hello_world_ui.h" #include "chrome/browser/ui/webui/webui_util.h" #include "components/hello_world/constants.h" #include "content/public/browser/browser_context.h" #include "content/public/browser/web_contents.h" #include "content/public/browser/web_ui.h" #include "content/public/browser/web_ui_data_source.h" HelloWorldUI::HelloWorldUI(content::WebUI* web_ui) : content::WebUIController(web_ui) { // Set up the chrome://hello-world source. content::WebUIDataSource* html_source = content::WebUIDataSource::Create(chrome::kChromeUIHelloWorldHost); // As a demonstration of passing a variable for JS to use we pass in some // a simple message. html_source->AddString("message", "Hello World!"); html_source->UseStringsJs(); // Add required resources. webui::SetupWUIDataSource(html_source, base::make_span(kHelloWorldResources, kHelloWorldResourcesSize), IDR_HELLO_WORLD_HELLO_WORLD_HTML); content::BrowserContext* browser_context = web_ui->GetWebContents()->GetBrowserContext(); content::WebUIDataSource::Add(browser_context, html_source); } HelloWorldUI::~HelloWorldUI() {}
To ensure that your code actually gets compiled, you need to add it to chrome/browser/ui/BUILD.gn:
static_library("ui") {
sources = [
... (lots)
"webui/hello_world/hello_world_ui.cc",
"webui/hello_world/hello_world_ui.h",
The Chrome WebUI factory is where you setup your new request handler.
chrome/browser/ui/webui/chrome_web_ui_controller_factory.cc:
+ #include "chrome/browser/ui/webui/hello_world_ui.h" ... + if (url.host() == chrome::kChromeUIHelloWorldHost) + return &NewWebUI<HelloWorldUI>;
You're done! Assuming no errors (because everyone gets their code perfect the first time) you should be able to compile and run chrome and navigate to chrome://hello-world/ and see your nifty welcome text!
Instead of having a full page for your WebUI, you might want a dialog in order to have a fully independent window. To do that, some small changes are needed to your code. First, we need to add a new class which inherits from ui::WebDialogDelegate. The easiest way to do that is to edit the hello_world_ui.* files
chrome/browser/ui/webui/hello_world_ui.h
// Leave the old content, but add this new code class HelloWorldDialog : public ui::WebDialogDelegate { public: static void Show(); ~HelloWorldDialog() override; private: HelloWorldDialog(); // ui::WebDialogDelegate: ui::ModalType GetDialogModalType() const override; base::string16 GetDialogTitle() const override; GURL GetDialogContentURL() const override; void GetWebUIMessageHandlers( std::vector<content::WebUIMessageHandler*>* handlers) const override; void GetDialogSize(gfx::Size* size) const override; std::string GetDialogArgs() const override; void OnDialogShown(content::WebUI* webui) override; void OnDialogClosed(const std::string& json_retval) override; void OnCloseContents(content::WebContents* source, bool* out_close_dialog) override; bool ShouldShowDialogTitle() const override; content::WebUI* webui_ = nullptr; DISALLOW_COPY_AND_ASSIGN(HelloWorldDialog); };
chrome/browser/ui/webui/hello_world_ui.cc
// Leave the old content, but add this new stuff HelloWorldDialog::HelloWorldDialog() {} void HelloWorldDialog::Show() { chrome::ShowWebDialog(nullptr, ProfileManager::GetActiveUserProfile(), new HelloWorldDialog()); } ui::ModalType HelloWorldDialog::GetDialogModalType() const { return ui::MODAL_TYPE_NONE; } base::string16 HelloWorldDialog::GetDialogTitle() const { return base::UTF8ToUTF16("Hello world"); } GURL HelloWorldDialog::GetDialogContentURL() const { return GURL(chrome::kChromeUIHelloWorldURL[); } void HelloWorldDialog::GetWebUIMessageHandlers( std::vector<content::WebUIMessageHandler*>* handlers) const {} void HelloWorldDialog::GetDialogSize(gfx::Size* size) const { const int kDefaultWidth = 544; const int kDefaultHeight = 628; size->SetSize(kDefaultWidth, kDefaultHeight); } std::string HelloWorldDialog::GetDialogArgs() const { return ""; } void HelloWorldDialog::OnDialogShown(content::WebUI* webui) { webui_ = webui; } void HelloWorldDialog::OnDialogClosed(const std::string& json_retval) { delete this; } void HelloWorldDialog::OnCloseContents(content::WebContents* source, bool* out_close_dialog) { *out_close_dialog = true; } bool HelloWorldDialog::ShouldShowDialogTitle() const { return true; } HelloWorldDialog::~HelloWorldDialog() = default;
Finally, you will need to do something to actually show your dialog, which can be done by calling HelloWorldDialog::Show().