1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# MozInputFolder
`moz-input-folder` is a reusable component that provides the ability to browse and pick a folder from the file system. It displays the path and icon of the selected folder to the user. It can also be configured to display custom text if needed.
```html story
<div style={{width: "500px"}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder
label="Save files to"
placeholder="Select folder">
</moz-input-folder>
</div>
```
## Usage guidelines
### When to use
* Use `moz-input-folder` when you want to allow a user to select a directory.
### When not to use
* When users need to select individual files rather than folders.
## Code
The source for `moz-input-folder` can be found under [toolkit/content/widgets/moz-input-folder/](https://searchfox.org/mozilla-central/source/toolkit/content/widgets/moz-input-folder)
## How to use `moz-input-folder`
### Importing the element
Like other custom elements, you should usually be able to rely on `moz-input-folder` getting lazy loaded at the time of first use.
See [this documentation](https://firefox-source-docs.mozilla.org/browser/components/storybook/docs/README.reusable-widgets.stories.html#using-new-design-system-components) for more information on using design system custom elements.
### Setting the `label`
Providing a label for the moz-input-folder component is crucial for usability and accessibility:
* Helps users understand the purpose of the folder picker.
* Improves accessibility by ensuring screen readers can announce the function of the input.
To set a label, use the `label` attribute. In general, the label should be controlled by Fluent.
```html
<moz-input-folder label="Label text"></moz-input-folder>
```
```html story
<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder label="Label text"></moz-input-folder>
</div>
```
### Setting the `description`
In order to set a description, use the `description` attribute.
In general, the description should be controlled by Fluent. This is the the preferred way of setting descriptions since it ensures consistency across instances of `moz-input-folder`.
```html
<moz-input-folder label="Label" description="Description text"></moz-input-folder>
```
```html story
<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder
label="Label"
description="Description text">
</moz-input-folder>
</div>
```
However, `moz-input-folder` does support a `slot` element if your use case is more complex.
```html
<moz-input-folder label="Label">
<span slot="description">A more complex description</span>
</moz-input-folder>
```
```html story
<div style={{width: "500px"}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder label="Label">
<span slot="description">A more <b>complex</b> description</span>
</moz-input-folder>
</div>
```
### Setting the `value`
The `value` attribute of `moz-input-folder` sets the initial folder path displayed in the input field. When a new folder is selected, the `value` gets updated with that folder's path.
```html
<moz-input-folder label="Save files to:" value="/User/Downloads"></moz-input-folder>
```
```html story
<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder label="Save files to:" value="/User/Downloads"></moz-input-folder>
</div>
```
### Setting the `displayValue`
Use `displayValue` property to display something other than a folder path in the input element. Listen to the `moz-input-folder` `change` event to set a `displayValue` after the new folder was selected. The `folder` property represents the selected folder in the file system (`nsIFile` object). You can use properties of the `folder` when setting a `displayValue` (e.g., `folder.path`, `folder.displayName` or `folder.leafName`).
```html
<moz-input-folder label="Save files to:" value="/User/Downloads" displayvalue="Downloads"></moz-input-folder>
```
```js
// Code example
let mozInputFolder = document.querySelector("moz-input-folder");
mozInputFolder.addEventListener(
"change",
() => {
mozInputFolder.displayValue = mozInputFolder.folder.displayName;
}
);
```
```html story
<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder label="Save files to:" value="/User/Downloads" displayvalue="Downloads"></moz-input-folder>
</div>
```
### Setting the `disabled` state
In order to disable the `moz-input-folder`, add `disabled=""` or `disabled` to the markup with no value.
```html
<moz-input-folder label="Label" disabled></moz-input-folder>
```
```html story
<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder label="Label" disabled></moz-input-folder>
</div>
```
### Setting the `accesskey`
`accesskey` defines an keyboard shortcut for the input.
```html
<moz-input-folder label="Label with accesskey" accesskey="L"></moz-input-folder>
```
```html story
<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
<moz-input-folder label="Label with accesskey" accesskey="L"></moz-input-folder>
</div>
```
### Fluent usage
The `label`, `description`, `placeholder` and `accesskey` attributes of `moz-input-folder` will generally be provided via [Fluent attributes](https://mozilla-l10n.github.io/localizer-documentation/tools/fluent/basic_syntax.html#attributes).
The relevant `data-l10n-attrs` are set automatically, so to get things working you just need to supply a `data-l10n-id` as you would with any other element.
For example, the following Fluent messages:
```
moz-input-folder-label =
.label = Save files to
moz-input-folder-placeholder =
.label = Save files to
.placeholder = Select folder
moz-input-folder-description =
.label = Save files to
.description = Description text
.placeholder = Select folder
moz-input-folder-with-accesskey =
.label = Save files to
.accesskey = v
```
would be used to set text and attributes on the different `moz-input-folder` elements as follows:
```html
<moz-input-folder data-l10n-id="moz-input-folder-label"></moz-input-folder>
<moz-input-folder data-l10n-id="moz-input-folder-placeholder"></moz-input-folder>
<moz-input-folder data-l10n-id="moz-input-folder-description"></moz-input-folder>
<moz-input-folder data-l10n-id="moz-input-folder-with-accesskey"></moz-input-folder>
```
|
