Password
<et2-password> | Et2Password
Examples
A password is a textbox whose characters are never shown while typing.
Everything Et2Textbox can do - label, helpText, required,
minlength, placeholder - works here too.
The examples on this page are plain HTML rather than a template, so they set
type="password" themselves. Read from a template, the widget sets it for you and you never
write it.
Basic
<et2-password type="password" label="Password" value="correct horse battery staple"></et2-password>
When it is only being shown
A readonly password is et2-password_ro, which templates get automatically the way every other
_ro widget is chosen - readonly in a template, and every customfield of type
passwd outside an edit dialog.
It says whether a password is set and nothing else: anything stored shows as ***, nothing
stored shows nothing. It is deliberately not this widget with its input disabled, because that one is given
the stored password so it can offer to reveal it - which is worth doing in a dialog somebody opened, and not
worth doing once per row of a list.
<et2-password_ro label="Stored password" value="correct horse battery staple"></et2-password_ro>
Letting the user look
viewable adds an eye button that switches the field to plain text, for a password the user is
allowed to read back - a stored account password, not their own login.
<et2-password type="password" label="Stored password" value="correct horse battery staple" viewable></et2-password>
Use that name and no other. The server decides from the template’s own attributes whether to send the
password to the client at all, and viewable is what it looks for - a field that shows an eye
button the server masked the value for reveals nothing but asterisks. togglePassword is an
older spelling of the same attribute, still accepted but deprecated, and Shoelace’s inherited
password-toggle is ignored in templates for exactly that reason.
Two fields, one password
Nothing links two password fields together on its own; templates ask for the password twice and compare the
two values server side. The second field is conventionally the first field’s id with
_2 appended, which is also the id “suggest password” looks for when it fills both at once.
<et2-password id="password-pair" type="password" label="Password"></et2-password>
<et2-password id="password-pair_2" type="password" label="Repeat password"></et2-password>
Suggesting a password
suggest is the length of password to generate, and adds a button to the field that asks the
server for one. This documentation site has no backend, so a preview of it could only fail
- here is the markup:
<et2-password label="Password" suggest="16"></et2-password>
When the suggestion arrives the field switches to plain text so the user can read what they have been given,
and a second field named <id>_2 is filled with the same value.
Encrypted passwords
plaintext (the default) means the value travels and is stored as typed. With
plaintext="false" the value is stored encrypted and reaches the client encrypted, so revealing
it is not a matter of changing the input type: the widget prompts for the user’s own password and has the
server decrypt the stored value first.
Browser autofill
Password managers fill anything that looks like a login form, which is wrong for a field that edits somebody
else’s stored password. autocomplete="new-password" marks the field as not-a-login, and the
widget additionally keeps the input readonly until it is focused, so autofill has nothing to write into.
<et2-password type="password" label="Password" autocomplete="new-password"></et2-password>
Disabled and readonly
disabled greys the field out but keeps it in the DOM, readonly shows it without
allowing any change and submits nothing. Neither reveals the password.
<et2-password type="password" label="Disabled" value="secret" disabled></et2-password>
<et2-password type="password" label="Readonly" value="secret" readonly></et2-password>
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
plaintext
|
Password is plaintext |
boolean
|
true
|
|
suggest
|
Suggest password length (0 for off) |
number
|
0
|
|
viewable
|
Add a button that switches the field to plain text, for a password the user is allowed to read back. This is the name to use. The server decides whether to send the password to the client at all from the template’s own attributes, and it looks for this one (see \EGroupware\Api\Etemplate\Widget\Password::beforeSendToClient()) - a field the client shows a reveal button for, but the server masked, reveals nothing but asterisks. It is also what every password customfield sets, defaulting to true. Implemented on top of SlInput’s passwordToggle, which render() reads. |
boolean
|
- |
Learn more about attributes and properties.
Inherited properties (55)
Et2Widget
| Name | Description |
|---|---|
accesskey |
Accesskey provides a hint for generating a keyboard shortcut for the current element. The attribute value must consist of a single printable character. |
actions |
Set Actions on the widget Each action is defined as an object: move: { type: “drop”, acceptedTypes: “mail”, icon: “move”, caption: “Move to” onExecute: javascript:mail_move” } This will turn the widget into a drop target for “mail” drag types. When “mail” drag types are dropped, the global function mail_move(egwAction action, egwActionObject sender) will be called. The ID of the dragged “mail” will be in sender.id, some information about the sender will be in sender.context. The etemplate2 widget involved can typically be found in action.parent.data.widget, so your handler can operate in the widget context easily. The location varies depending on your action though. It might be action.parent.parent.data.widget To customise how the actions are handled for a particular widget, override _link_actions(). It handles the more widget-specific parts. |
align |
Used by Et2Box to determine alignment. Allowed values are left, right |
class |
CSS Class. This class is applied to the outside, on the web component itself. Due to how WebComponents work, this might not change anything inside the component. |
data |
Set the dataset from a CSV |
deferredProperties |
Any attribute that refers to row content cannot be resolved immediately, but some like booleans cannot stay a string because it’s a boolean attribute. We store them for later, and parse when they’re fully in their row. If you are creating a widget that can go in a nextmatch row, and it has boolean attributes that can change for each row, add those attributes into deferredProperties |
dom_id |
Get the actual DOM ID, which has been prefixed to make sure it’s unique. |
hidden |
The widget is not visible. As far as the user is concerned, the widget does not exist. Widgets hidden with an attribute in the template may not be created in the DOM, and will not return a value. Widgets can be hidden after creation, and they may return a value if hidden this way. |
id |
Get the ID of the widget |
label |
The label of the widget Legacy support for labels with %s that get wrapped around the widget Not the best way go with webComponents - shouldn’t modify their DOM like this |
noLang |
Disable any translations for the widget |
parentId |
Parent is different than what is specified in the template / hierarchy. Widget ID of another node to insert this node into instead of the normal location |
statustext |
Tooltip which is shown for this element on hover |
styles |
WebComponent * |
options |
Get property-values as object |
supportedWidgetClasses |
et2_widget compatability |
SlInput (Shoelace)
| Name | Description |
|---|---|
autocapitalize |
Controls whether and how text input is automatically capitalized as it is entered by the user. |
autocomplete |
Specifies what permission the browser has to provide assistance in filling out form field values. Refer to this page on MDN for available values. |
autocorrect |
Indicates whether the browser’s autocorrect feature is on or off. |
clearable |
Adds a clear button when the input is not empty. |
defaultValue |
The default value of the form control. Primarily used for resetting the form control. |
enterkeyhint |
Used to customize the label or icon of the Enter key on virtual keyboards. |
filled |
Draws a filled input. |
form |
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you to place the form control outside of
a form and associate it with the form that has this id. The form must be in the same
document or shadow root for this to work.
|
helpText |
The input’s help text. If you need to display HTML, use the help-text slot instead.
|
inputmode |
Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual keyboard on supportive devices. |
max |
The input’s maximum value. Only applies to date and number input types. |
maxlength |
The maximum length of input that will be considered valid. |
min |
The input’s minimum value. Only applies to date and number input types. |
minlength |
The minimum length of input that will be considered valid. |
name |
The name of the input, submitted as a name/value pair with form data. |
noSpinButtons |
Hides the browser’s built-in increment/decrement spin buttons for number inputs. |
passwordToggle |
Adds a button to toggle the password’s visibility. Only applies to password types. |
passwordVisible |
Determines whether or not the password is currently visible. Only applies to password input types. |
pattern |
A regular expression pattern to validate input against. |
pill |
Draws a pill-style input with rounded edges. |
readonly |
Makes the input readonly. |
required |
Makes the input a required field. |
size |
The input’s size. |
spellcheck |
Enables spell checking on the input. |
step |
Specifies the granularity that the value must adhere to, or the special value
any which means no stepping is implied, allowing any numeric value. Only applies to
date and number input types.
|
type |
The type of input. Works the same as a native <input> element, but only a
subset of types are supported. Defaults to text.
|
validationMessage |
Gets the validation message |
validity |
Gets the validity state object |
value |
The current value of the input, submitted as a name/value pair with form data. |
valueAsDate |
Gets or sets the current value as a Date object. Returns null if the
value can’t be converted. This will use the native
<input type="{{type}}"> implementation and may result in an error.
|
valueAsNumber |
Gets or sets the current value as a number. Returns NaN if the value can’t be
converted.
|
Et2InputWidget
| Name | Description |
|---|---|
autofocus |
Have browser focus this input on load. Overrides etemplate2.focusOnFirstInput(), use only once per page https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes |
hasFeedbackFor |
Get a list of feedback types |
needed |
Compatibility for deprecated name “needed” |
Textbox
| Name | Description |
|---|---|
disabled |
Defines whether this widget is visibly disabled. The widget is still visible, but clearly cannot be interacted with. Widgets disabled in the template will not return a value to the application code, even if re-enabled via javascript before submitting. To allow a disabled widget to be re-enabled and return a value, disable via javascript in the app’s et2_ready() instead of an attribute in the template file. |
mask |
Mask the input to enforce format. The mask is enforced as the user types, preventing invalid input. |
placeholder |
Placeholder text to show as a hint when the input is empty. |
translate |
List of properties that get translated Done separately to not interfere with properties - if we re-define label property, labels go missing. |
LitElement
| Name | Description |
|---|---|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Events
| Name | Description | Event Detail |
|---|---|---|
change |
Missing description |
Event
|
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
handleInput()
|
Anything the user types is theirs, not the ciphertext the server handed us. Without this the field would still consider itself encrypted, so revealing a password just typed (or one we suggested and the user then edited) would demand the login password and then ask the server to decrypt something it never issued - which it refuses. | - |
handlePasswordToggle()
|
If the password is viewable, toggle the visibility. If the password is still encrypted, we’ll ask for the user’s password then have the server decrypt it. | - |
suggestPassword()
|
Ask the server for a password suggestion | - |
Learn more about methods.
Inherited methods (41)
SlInput (Shoelace)
| Name | Description |
|---|---|
blur() |
Removes focus from the input. |
checkValidity() |
Checks for validity but does not show a validation message. Returns true when valid
and false when invalid.
|
focus() |
Sets focus on the input. |
getForm() |
Gets the associated form, if one exists. |
reportValidity() |
Checks for validity and shows the browser’s validation message if the control is invalid. |
select() |
Selects all the text in the input. |
setCustomValidity() |
Sets a custom validation message. Pass an empty string to restore validity. |
setRangeText() |
Replaces a range of text with a new string. |
setSelectionRange() |
Sets the start and end positions of the text selection (0-based). |
showPicker() |
Displays the browser picker for an input element (only works if the browser supports it for the input type). |
stepDown() |
Decrements the value of a numeric input type by the value of the step attribute. |
stepUp() |
Increments the value of a numeric input type by the value of the step attribute. |
Et2Widget
| Name | Description |
|---|---|
checkCreateNamespace() |
Checks whether a namespace exists for this element in the content array. If yes, an own perspective of the content array is created. If not, the parent content manager is used. Constructor attributes are passed in case a child needs to make decisions |
clone() |
Creates a copy of this widget. |
createElementFromNode() |
Create a et2_widget from an XML node. First the type and attributes are read from the node. Then the readonly & modifications arrays are checked for changes specific to the loaded data. Then the appropriate constructor is called. After the constructor returns, the widget has a chance to further initialize itself from the XML node when the widget’s loadFromXML() method is called with the node. |
getArrayMgr() |
Returns the array manager object for the given part |
getArrayMgrs() |
Returns an associative array containing the top-most array managers. |
getChildren() |
Get child widgets Use |
getInstanceManager() |
Returns the instance manager |
getPath() |
Returns the path into the data array. By default, array manager takes care of this, but some extensions need to override this |
getRoot() |
Returns the base widget Usually this is the same as getInstanceManager().widgetContainer |
loadFromXML() |
Loads the widget tree from an XML node |
loadingFinished() |
Needed for legacy compatability. |
parseXMLAttrs() |
The parseXMLAttrs function takes an XML DOM attributes object and adds the given attributes to the _target associative array. This function also parses the legacyOptions. N.B. This is only used for legacy widgets. WebComponents use transformAttributes() and do their own handling of attributes. |
set_label() |
NOT the setter, since we cannot add to the DOM before connectedCallback() TODO: This is not best practice. Should just set property, DOM modification should be done in render https://lit-element.polymer-project.org/guide/templates#design-a-performant-template |
setArrayMgr() |
Sets the array manager for the given part |
setArrayMgrs() |
Sets all array manager objects - this function can be used to set the root array managers of the container object. |
setInstanceManager() |
Set the instance manager Normally this is not needed as it’s set on the top-level container, and we just return that reference |
_handleClick() |
Click handler calling custom handler set via onclick attribute to this.onclick |
destroy() |
et2_widget compatability |
set_class() |
Set the widget class |
set_disabled() |
Wrapper on this.disabled because legacy had it. |
set_statustext() |
supports legacy set_statustext |
Et2InputWidget
| Name | Description |
|---|---|
et2HandleBlur() |
If the value is unchanged, put any held validation messages back Named et2HandleBlur to avoid overwriting handleBlur() in Shoelace components |
et2HandleFocus() |
When input receives focus, clear any validation errors. If the value is the same on blur, we’ll put them back The ones from the server (ManualMessage) can interfere with submitting. Named et2HandleFocus to avoid overwriting handleFocus() in Shoelace components |
getInputNode() |
Get input to e.g. set aria-attributes |
handleSlChange() |
Handle sl-change event from Shoelace components and dispatch a change event so anything listening for change events can react to it instead of having to listen for both sl-change and change. |
isValid() |
Used by etemplate2 to determine if we can submit or not |
submit() |
Called whenever the template gets submitted. We return false if the widget is not valid, which cancels the submission. |
validate() |
Massively simplified validate, as compared to what ValidatorMixin gives us, since ValidatorMixin extends FormControlMixin which breaks SlSelect’s render() We take all validators for the widget, and if there’s a value (or field is required) we check the value with each validator. For array values we check each element with each validator. If the value does not pass the validator, we collect the message and display feedback to the user. We handle validation errors from the server with ManualMessages, which always “fail”. If the value is empty, we only validate if the field is required. |
_oldChange() |
Change handler calling custom handler set via onchange attribute |