chromium/src
0
Fork 0
Code Activity

Update WebUI documentation for AddLocalizedStrings()/AddResourcePaths().

Browse Source 
Move the documentation for these methods out of the utility section, as
https://crrev.com/852357 moved them. Update the example to fix a typo
and make the sample names more generic.

Also update another code example to call these functions, to encourage
readers to use these functions.

Change-Id: Ibc977e1972772feb117a0f83110e360609b6085c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3413795
Reviewed-by: Rebekah Potter <rbpotter@chromium.org>
Commit-Queue: Lei Zhang <thestig@chromium.org>
Cr-Commit-Position: refs/heads/main@{#963076}
This commit is contained in:
Lei Zhang
2022-01-25 18:08:38 +00:00
committed by Chromium LUCI CQ
parent c689b3e209
commit 5b2050836c
2 changed files with 54 additions and 47 deletions

86
docs/webui_explainer.md

@ -305,6 +305,22 @@ 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::AddLocalizedStrings()
Many Web UI data sources need to be set up with a large number of localized
strings. Instead of repeatedly calling <code>AddLocalizedString()</code>, create
an array of all the strings and use <code>AddLocalizedStrings()</code>:
```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::AddResourcePath()
Using an int reference to a grit resource (starts with "IDR" and lives in a .grd
@ -321,6 +337,33 @@ 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::AddResourcePaths()
Similar to the localized strings, many Web UIs need to add a large number of
resource paths. In this case, use <code>AddResourcePaths()</code> to
replace repeated calls to <code>AddResourcePath()</code>.
```c++
static constexpr webui::ResourcePath kResources[] = {
{"browser_api.js", IDR_BROWSER_API_JS},
{"constants.js", IDR_CONSTANTS_JS},
{"controller.js", IDR_CONTROLLER_JS},
};
source->AddResourcePaths(kResources);
```
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
<code>webui::ResourcePath</code> array named <code>kPrintPreviewResources</code>
and a <code>size\_t kPrintPreviewResourcesSize</code>. All the resources in this
resource map can be added as follows:
```c++
source->AddResourcePaths(
base::make_span(kPrintPreviewResources, kPrintPreviewResourcesSize));
```
### WebUIDataSource::AddBoolean()
Often a page needs to know whether a feature is enabled. This is a good use case
@ -348,49 +391,6 @@ make sure to call <code>WebUIDataSource::Update()</code> when the value changes.
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 <code>AddLocalizedString()</code>, create
an array of all the strings and use <code>AddLocalizedStrings()</code>:
```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 <code>AddResourcePaths()</code> to
replace repeated calls to <code>AddResourcePath()</code>.
```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
<code>webui::ResourcePath</code> array named <code>kPrintPreviewResources</code>
and a <code>size\_t kPrintPreviewResourcesSize</code>. 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

15
docs/webui_in_components.md

@ -170,16 +170,23 @@ HelloWorldUI::HelloWorldUI(content::WebUI* web_ui)
content::WebUIDataSource::Create(chrome::kChromeUIHelloWorldHost);
// Localized strings.
html_source->AddLocalizedString("helloWorldTitle", IDS_HELLO_WORLD_TITLE);
html_source->AddLocalizedString("welcomeMessage", IDS_HELLO_WORLD_WELCOME_TEXT);
static constexpr webui::LocalizedString kStrings[] = {
{"helloWorldTitle", IDS_HELLO_WORLD_TITLE},
{"welcomeMessage", IDS_HELLO_WORLD_WELCOME_TEXT},
};
html_source->AddLocalizedStrings(kStrings);
// As a demonstration of passing a variable for JS to use we pass in the name "Bob".
html_source->AddString("userName", "Bob");
html_source->UseStringsJs();
// Add required resources.
html_source->AddResourcePath("hello_world.css", IDR_HELLO_WORLD_CSS);
html_source->AddResourcePath("hello_world.js", IDR_HELLO_WORLD_JS);
static constexpr webui::ResourcePath kResources[] = {
{"hello_world.html", IDR_HELLO_WORLD_HTML},
{"hello_world.css", IDR_HELLO_WORLD_CSS},
{"hello_world.js", IDR_HELLO_WORLD_JS},
};
source->AddResourcePaths(kResources);
html_source->SetDefaultResource(IDR_HELLO_WORLD_HTML);
content::BrowserContext* browser_context =