ZenBrowserMirrors/docs
1
0
Fork 0
mirror of https://github.com/zen-browser/docs.git synced 2025-07-07 17:05:34 +02:00
Code Issues Projects Releases Packages Wiki Activity

improved examples and page structure

Browse source
This commit is contained in:
nitro 2024-09-16 23:03:39 +02:00
parent 368e789f8d
commit eca2c9fc5d
1 changed files with 60 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

183
content/themes-store/themes-marketplace-preferences.md
View file

@ -6,22 +6,20 @@ title: Themes Store Preferences ⚙️
The `preferences.json` file allows theme developers to define custom preferences that control the behavior and appearance of themes in the Zen Browser. Each preference is defined with a `property`, a `label`, a `type`, and optionally `options` (for dropdown preferences). The `preferences.json` file contains a list of these preference objects at its root. The `preferences.json` file allows theme developers to define custom preferences that control the behavior and appearance of themes in the Zen Browser. Each preference is defined with a `property`, a `label`, a `type`, and optionally `options` (for dropdown preferences). The `preferences.json` file contains a list of these preference objects at its root.
## Preferences.json structure
### 1. **Property** Format
The `property` field is a string that should follow Firefox's preference naming schema, similar to `about:config` entries. The `property` value can be any valid string that aligns with this schema.
For example:
- `theme.mytheme.background_color`
- `theme.mytheme.enable_dark_mode`
### Example Preferences ## Theme Preferences
#### **1. Checkbox Preference** ### Preference Types
```json | **Property** | **Type** | **Accepted Values** |
|-------------------------------------------|------------|--------------------------------------|
| `checkbox` | Boolean | `true`, `false` |
| `dropdown` | Array[Options] | The `value` of an option must be a string (`"blue"`) or an integer (`1`)|
### Checkbox preferences
```json title="Checkbox Example"
{ {
"property": "theme.mytheme.enable_dark_mode", "property": "theme.mytheme.enable_dark_mode",
"label": "Enable dark mode", "label": "Enable dark mode",
@ -29,21 +27,27 @@ For example:
} }
``` ```
#### **2. Dropdown Preference** #### Properties
```json The `property` field is a string that should follow Firefox's preference naming schema, similar to `about:config` entries. The `property` name can be any valid string that aligns with this schema.
For example: `theme.mytheme.background_color`
#### Labels
The `label` field is the description that will be visible to users in the Zen Mods settings page.
This field accepts a string and allows white space.
---
### Dropdown preferences
```json title="Dropdown Example"
{ {
"property": "theme.mytheme.background_color", "property": "theme.mytheme.background_color",
"label": "Background color", "label": "Background color",
"type": "dropdown", "type": "dropdown",
"options": [ "options": [
{ {
"label": "Light", "label": "Green",
"value": "light" "value": "green"
},
{
"label": "Dark",
"value": "dark"
}, },
{ {
"label": "Blue", "label": "Blue",
@ -53,41 +57,11 @@ For example:
} }
``` ```
--- Dropdown preferences also contain property and label fields. What separates dropdown menus from checkboxes is that they allow multiple options.
### Property Types and Accepted Values The `options` field is an array of option objects, only available for the `dropdown` type. This field must be an array containing one or more option objects.
| **Property** | **Type** | **Accepted Values** | ```json
|-------------------------------------------|------------|--------------------------------------|
| `checkbox` | Boolean | `true`, `false` |
| `dropdown` | Array[Options] | The `value` of an option must be a string (`"blue"`) or an integer (`1`)|
---
### Detailed Explanation of Fields
#### 1. **label**
- **Description:** The `label` field is the description that will be visible in the Zen Browser configuration for the user to see.
- **Accepted Values:** It accepts a string. White spaces can be used.
Example:
```json title="Example" {2}
{
"property": "theme.mytheme.enable_dark_mode",
"label": "Enable dark mode",
"type": "checkbox"
}
```
#### 2. **options**
- **Description:** The `options` field is an array of option objects, only available for the `dropdown` type.
- **Accepted Values:** This field must be an array containing one or more option objects.
```json title="Example" {5-14}
{
"property": "theme.mytheme.background_color",
"label": "Background color",
"type": "dropdown",
"options": [ "options": [
{ {
"label": "Light", "label": "Light",
@ -98,45 +72,29 @@ Example:
"value": "dark" "value": "dark"
} }
] ]
}
``` ```
#### 3. **option objects** Each option object defines a possible value for the dropdown menu. It contains two fields: `label` and `value`.
- **Description:** Each option object in the `options` array defines a possible value for the dropdown menu. It contains two fields: `label` and `value`.
- **Fields:**
- **label:** A string displayed in the dropdown menu (can include white spaces).
- **value:** The value that will be assigned as a CSS property. Only `string` or `int` values are valid. Strings cannot contain white spaces or special characters.
```json title="Example" {6-9} * The `label` is the description that will be displayed in the dropdown menu. This field accepts a string and allows white space.
* The `value` field contains the value that will be assigned as a CSS property. Only `string` or `int` values are valid. Strings may not contain white space or special characters.
```json title="Example"
{ {
"property": "theme.mytheme.background_color", "label": "Green",
"label": "Background color", "value": "green" // valid string
"type": "dropdown",
"options": [
{
"label": "Light",
"value": "light" // valid string
},
{
"label": "Dark",
"value": "dark" // valid string
},
{
"label": "Blue",
"value": 3 // valid integer
}
]
} }
``` ```
Invalid Example: ```json title="Invalid Example" {3}
```json
{ {
"label": "Invalid option", "label": "Invalid option",
"value": [] // invalid, only string/int are allowed "value": [] // invalid, only string/int are allowed
} }
``` ```
---
<details> <details>
<summary><font weight="bold" size=4.75><b>See Full Example</b></font></summary> <summary><font weight="bold" size=4.75><b>See Full Example</b></font></summary>
@ -155,12 +113,8 @@ Below is a full example of what a `preferences.json` file might look like with m
"type": "dropdown", "type": "dropdown",
"options": [ "options": [
{ {
"label": "Light", "label": "Green",
"value": "light" "value": "green"
},
{
"label": "Dark",
"value": "dark"
}, },
{ {
"label": "Blue", "label": "Blue",
@ -189,7 +143,7 @@ In this example:
Once you have defined your preferences in the `preferences.json` file, you can use them in your theme’s CSS to modify the appearance or behavior based on the user’s selections. Once you have defined your preferences in the `preferences.json` file, you can use them in your theme’s CSS to modify the appearance or behavior based on the user’s selections.
### 1. Using Checkbox Preferences `-moz-bool-pref` ### Checkbox Preferences
Checkbox preferences can be detected in your CSS using the `-moz-bool-pref` media query, which evaluates the boolean value (`true` or `false`) of a checkbox preference. Checkbox preferences can be detected in your CSS using the `-moz-bool-pref` media query, which evaluates the boolean value (`true` or `false`) of a checkbox preference.
@ -214,14 +168,19 @@ You can use the following CSS to change the background color when the dark mode
} }
``` ```
In this example: You can also have negative conditions
- The background color changes to black, and the text color changes to white if the `enable_dark_mode` checkbox is checked (set to `true`). ```css
@media not (-moz-bool-pref: "theme.mytheme.enable_dark_mode")
```
### 2. Using Dropdown Preferences `body:has(#theme-<theme-name>[<attribute-name>="<value>"])` ### Dropdown Preferences
> [!attention] > [!attention]
> In the theme's CSS file, the `property` defined in the `preferences.json` using the `"dropdown"` type will be called exactly as defined, but with one key difference: **dots (`.`) in the `property` name are replaced with hyphens (`-`)**. For example: - `theme.mytheme.background_color` in the `preferences.json` file becomes `theme-mytheme-background_color` in the CSS file. This transformation ensures that the property can be used as an attribute selector or inside a media query. > `property` fields defined in `preferences.json` using the `"dropdown"` type will have one key difference when used in your themes CSS: **dots (`.`) in the `property` name are replaced with hyphens (`-`)**.
>
> E.g. `theme.mytheme.background_color` becomes `theme-mytheme-background_color` in the CSS file.
> This transformation ensures that the property can be used as an attribute selector or inside a media query.
For dropdown preferences, you can detect the selected value using the `:has(){:css}` CSS pseudo-class, which applies styles based on the selected attribute and value in the DOM. For dropdown preferences, you can detect the selected value using the `:has(){:css}` CSS pseudo-class, which applies styles based on the selected attribute and value in the DOM.
@ -234,12 +193,8 @@ For example, if you have a preference to select the background color from a drop
"type": "dropdown", "type": "dropdown",
"options": [ "options": [
{ {
"label": "Light", "label": "Green",
"value": "light" "value": "green"
},
{
"label": "Dark",
"value": "dark"
}, },
{ {
"label": "Blue", "label": "Blue",
@ -252,21 +207,15 @@ For example, if you have a preference to select the background color from a drop
You can use the following CSS to change the background color based on the selected value: You can use the following CSS to change the background color based on the selected value:
```css {2,8,14} ```css {2,8,14}
/* Light background */ /* Green background */
body:has(#theme-mytheme[theme-mytheme-background_color="light"]) { body:has(#theme-mytheme[theme-mytheme-background_color="green"]) {
background-color: #fff; background-color: #008000;
color: #000; color: #000;
} }
/* Dark background */
body:has(#theme-mytheme[theme-mytheme-background_color="dark"]) {
background-color: #000;
color: #fff;
}
/* Blue background */ /* Blue background */
body:has(#theme-mytheme[theme-mytheme-background_color="blue"]) { body:has(#theme-mytheme[theme-mytheme-background_color="blue"]) {
background-color: #001f3f; background-color: #0000ff;
color: #fff; color: #fff;
} }
``` ```
@ -295,12 +244,8 @@ Suppose your `preferences.json` file includes these two preferences:
"type": "dropdown", "type": "dropdown",
"options": [ "options": [
{ {
"label": "Light", "label": "Green",
"value": "light" "value": "green"
},
{
"label": "Dark",
"value": "dark"
}, },
{ {
"label": "Blue", "label": "Blue",
@ -323,18 +268,13 @@ You can combine the CSS like this:
} }
/* Dropdown for background color selection */ /* Dropdown for background color selection */
body:has(#theme-mytheme[theme-mytheme-background_color="light"]) { body:has(#theme-mytheme[theme-mytheme-background_color="green"]) {
background-color: #fff; background-color: #008000;
color: #000; color: #000;
} }
body:has(#theme-mytheme[theme-mytheme-background_color="dark"]) {
background-color: #000;
color: #fff;
}
body:has(#theme-mytheme[theme-mytheme-background_color="blue"]) { body:has(#theme-mytheme[theme-mytheme-background_color="blue"]) {
background-color: #001f3f; background-color: #0000ff;
color: #fff; color: #fff;
} }
``` ```
@ -345,9 +285,6 @@ This allows users to:
</details> </details>
> [!info]
> The `-moz-bool-pref` query is used for detecting boolean values (checkboxes), while the `:has(){:css}` pseudo-class with attribute selectors is used for detecting the selected values of dropdowns.
--- ---