Implement theme experiments
Categories
(WebExtensions :: Themes, enhancement, P5)
Tracking
(firefox63 fixed)
| Tracking | Status | |
|---|---|---|
| firefox63 | --- | fixed |
People
(Reporter: mikedeboer, Assigned: ntim)
References
(Blocks 1 open bug)
Details
(Keywords: dev-doc-complete, Whiteboard: triaged [ntim-intern-project])
User Story
As a theme author I’d like to be able to propose new properties that will allow all theme authors to style different parts of the browser using the following API:
```json
{
"manifest_version": 2,
"name": "Moar Custom Icons",
"description": "Example of a theme experiment",
"version": "1.0",
"applications": {
"gecko": {
"id": "moar-custom-icons@example.com",
"strict_min_version": "57.0",
"strict_max_version": "65.*"
}
},
"icons": {
"48": "icon.png",
"96": "icon@2x.png"
},
"theme": {
"colors": {
"popup_affordance": [128,128,128]
},
"images": {
"headerURL": "image.jpeg",
"theme_toolbar": "toolbar.jpg"
}
},
"theme_experiment": {
"stylesheet": "style.css", // optional
"colors": {
"popup_affordance": "arrowpanel-dimmed"
},
"images": {
"theme_toolbar": "toolbar-bgimage"
},
"properties": {
"toolbar_image_alignment": "toolbar-bgalignment"
}
}
}
```
Attachments
(4 files)
Whiteboard session at SF All Hands
|
||
Updated•7 years ago
|
|
||
Comment 1•7 years ago
|
||
|
Assignee | |
Updated•7 years ago
|
|
||
Comment 2•7 years ago
|
||
|
||
Comment 3•7 years ago
|
||
| Comment hidden (mozreview-request) |
|
|
Assignee | |
Comment 5•7 years ago
|
||
|
|
||
Comment 6•7 years ago
|
||
|
|
Assignee | |
Comment 7•7 years ago
|
||
|
Reporter | |
Comment 8•7 years ago
|
||
|
|
||
Comment 9•7 years ago
|
||
|
|
Assignee | |
Updated•6 years ago
|
|
|
Assignee | |
Comment 11•6 years ago
|
||
|
|
Assignee | |
Updated•6 years ago
|
|
|
Reporter | |
Comment 12•6 years ago
|
||
|
||
Updated•6 years ago
|
|
|
||
Updated•6 years ago
|
|
|
||
Comment 13•6 years ago
|
||
| Comment hidden (mozreview-request) |
|
|
Assignee | |
Updated•6 years ago
|
| Comment hidden (mozreview-request) |
|
||
Comment 16•6 years ago
|
||
| mozreview-review | ||
|
|
||
Comment 17•6 years ago
|
||
| mozreview-review | ||
| Comment hidden (mozreview-request) |
|
|
||
Comment 19•6 years ago
|
||
| mozreview-review | ||
| Comment hidden (mozreview-request) |
|
|
||
Comment 21•6 years ago
|
||
| mozreview-review | ||
| Comment hidden (mozreview-request) |
|
|
||
Comment 23•6 years ago
|
||
| mozreview-review | ||
|
|
||
Updated•6 years ago
|
|
|
||
Comment 24•6 years ago
|
||
| mozreview-review | ||
|
|
||
Comment 25•6 years ago
|
||
| mozreview-review | ||
| Comment hidden (mozreview-request) |
| Comment hidden (mozreview-request) |
|
|
Assignee | |
Comment 28•6 years ago
|
||
|
|
||
Comment 29•6 years ago
|
||
| mozreview-review | ||
|
|
||
Comment 30•6 years ago
|
||
| mozreview-review | ||
|
|
||
Comment 31•6 years ago
|
||
| Comment hidden (mozreview-request) |
|
||
Comment 33•6 years ago
|
||
|
||
Comment 34•6 years ago
|
||
|
|
||
Comment 35•6 years ago
|
||
| Comment hidden (mozreview-request) |
|
|
Assignee | |
Updated•6 years ago
|
|
|
||
Comment 37•6 years ago
|
||
|
|
Assignee | |
Updated•6 years ago
|
|
|
||
Comment 39•6 years ago
|
||
| Comment hidden (mozreview-request) |
|
|
||
Comment 41•6 years ago
|
||
|
|
Assignee | |
Updated•6 years ago
|
|
|
||
Comment 42•6 years ago
|
||
|
|
||
Comment 43•6 years ago
|
||
| Comment hidden (mozreview-request) |
| Comment hidden (mozreview-request) |
| Comment hidden (mozreview-request) |
| Comment hidden (mozreview-request) |
| Comment hidden (mozreview-request) |
|
||
Comment 49•6 years ago
|
||
| mozreview-review | ||
|
|
||
Comment 50•6 years ago
|
||
|
||
Comment 51•6 years ago
|
||
| bugherder | ||
|
|
Assignee | |
Updated•6 years ago
|
|
||
Comment 52•6 years ago
|
||
| bugherder | ||
|
|
Assignee | |
Updated•6 years ago
|
|
||
Comment 53•6 years ago
|
||
|
|
Assignee | |
Updated•6 years ago
|
|
||
Comment 54•5 years ago
|
||
Can I confirm the documentation updates required:
-
in summary: this is a new manifest key
theme_experimentproviding for the properties:stylesheet,images, andproperties. It enables developers to do two things: -
override page CSS and therefore align look of all pages with the browser theme.
-
override the images used for icons in the browser UI and apply properties to those images, enabling the developer to more deeply customize the UI.
It is supported on desktop Firefox only from version 63. -
manifest keys pages: add a new page for
theme_experimentwith the following content:
Type: Object
Mandatory: No
Example:
"theme_experiment": {
"stylesheet": "style.css", // optional
"colors": {
"popup_affordance": "arrowpanel-dimmed"
},
"images": {
"theme_toolbar": "toolbar-bgimage"
},
"properties": {
"toolbar_image_alignment": "toolbar-bgalignment"
}
}
Theme experiments enable to features:
- overriding the CSS of pages so that the presentation of pages more closely matches the theme applied to the browser UI.
- specification of new images to use as content within Firefox UI components, thus enabling the UI to be more deeply customized. MSyntax
The theme key is an object that takes the following properties:
| Name | Type | Description |
|---|---|---|
stylesheet |
Object | Provides for the optional specification of a stylesheet and stylesheet elements. The stylesheet elements are either added to the specified stylesheet or used as stylesheet overrides. |
images |
Object | Provides for the specification of images to override theme elements. A list of theme element names is available (where?) |
properties |
Object | Provides for the specification of additional properties for theme elements. The listed theme properties is available (where?) |
- browser compatibility data: add a compatibility file for
theme_experimentand include the propertiesstylesheet,images, andpropertiesindicating their availability from Firefox for desktop version 63.
|
|
Assignee | |
Comment 55•5 years ago
|
||
Sorry for not providing much detail in this bug. Here's a summary of how it works:
This feature allows defining new theme properties for styling parts of the Firefox interface that the built-in properties don't cover. One very important thing to note is that the feature is limited to Developer Edition and Nightly channels behind the extensions.legacy.enabled preference.
The stylesheet is injected inside the Firefox interface and lets you define CSS variables that can then be mapped in the colors, images and properties objects to new theme properties.
For example, I could have a style.css file which has:
#reload-button {
fill: var(--reload-button-color);
}
(the #reload-button ID references to Firefox's internal code, and --reload-button-color is a name you make up).
and then in the manifest.json file, I could use:
"theme_experiment": {
"stylesheet": "style.css",
"colors": {
"reload_button": "--reload-button-color"
}
}
and you can use reload_button as any other theme property:
"theme": {
"colors": {
"reload_button": "orange"
}
}
which would make the reload icon color orange. You can also use this property in browser.theme.update() like other property.
images and properties work pretty similarly to colors.
Without stylesheet, you can still use this feature to map internal CSS variables that Firefox defines (like --arrowpanel-dimmed) to new theme properties. There isn't an exhaustive list of those anywhere, since the feature is mostly about defining new theme properties using Firefox internals.
Though I think most of the usefulness from this feature would come from the stylesheet feature, given that it can inject arbitrary CSS into the Firefox UI and hence have a lot of power.
Note that this feature could change at any time (though it hasn't so far), since it's experimental and only exposed to Nightly/Developer Edition.
Please let me know if you have any questions :)
|
|
||
Comment 56•5 years ago
|
||
Hi Tim,
I've attached my work in progress writeup below, but also have some questions/requests:
- given that you can't use this to release a theme, what is the purpose? Is it simply to give developers the option to play around? could it lead to a feature For the release version of Firefox?
- why wasn't this done by providing a set of hidden/experimental properties in
theme? - I'm still somewhat unclear what the advantage of defining the stylesheet given that all you appear to do is map a Firefox UI component ID to an arbitrary name which in there then is in turn mapped to an arbitrary name for a key view using
theme. Why isn't it easier simply to map the Firefox UI component ID to the key property intheme_experiment? - If you don't make use of the stylesheet, in your example would you define
"colors": {"reload_button": "#reload-button"}? - Where can I find a list of/lookup/discover the Firefox UI component ID?
Thanks!
<table>
<tbody>
<tr>
<td>Type</td>
<td>Object</td>
</tr>
<tr>
<td>Mandatory</td>
<td>No</td>
</tr>
<tr>
<td>Example</td>
<td><pre>"theme_experiment": {
"stylesheet": "style.css",
"colors": {
"popup_affordance": "arrowpanel-dimmed"
},
"images": {
"theme_toolbar": "toolbar-bgimage"
},
"properties": {
"toolbar_image_alignment": "toolbar-bgalignment"
}
} </pre>
</td>
</tr>
</tbody>
</table>
This key enables new theme key properties for the Firefox interface to be defined. This is done by either creating a stylesheet that provides mapping between the Firefox internal ID for a UI element feature and an arbitrary … ( to be completed)
The stylesheet is injected inside the Firefox interface and lets you define CSS variables that can then be mapped in the colors, images and properties objects to new theme properties.
Without stylesheet, you can still use this feature to map internal CSS variables that Firefox defines (like --arrowpanel-dimmed) to new theme properties. There isn't an exhaustive list of those anywhere, since the feature is mostly about defining new theme properties using Firefox internals.
Note: This key is only available for use in Firefox Developer Edition and Firefox Nightly channels and requires the extensions.legacy.enabled preference to be enabled.
** Warning**: This feature is experimental and could be subject to change.
Syntax
The theme key is an object that takes the following properties:
| Name | Type | Description |
|---|---|---|
stylesheet |
String | Name of the stylesheet providing mapping information for images and properties. |
images |
Object | Details of mappings between UI element Firefox internal IDs for images and property names to be used in themes. |
colors |
Object | Details of mappings between UI element Firefox internal IDs for colors and property names to be used in themes. |
properties |
Object | Details of mappings between UI element Firefox internal IDs for properties and property names to be used in themes. |
A list of UI element Firefox internal IDs is available (where?)
Examples
This example uses a stylesheet named style.css to provide the ability to define a color for the browser reload button in the theme key.
The stylesheet defines:
#reload-button {
fill: var(--reload-button-color);
}
where #reload-button is the Firefox internal ID for the reload button and --reload-button-color is an arbitrary name.
In the manifest.json file, --reload-button-color is then mapped to the name to be used in the theme colors property:
"theme_experiment": {
"stylesheet": "style.css",
"colors": {
"reload_button": "--reload-button-color"
}
}
Then reload_button is used in the same way as any other theme property:
"theme": {
"colors": {
"reload_button": "orange"
}
}
This has the effect of making the reload icon orange.
(add image)
This property can also be used in browser.theme.update(). images and properties work in a similar way to colors.
|
|
Assignee | |
Comment 57•5 years ago
|
||
given that you can't use this to release a theme, what is the purpose? Is it simply to give developers the option to play around? could it lead to a feature For the release version of Firefox?
Same purpose as WebExtension experiments, propose new theming API features for inclusion in Firefox.
why wasn't this done by providing a set of hidden/experimental properties in theme?
We wouldn't be able to cover everyone's needs, so it's better that extension developers define the experiment themselves.
I'm still somewhat unclear what the advantage of defining the stylesheet given that all you appear to do is map a Firefox UI component ID to an arbitrary name which in there then is in turn mapped to an arbitrary name for a key view using theme. Why isn't it easier simply to map the Firefox UI component ID to the key property in theme_experiment ?
The mapping maps a key property in theme_experiment to a Firefox UI CSS variable, to a not UI element/component ID. The stylesheet lets you define those Firefox UI CSS variables.
Also, CSS variables can be used in a more creative way then the example I showed above, a more crazy example would be:
#reload-button {
fill: var(--reload-button-color);
}
#reload-button:hover {
background-color: var(--reload-button-color);
fill: white;
}
If you don't make use of the stylesheet, in your example would you define "colors": {"reload_button": "#reload-button"}?
That simply wouldn't work. The value needs to be defined CSS variable, hence why the stylesheet is useful, since it allows to define new CSS variables.
If you don't make use of the stylesheet, you can only map to CSS variables (not component IDs) that Firefox already defines internally. There's unfortunately not centralized place to find all the CSS vars, but by inspecting through the browser toolbox, it's possible to find them.
https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox
Where can I find a list of/lookup/discover the Firefox UI component ID?
You can inspect the Firefox interface using the Browser Toolbox.
|
|
||
Comment 58•5 years ago
|
||
Hi Tim, thanks for your feedback. Here is my final draft for the MDN content. do you have any further comments?
| Type | Object |
| Mandatory | No |
| Example | "theme_experiment": { <br> "stylesheet":<br>"style.css",<br>"colors": {<br> "popup_affordance": "arrowpanel-dimmed" <br> },<br> "images":<br>{<br>"theme_toolbar": "toolbar-bgimage"<br>},<br>"properties": {<br>"toolbar_image_alignment":<br>"toolbar-bgalignment"<br>}<br>} |
This key enables experimental theme key properties for the Firefox interface to be defined. These experiments are a precursor to proposing new theme features for inclusion in Firefox. Experimentation is done by:
- creating a stylesheet that defines mappings between internal IDs for Firefox UI element features and arbitrary CSS variables. The CSS variables are then mapped in the
colors,imagesandpropertiesobjects to newthemekey properties. - (without a stylesheet) using
colors,imagesandpropertiesto map internal Firefox CSS variables, such as--arrowpanel-dimmedto newthemekey properties. This option limits experimentation to UI components that are associated with a inbuilt CSS variable.
To discover the internal IDs for Firefox UI elements or internal Firefox CSS variables use the browser toolbox.
Note: This key is only available for use in Firefox Developer Edition and Firefox Nightly channels and requires the extensions.legacy.enabled preference to be enabled.
Warning: This feature is experimental and could be subject to change.
Syntax
The theme key is an object that takes the following properties:
| Name | Type | Description |
|---|---|---|
stylesheet |
String | Name of a stylesheet providing mapping of Firefox UI element feature internal IDs to CSS variables. |
images |
Object | Mappings of CSS variables (as defined in Firefox or by the stylesheet defined instylesheet) to images property names for use in themes. |
colors |
Object | Mappings of CSS variables (as defined in Firefox or by the stylesheet defined instylesheet) to colors property names for use in themes. |
properties |
Object | Mappings of CSS variables (as defined in Firefox or by the stylesheet defined instylesheet) to properties property names for use in themes. |
Examples
This example uses a stylesheet named style.css to provide the ability to define a color for the browser reload button in the themekey.
The stylesheet defines:
#reload-button {
fill: var(--reload-button-color);
}
where #reload-button is the Firefox internal ID for the reload button and --reload-button-color is an arbitrary name.
In the manifest.json file, --reload-button-coloris then mapped to the name to be used in the theme``colorsproperty:
"theme_experiment": {
"stylesheet": "style.css",
"colors": {
"reload_button": "--reload-button-color"
}
}
Then reload_button is used in the same way as any other theme property:
"theme": {
"colors": {
"reload_button": "reload_button"
}
}
This has the effect of making the reload icon orange.
(image)
This property can also be used in browser.theme.update(). images and properties work in a similar way to colors.
|
|
Assignee | |
Comment 59•5 years ago
|
||
Looks great, thanks!
Some small nits:
- "internal IDs" should probably "internal CSS selectors" given that you can use other CSS selectors too.
- In the table, I'm not sure why
themesis a code quote, I think it should just be a normal word since it's not referring to any code.
needinfo'ing Jared/Mike if they have any extra feedback.
|
|
||
Comment 60•5 years ago
|
||
Thanks Tim, I'll start preparing the content for MDN pending feedback from Jared and Mike.
|
|
||
Comment 61•5 years ago
|
||
Hi Jared/Mike, do you have any feedback on the proposed content, or can we go ahead and publish?
|
|
||
Comment 62•5 years ago
|
||
FYI Tim, Jered, and Mike new pages now on MDN: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme_experiment If you have any further comments, please let me know or edit the page directly. Thank you!
|
|
||
Updated•5 years ago
|
|
|
||
Updated•5 years ago
|
Description
•