components

components

This class doesn't actually exist. It is merely used to group and document the HTML components that come with the Kiss system. Each method represents a new HTML tag offered by the Kiss system. Although these methods are shown with an underscore in their name, the actual tag they represent would have a dash instead.

In addition to the additional capabilities offered by some of these controls, many are enhancements over features already provided by HTML. These enhancements offer significant additional functionality as well as a more consistent interface.

In addition to the tag attributes and content documented here, most of these new HTML tags also support the standard attributes that HTML normally supports (such as "style" and "id"). Each of these controls (except radio-button) require the "id" attribute in order for your code to reference the control.

Components are accessed via the $$ global function. For example, if you have HTML containing:

     <text-input id="fname"></text-input>

You would access that control in your code with $$('fname') Methods available withing that control are accessed from that point. For example, one method available to text-input is hide(). This method can be accessed as follows:

     $$('fname').hide()

The documentation for each element includes three sections labeled Attributes, Content, and API. These are used as follows:

     <text-input Attributes>Content</text-input>

The API is what is used within JavaScript.

Functions that don't have a meaningful result otherwise, return 'this' so that function chaining can occur.

All the controls support all the standard HTML global attributes. The following lists some of the attributes commonly used:

Common Attributes
autofocus
class="class-name"
disabled
hidden
id="control-id"
readonly
style="..."

Constructor

new components()

Description:
  • There is no constructor.
Source:

Methods

(static) accordion()

Description:
  • This HTML tag, "accordion", creates a reusable disclosure group.

    Sections are declared with child accordion-item title="..." value="...">Content tags.

    AttributeDescription
    single allows only one section open at a time
    persist-key="key" stores open sections in localStorage
    APIDescription
    open(value) / close(value) / toggle(value) controls a section
    getOpenValues() / setOpen(values) reads or sets all open sections
    onchange(fun) receives (value, open, openValues) when a section changes
Source:

(static) avatar_badge()

Description:
  • This HTML tag, "avatar-badge", creates a generic avatar from initials or an image.

    AttributeDescription
    name="Jane Doe" name used for initials and label
    src="image.png" optional image URL
    size="40px" avatar size
    tone="neutral" neutral, accent, success, warning, error, or danger
    status="online" optional status dot: online, away, busy, or error
    APIDescription
    setName(name) updates the name used for initials and label
    setSrc(url) sets or replaces the avatar image
    setStatus(status) updates the status dot (online, away, busy, or error)
Source:

(static) badge_chip()

Description:
  • This HTML tag, "badge-chip", creates a small status badge or chip.

    AttributeDescription
    tone="neutral" neutral, accent, info, success, warning, error, or danger
    size="md" sm, md, or lg
    icon="✓" optional leading icon text
    dot shows a leading status dot
    APIDescription
    getValue() / setValue(text) reads or replaces the badge label text
    setTone(tone) changes the tone (neutral, accent, info, success, warning, error, or danger)
Source:

(static) check_box()

Description:
  • This HTML tag, "check-box", adds functionality and a consistent and convenient API to the HTML provided checkbox tag.

    AttributeDescription
    checked pre-selects the element

    Content

    The Content represents the label associated with the checkbox.

    APIDescription
    clear() uncheck the box
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets focus on control
    getValue() returns true if checked and false if unchecked
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if the user changed its state
    isDisabled() true if the control is disabled
    isHidden() true if the control is hidden (not visible)
    isReadOnly() true if the control is read-only
    isVisible() true if the control is visible (not hidden)
    onChange(fun) execute fun whenever the state of this control changes. fun is passed the value of the control.
    processChanges(flg) if false, checkbox should not register changes (no data was changed) See Utils.someControlValueChanged()
    readOnly([flg]) sets control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) sets control to read-write (or the reverse if the optional argument is false)
    setValue(val) if val is true check the box, uncheck if false
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) combo_box()

Description:
  • This HTML tag, "combo-box", is the equivalent of the Microsoft Windows combobox control. It is a drop-down list that also allows the user to type in a value that is not in the list (free entry). As the user types, the list opens (if closed) and narrows to the items whose label contains the typed text anywhere (case-insensitive); an empty field shows every item, and the list closes when nothing matches. Like a Windows combobox, the drop-down arrow button (and clicking into the field) always shows the complete list regardless of what has been typed. The Up/Down arrow keys (list open or closed) show and move through only the items matching the current text and never widen to the full list; Enter and Escape also operate on the items shown. Setting the value programmatically never opens or filters the list.

    Each list item has a label (the text shown, typed, and selected by the user) and an optional underlying value and arbitrary associated data. When the user types text that is not in the list, getValue() returns that typed text as-is. When the user selects (or types) a known list item, getValue() returns that item's underlying value. When add is called with only one argument, the value and the label are the same (a plain string list).

    Unlike drop-down, clear() here empties the entered/selected text (the typical expectation for a control the user types into); use clearList() to remove the suggestion list.

    AttributeDescription
    placeholder="text" text shown in the control when it is empty (standard HTML attribute, passed through)
    required an entry (selected or typed) is required

    Content

    The Content represents the HTML that would normally be inside an HTML datalist element — i.e. a static list of <option value="..."> suggestions. This would only be used in cases of a static list. List contents that depend on data would use the add / addItems / fill methods.

    APIDescription
    add(val [, lbl, data]) add a new list item. val is the underlying value, lbl is the text shown in the list (defaults to val if omitted), and data represents optional and arbitrary data associated to the item
    addItems(items, valField, lblField [, dataField]) used to add an array of items at one time. items is the array of items to add. valField and lblField are the names of the fields in the array. lblField can also be a function that formats the label. It is passed the row in items. dataField is the name of a field whose data is stored along with the item. If null, the whole item is stored.
    clear() clear the entered/selected text (the suggestion list is left intact)
    clearList() remove all items from the suggestion list
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    fill(selectedItem, items, valField, labelField [, dataField]) clear the list and fill it, then select/show the item whose value is selectedItem (or clear the entry if none)
    focus() sets focus on the control
    getAllData() returns the map of all label-to-data associations
    getAllLabels() returns an array of all the suggestion labels
    getData() returns the data associated to the currently shown item (or undefined for a free entry)
    getLabel() same as getText()
    getText() returns the text currently shown in the control (the label), whether a list item or free entry
    getValue() returns the underlying value of the shown item, or the typed text itself when it is a free entry not in the list
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if the user changed the value
    isDisabled() true if control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if control is hidden (not visible)
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute fun whenever the user commits a change (selection or leaving the field after editing). fun is called as fun(value, text, data)
    onEnter(fun) execute fun when the enter key is hit
    readOnly([flg]) make control read-only (or the reverse if the optional argument is false)
    readWrite([flg]) make control read-write (or the reverse if the optional argument is false)
    setText(val) set the text shown in the control directly (treats val as the displayed label)
    setValue(val) show the list item whose underlying value is val; if none matches, val is shown as free text
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
    size() returns the number of items in the suggestion list
    triggerGlobalChange(flg) Default true. If false then control changes will not trigger a global control change. See Utils.someControlValueChanged()
Source:

(static) date_input()

Description:
  • This HTML tag, "date-input", adds functionality and a consistent and convenient API for user date input. This control is custom and doesn't use the native browser date input offering the advantage of a significantly smaller width requirements. Also see native-date-input tag.

    AttributeDescription
    max="20181231" the maximum date allowed (also accepts "2018-12-31", "2/22/25", etc.)
    min="20180101" the minimum date allowed (also accepts "2018-12-31", "2/22/25", etc.)
    no-placeholder do not display mm/dd/yyyy when field is empty
    required an entry is required

    Content

    The Content represents the placeholder or what is shown as a prompt inside the control when there is no value.

    APIDescription
    clear() clear the control value
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getDateValue() returns the date as a Date instance
    getIntValue() returns the date as an integer with the "YYYYMMDD" format
    getSQLValue() returns the date as a string with the "YYYY-MM-DD" format
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if the user changed the value
    isDisabled() true if the control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if the control is hidden (not visible)
    isReadOnly() true if the control is read-only
    isVisible() true if the control is visible (not hidden)
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute funwhenever the user exits the control if the value changed, fun is passed the control value
    onEnter(fun) execute fun when enter key hit
    readOnly([flg]) set control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) set control to read-write (or the reverse if the optional argument is false)
    setMaxValue(val) sets the maximum value the control will accept val may be a Date, number (20180608), or string ("2018-06-08")
    setMinValue(val) sets the minimum value the control will accept val may be a Date, number (20180608), or string ("2018-06-08")
    setValue(val) sets the control value. val may be a Date, number (20180608), or string ("2018-06-08")
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) drop_down()

Description:
  • This HTML tag, "drop-down", adds functionality and a consistent and convenient API to the HTML provided select tag.

    AttributeDescription
    default-option="label" what is shown before the user makes a selection. This would often be something like "(choose)"
    required a selection is required

    Content

    The Content represents the HTML that would normally be inside an HTML select element. This would only be used in cases of a static list. List contents that depended on data would use the add method.

    The open list

    When the list is opened with the mouse or the keyboard (a click, Space, Alt+Down, Alt+Up, or F4), the control draws the list itself, under the control or above it when there is more room there, rather than using the browser's own pop-up. The browser delivers every keystroke to its pop-up and none to the page, so typing to filter (below) could not work there. The control's list behaves as the native one does: the current value is highlighted, Up and Down move it (firing onChange, as they do in a closed control), a click or Enter closes the list keeping the value, Escape closes it and returns to the value it opened with, and clicking elsewhere, leaving the control, or scrolling the page closes it. Only one drop-down list is ever open at a time. Touch input is left to the browser's native picker, which is the better control on a device with no keyboard to filter with. A read-only drop-down (readOnly()) neither opens nor changes its value from the keyboard.

    Typing to filter

    While the control has focus, whether or not its list is open, typing narrows the list to the options whose label contains the typed characters. Matching is case-insensitive, and the text may appear anywhere in the label, not only at its start. With the list open, the typed text is shown at the top of the list and the rows narrow with each keystroke. As the user types, the current selection is kept if it still matches; otherwise the first matching option becomes selected (and onChange fires, as with the browser's own type-ahead). Backspace removes the last typed character. Escape erases the typed sequence, restores the full list, and returns to the selection that was current before typing began, so the user can start again (an open list stays open; a second Escape closes it). Leaving the control also restores the full list, keeping whatever is then selected. A lone space opens and closes the list, as it does natively; once a sequence has begun, a space is part of it.

    The filter changes only what the list displays and which option is selected. size(), getValue(idx), getLabel(idx), getAllLabels(), selectedIndex(), and the other index-based methods always refer to the complete list, and any method that modifies the list first restores it and closes the list.

    APIDescription
    add(val, lbl, data) add a new list item. val is the value associated to the option, lbl is the text shown in the list, and data represents optional and arbitrary data associated to the option
    addItems(items, valField, lblField [, dataField]) used to add an array of items at one time. items is the array of items to add. valField and lblField are the names of the fields in the array. lblField an also be a function that formats the label. It is passed the row in items. dataField is the name of a field whose data is stored along with the item. If null, the whole item is stored.
    clear() remove the list contents except the default-option
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    fill(selectedItem, items, valField, labelField [, dataField]) clear and fill a dropdown selecting the specified item
    focus() sets focus on the control
    getAllLabels() returns an array of all the labels
    getAllData() returns an array of all the data associated with the control
    getData(idx) returns the data associated to an option. If idx is undefined, the selected row is used otherwise the row indexed by idx is used.
    getLabel(idx) returns the label associated to an option. If idx is undefined, the selected row is used otherwise the row indexed by idx is used.
    getValue(idx) returns the string value associated to an option (returns an array if multiple attribute included). If idx is undefined, the selected row is used otherwise the row indexed by idx is used.
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty([flg]) true if user changed value (or the reverse if the optional argument is false)
    isDisabled() true if control is disabled
    isHidden() true if control is hidden (not visible)
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    onChange(fun) execute funwhenever the state of this control changes. fun is called as follows fun(val, lbl, data)
    readOnly([flg]) make control read-only (or the reverse if the optional argument is false)
    readWrite([flg]) make control read-write (or the reverse if the optional argument is false)
    removeByIndex(idx) remove the row indicated by idx
    selectedIndex() returns the index of the selected item (-1 if none)
    selectIndex(row) selects the indicated row index
    setLabel(lbl, idx) sets a row label to lbl. If idx is undefined, the selected row is affected otherwise the row indexed by idx is updated.
    setValue(val, idx) sets a row value to val. If idx is undefined, the selected row is affected otherwise the row indexed by idx is updated.
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
    size() returns the number of rows in the list (including default-option
    triggerGlobalChange(flg) Default true. If false then control changes will not trigger a global control change. See Utils.someControlValueChanged()
Source:

(static) duration_input()

Description:
  • This HTML tag, "duration-input", provides a control where the user can enter a duration as two integers separated by a colon. The first number is the number of hours and the second is the number of minutes (0-59). If the user does not enter a colon, the value is treated as hours only with an implied :00 for the minutes (so 3 means 3 hours, 0 minutes). The control allows only digits and a single colon. This represents a duration, not a time of day.

    The "value" of this control is the total number of minutes (an integer). getValue() returns 0 when the field is blank or contains an invalid value.

    If the decimal-hours attribute is set, the user enters and the control displays a decimal number of hours (e.g. 1.25 means 1 hour 15 minutes) instead of H:MM. Only digits and at most one decimal point are accepted. The JavaScript API is unchanged: getValue() still returns the total number of minutes (so 1.25 entered returns 75) and setValue(75) displays 1.25.

    AttributeDescription
    decimal-hours accept and display the value as decimal hours (e.g. 1.25) instead of H:MM
    min="1:30" the minimum duration allowed (also accepts a total-minutes integer or, in decimal-hours mode, a decimal-hours value such as "1.5")
    max="8:00" the maximum duration allowed (also accepts a total-minutes integer or, in decimal-hours mode, a decimal-hours value such as "8.0")
    no-placeholder do not display the format hint when field is empty
    required an entry is required
    size="20" width of control in number of characters (default 20)

    Content

    The Content represents the placeholder or what is shown as a prompt inside the control when there is no value.

    APIDescription
    clear() remove the value associated with the control
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getHours() returns the duration as a floating point number of hours (e.g. 2:15 returns 2.25)
    getValue() returns the total number of minutes; 0 if blank or invalid
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if user changed control value
    isDisabled() true if control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if control is hidden (not visible)
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute fun whenever the user exits the control if the value changed, fun is passed the control value
    onEnter(fun) execute fun when enter key hit
    readOnly([flg]) sets control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) sets control to read-write (or the reverse if the optional argument is false)
    setHours(val) sets the control value from a floating point number of hours (e.g. 2.25 displays as 2:15)
    setMaxValue(val) sets the maximum value the control will accept (accepts "h:mm" string or a total-minutes integer)
    setMinValue(val) sets the minimum value the control will accept (accepts "h:mm" string or a total-minutes integer)
    setValue(val) sets the control value from a total number of minutes
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) file_upload()

Description:
  • This HTML tag, "file-upload", adds functionality and a consistent and convenient facility uploading files and taking pictures with the camera.
    Please note: When this control is used, you must use Server.fileUploadSend() rather than Server.call().

    AttributeDescription
    multiple the user may select multiple files
    required an entry is required (at least 1 file)
    accept types of files allowed (see HTML input type="file")
    custom rather than the native HTML control, use a Kiss button to upload files.

    Content

    The Content of this control is unused.

    APIDescription
    clear() erases the contents of the control
    click() simulate a user click on the control
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getFormData() gets the upload file data for transmission to the back-end
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() has the control contents been changed by user
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isDisabled() is the control disabled?
    isHidden() is the control hidden?
    isReadOnly() is the control read-only?
    isVisible() is the control visible?
    numberOfUploadFiles() the number of files the user selected is returned
    onChange(fun) execute fun when control changes
    readOnly([flg]) set control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) set control to read-write (or the reverse if the optional argument is false)
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
    uploadFile(idx) the JavaScript FileList object of file number idx. If idx is missing, the whole FileList is returned.
    uploadFileExtension(idx) the file name extension of file number idx
    uploadFilename(idx) the name of file number idx
Source:

(static) list_box()

Description:
  • This HTML tag, "list-box", adds functionality and a consistent and convenient API to the HTML provided select tag.

    Be sure to call the clear() method between uses otherwise the system won't detect the same file being accessed.

    AttributeDescription
    default-option="label" what is the default selection
    multiple multiple entries may be selected (an array will be returned)
    required a selection is required
    size="20" the minimum number of visible lines (will expand to fill the area it is in)

    Content

    The Content represents the HTML that would normally be inside an HTML select element. This would only be used in cases of a static list. List contents that depended on data would use the add method.

    Typing to filter

    While the control has focus, typing narrows the list to the options whose label contains the typed characters. Matching is case-insensitive, and the text may appear anywhere in the label, not only at its start. In a single-select list the current selection is kept if it still matches; otherwise the first matching option becomes selected (and onChange fires, as with the browser's own type-ahead). A multiple list only narrows what is shown; every selection is left as it is, including selections on rows the filter has hidden. Backspace removes the last typed character. Escape erases the typed sequence, restores the full list, and returns to the selection that was current before typing began, so the user can start again. Leaving the control also restores the full list, keeping whatever is then selected. A leading space keeps its native meaning; once a sequence has begun, a space is part of it.

    The filter changes only what the list displays and which options are selected. size(), getValue(), getValue(idx), getLabel(idx), getAllLabels(), selectedIndex(), and the other index-based methods always refer to the complete list, and any method that modifies the list or its selection first restores it.

    APIDescription
    add(val, lbl, data) add a new list item. val is the value associated to the option, lbl is the text shown in the list, and data represents optional and arbitrary data associated to the option
    addItems(items, valField, lblField [, dataField]) used to add an array of items at one time. items is the array of items to add. valField and lblField are the names of the fields in the array. lblField an also be a function that formats the label. It is passed the row in items. dataField is the name of a field whose data is stored along with the item. If null, the whole item is stored.
    clear() remove the list contents except the default-option
    clearSelection() de-select all elements
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets focus on control
    getAllLabels() returns an array of all the labels
    getAllData() returns an array of all the data associated with the control
    getData(idx) returns the data associated to an option. If idx is undefined, the selected row is used otherwise the row indexed by idx is used.
    getLabel(idx) returns the label associated to an option. If idx is undefined, the selected row is used otherwise the row indexed by idx is used.
    getValue(idx) If idx is undefined and the multiple attribute is set, returns an array of all selected values. If idx is undefined and multiple is not set, returns the single selected value. If idx is provided, returns the value at that row index.
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if user has changed control value
    isDisabled() true if control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if control is hidden (not visible)
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    onChange(fun) execute funwhenever the state of this control changes. fun is called as follows fun(val, lbl, data)
    onClick(fun) execute funwhenever the user clicks on an item. fun is called as follows fun(val, lbl, data)
    onDblClick(fun) execute funwhenever the user double-clicks on an item. fun is called as follows fun(val, lbl, data) (Note that double-click does not function on mobile devices.)
    readOnly([flg]) sets control to read-only (or the reverse if the optional argument is false). A read-only list shows its selection but neither the keyboard nor a click on a row can change it; it can still be scrolled
    readWrite([flg]) sets control to read-write (or the reverse if the optional argument is false)
    removeByIndex(idx) remove the row indicated by idx
    setLabel(lbl, idx) sets a row label to lbl. If idx is undefined, the selected row is affected otherwise the row indexed by idx is updated.
    setValue(val, idx) sets a row value to val. If idx is undefined, the selected row is affected otherwise the row indexed by idx is updated.
    selectedIndex() returns the index of the selected item (-1 if none)
    selectIndex(row) selects the indicated row index
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
    size() returns the number of rows in the list
    triggerGlobalChange(flg) Default true. If false then control changes will not trigger a global control change. See Utils.someControlValueChanged()
Source:

(static) menu_button()

Description:
  • This HTML tag, "menu-button", creates a button that opens a keyboard-accessible dropdown menu.

    Menu content is declared with child menu-item, menu-separator, and optional menu-trigger tags.

    AttributeDescription
    label="Menu" trigger text when no menu-trigger is supplied
    align="start" menu alignment: start or end
    placement="bottom" menu placement: bottom or top
    disabled disables the trigger
    close-on-select="false" leaves the menu open after selection
    APIDescription
    open() / close() / toggle() controls menu visibility
    isOpen() returns whether the menu is visible
    onselect(fun) receives (value, label, itemElement) when a menu item is chosen
    getValue() / setValue(val) gets or stores the current selected value
    disable([flg]) disables the trigger (or the reverse if the optional argument is false)
    enable([flg]) enables the trigger (or the reverse if the optional argument is false)
    focus() sets focus on the trigger
Source:

(static) native_date_input()

Description:
  • This HTML tag, "native-date-input", adds functionality and a consistent and convenient API to the HTML provided date input. Also see the date-input tag.

    AttributeDescription
    max="20181231" the maximum date allowed (also accepts "2018-12-31", "2/22/25", etc.)
    min="20180101" the minimum date allowed (also accepts "2018-12-31", "2/22/25", etc.)
    required an entry is required

    Content

    The Content represents the placeholder or what is shown as a prompt inside the control when there is no value.

    APIDescription
    clear() clear the control value
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getDateValue() returns the date as a Date instance
    getIntValue() returns the date as an integer with the "YYYYMMDD" format
    getSQLValue() returns the date as a string with the "YYYY-MM-DD" format
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if the user changed the value
    isDisabled() true if the control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if the control is hidden (not visible)
    isReadOnly() true if the control is read-only
    isVisible() true if the control is visible (not hidden)
    onCChange(fun) execute fun whenever the user changes the value (typing, the date picker, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute funwhenever the user exits the control if the value changed, fun is passed the control value
    onEnter(fun) execute fun when enter key hit
    readOnly([flg]) set control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) set control to read-write (or the reverse if the optional argument is false)
    setMaxValue(val) sets the maximum value the control will accept val may be a Date, number (20180608), or string ("2018-06-08")
    setMinValue(val) sets the minimum value the control will accept. val may be a Date, number (20180608), or string ("2018-06-08")
    setValue(val) sets the control value. val may be a Date, number (20180608), or string ("2018-06-08")
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) numeric_input()

Description:
  • This HTML tag, "numeric-input", adds functionality and a consistent and convenient API to the HTML input text element. For example, it will only accept numbers, can verify decimal places, and formats the number when the control is exited by the user.

    AttributeDescription
    decimal-places="2" controls the maximum number of digits past the decimal point (default 0)
    dollar-sign adds a dollar sign when formatting the number
    left-justify left-justifies the number (default is right-justified)
    min="20" sets the minimum acceptable value (default 0)
    max="200" sets the maximum acceptable value
    money sets min="0" dollar-sign decimal-places="2"
    no-comma do not format number with commas
    required an entry is required
    show-zero show zero values (instead of blank if zero)
    size="20" width of control in number of characters (default 20)

    Content

    The Content represents the placeholder or what is shown as a prompt inside the control when there is no value.

    APIDescription
    clear() erases the contents of the control
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getValue() returns the numeric value of the control
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() did user change control content?
    isDisabled() is control disabled?
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() is control hidden?
    isReadOnly() is control read-only?
    isVisible() is control visible?
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute funwhenever the user exits the control if the value changed, fun is passed the control value
    onEnter(fun) execute fun when enter key hit
    readOnly([flg]) set control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) set control to read-write (or the reverse if the optional argument is false)
    setMaxValue(val) sets the maximum value the control will accept
    setMinValue(val) sets the minimum value the control will accept
    setValue(val) sets the numeric value of the control
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) panel_card()

Description:
  • This HTML tag, "panel-card", creates a generic card or panel surface.

    AttributeDescription
    as="section" rendered element: div, section, article, aside, main, header, or footer
    no-pad removes default padding
    hover adds a hover elevation state
    interactive adds button-like focus and click affordances
    APIDescription
    onclick(fun) registers a click handler (used with the interactive attribute)
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    show([flg]) the control is shown (or the reverse if the optional argument is false)
    isHidden() true if the control is hidden
    isVisible() true if the control is visible
Source:

(static) picture()

Description:
  • This HTML tag, "picture", adds the ability to display an image.

    APIDescription
    clear() erases the image
    hide([flg]) the image is hidden (or the reverse if the optional argument is false)
    isHidden() is image hidden?
    isVisible() is image visible?
    onclick(fun) fun is executed when the user clicks on the image
    setValue(filename, image) sets the image to be displayed
    show([flg]) the image is made visible (or the reverse if the optional argument is false)
Source:

(static) popup()

Description:
  • This HTML tag, "popup", adds the ability to define a popup window. Within it, the tags "popup-title" and "popup-body" should be used to define the respective parts of the popup window.

    AttributeDescription
    height="400px" sets the height of the body of the popup window
    width="200px" sets the width of the body of the popup window
    draggable="false" disables title-bar dragging for the popup
    close-button="true" adds a standard title-bar close button
    close-label="Close" aria label for the standard close button
Source:

(static) push_button()

Description:
  • This HTML tag, "push-button", adds functionality and a consistent and convenient API to the HTML provided button input.

    No new attributes are defined.

    Content

    No element content is defined.

    APIDescription
    click() simulate a button click
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets focus to control
    getValue() returns the label on the push button
    hide([flg]) hides the control (or the reverse if the optional argument is false)
    isDisabled() true if control is disabled
    isHidden() true if control is hidden (not visible)
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    readOnly([flg]) sets control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) sets control to read-write (or the reverse if the optional argument is false)
    onclick(fun) fun is executed when the user clicks on the button
    setValue(val) sets the label on the push button
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) radio_button()

Description:
  • This HTML tag, "radio-button", adds functionality and a consistent and convenient API to the HTML provided radio input element.

    One thing that makes this control different from the others is that it can be referred to with the $$ function by its group name or the individual radio button id. When the group name is used, the entire group is effected. When an individual radio button is addressed by its id, only that control is effected.

    All the radio buttons in the same group should share the same group name.

    AttributeDescription
    align-horizontal align the buttons horizontally (default)
    align-vertical align the buttons vertically
    button-style="style" style used for the button portion of the radio button
    checked pre-selects the particular radio button
    group="name" the name of the group this radio button is a part of (the same for each radio button in a group)
    label-style="style" style used for the label portion of the radio button
    name="name" this is an alternate to the group attribute for HTML consistency
    required a selection is required
    value="value" required unique value associate with each radio button (different for each radio button)

    Content

    This is the label associated with the radio button.

    APIDescription
    APIDescription
    clear() sets the radio button group to none selected
    disable([flg]) set the control to disabled (or the reverse if the optional argument is false)
    enable([flg]) set the control to enabled (or the reverse if the optional argument is false)
    focus() set focus on the current control
    getIntValue() the integer value of the selected ratio button group
    getValue() the string value of the selected ratio button group
    hide([flg]) hides the control (or the reverse if the optional argument is false)
    isDirty() true if the user changed the value
    isDisabled() true if the control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden(desc) true if the control is hidden (not visible)
    isReadOnly() true if the control is read-only
    isVisible() true if the control is visible (not hidden)
    onChange(fun) execute fun whenever the state of this control changes. fun is passed the value of the control group.
    readOnly([flg]) sets the control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) sets the control to read-write (or the reverse if the optional argument is false)
    setLabel(val) selects the label for the control
    setValue(val) selects the button with the associated value
    show([flg]) sets the control to show (not hide) (or the reverse if the optional argument is false)
Source:

(static) search_input()

Description:
  • This HTML tag, "search-input", creates a search field with a built-in clear button and optional result list.

    AttributeDescription
    placeholder="Search..." placeholder text
    value="text" initial value
    maxlength="100" maximum input length
    disabled disables the field
    APIDescription
    getValue() / setValue(val) / clear() manages the search text
    oninput(fun) / onsearch(fun) / onclear(fun) registers field callbacks
    setResults(items [, options]) displays selectable results. Options include valueField, labelField, descriptionField, and metaField.
    onselect(fun) receives (value, label, item, element) when a result is chosen
    showResults() / hideResults() shows or hides the result list
    focus() sets focus on the search field
    disable([flg]) disables the field (or the reverse if the optional argument is false)
    enable([flg]) enables the field (or the reverse if the optional argument is false)
Source:

(static) section_title()

Description:
  • This HTML tag, "section-title", creates a reusable section heading row with optional supporting text and actions.

    AttributeDescription
    title="Title" heading text
    subtitle="Description" secondary text under the heading
    eyebrow="Label" small label above the heading
    level="2" heading level from 1 to 6
    Child content is rendered as the action area when title attributes are supplied.
    APIDescription
    setTitle(text) updates the heading text
    setSubtitle(text) updates the secondary text under the heading
Source:

(static) segmented_control()

Description:
  • This HTML tag, "segmented-control", creates a segmented tab/button selector.

    Options are declared with child segment value="...">Label tags.

    AttributeDescription
    value="id" selected segment value
    equal segments share equal width
    disabled disables all segments
    APIDescription
    getValue() / setValue(val [, silent]) reads or selects a segment
    onchange(fun) receives (value, label, itemElement) when selection changes
    fill(items, selectedItem [, valField, labelField]) replaces all segments from an array
    disable([flg]) disables all segments (or the reverse if the optional argument is false)
    enable([flg]) enables all segments (or the reverse if the optional argument is false)
Source:

(static) smart_chooser()

Description:
  • This HTML tag, "smart-chooser", is a select-like control that automatically avoids unusably long drop-down lists. Depending on how many items it is given (compared to a caller-supplied threshold), it renders as one of:
    • a normal HTML select drop-down (few enough items), or
    • a disabled/read-only text field paired with a small chooser button that invokes a caller-supplied asynchronous selection function (typically a search popup) when there are too many items for a drop-down, or
    • a disabled text field showing the single available choice (exactly one item and selection isn't forced), or
    • a disabled text field reading "(nothing to select)" (zero items and selection isn't forced).
    The control can be driven at either of two levels: the low-level API builds the list/chooser manually (similar to drop-down), while the high-level API (setup / setupItems / setupSelectFunction / setupDefault / run) decides which of the four presentations above to use automatically from the item count.

    The chooser button needs application-supplied styling. The framework emits the button with class btn-smart-chooser (and a :disabled state) but ships no default appearance or icon for it — the hosting application must supply that CSS (and any icon asset it references).

    AttributeDescription
    required a selection is required
    disabled disables the control
    default-option="label" what is shown before the user makes a selection (drop-down presentation only)
    inside-width="n" sets the control's inner width, in pixels
    outside-width="n" sets the control's outer (including padding) width, in pixels

    Content

    The Content represents the HTML that would normally be inside an HTML select element (used only for a static list; data-driven lists use add / addItems).

    API (low-level)Description
    add(val, label, data) add one item to the drop-down list
    addItems(items, valField, labelField, dataField) add an array of items at once; labelField can be a field name or a function that formats the label from the item
    useDropdown([items, valField, labelField, dataField]) force the drop-down presentation, optionally filling it
    forceSelect([title]) force the chooser-button (search) presentation, showing title (default "(choose)") until a value is set
    nothingToSelect() force the "(nothing to select)" disabled presentation
    singleValue(val, label, data) force the single-disabled-value presentation showing the one given item
    setSelectFunction(fun) sets the (must be async) function run when the chooser button is clicked; its resolved value is passed to the caller's own handling, not consumed automatically — see the high-level API for the common wiring pattern
    setForceSelection([flg]) when true, forces the chooser-button presentation even for item counts that would otherwise use a drop-down
    setForceDropDown([flg]) when true, allows the drop-down presentation even above the normal item-count threshold
    clear() resets the control's list/value back to its initial (empty) state
    reset() restores the control to the original underlying element and clears it (undoes a prior forceSelect)
    setValue(val, label, data) selects val; in the drop-down presentation the item is added first if not already present
    getValue() returns the underlying value of the current selection
    getIntValue() returns the current value as a number (0 if empty)
    getLabel() returns the label text currently shown
    getData() returns the data associated with the current selection
    size() returns the number of items in the drop-down list
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets focus on the control
    hide([flg]) the control (and its chooser button) is hidden (or the reverse if the optional argument is false)
    show([flg]) the control (and its chooser button) is made visible (or the reverse if the optional argument is false)
    isDirty() true if the user changed its value (drop-down presentation only)
    isDisabled() true if the control is disabled
    isHidden() true if the control is hidden (not visible)
    isVisible() true if the control is visible (not hidden)
    isReadOnly() / readOnly([flg]) / readWrite([flg]) read-only state (drop-down presentation only)
    isError(desc) used for error checking (only meaningful with required). If error, display error message and return true. desc is a description of the user field.
    onChange(fun) execute fun(val, label, data) whenever the drop-down selection changes
    triggerGlobalChange(flg) Default true. If false then control changes will not trigger a global control change. See Utils.someControlValueChanged()
    API (high-level convenience wrapper)Description
    setup(maxNumberInDropDown, addChooseOption) first call; maxNumberInDropDown is the item-count threshold that decides drop-down vs. chooser-button, addChooseOption (boolean or label string) adds a blank "(choose)" first option to the drop-down
    setupItems(items, valField, labelField, dataField) supplies the candidate item array and its field names (labelField can be a formatting function)
    setupSelectFunction(selectFunction, valField, labelField, dataField) supplies the async function used for the chooser-button presentation, plus the field names to read from its resolved item
    setupDefault(defaultValue, defaultLabel, defaultData) supplies the initially-selected value
    testMode([flg]) forces both the drop-down and the chooser button to be shown/enabled together (for exercising both paths during testing)
    run() builds the control from everything supplied to setup* above, automatically choosing the drop-down, chooser-button, single-value, or nothing-to-select presentation
Source:

(static) text_input()

Description:
  • This HTML tag, "text-input", adds functionality and a consistent and convenient API to the HTML provided text input.

    AttributeDescription
    fixcap auto-correct capitalization of each word (first char uppercase, rest lowercase)
    minlength="5" sets the minimum acceptable string length
    maxlength="20" sets the maximum number of characters
    password the character are not shown on the screen
    required an entry is required (at least 1 character)
    size="20" width of control in number of characters (default 20)
    upcase when the user enters text, it is auto-upcased

    Content

    The Content represents the placeholder or what is shown as a prompt inside the control when there is no value.

    APIDescription
    clear() erases the contents of the control
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getValue() returns the string associated with the control
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() has the control contents been changed by user
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isDisabled() is the control disabled?
    isHidden() is the control hidden?
    isReadOnly() is the control read-only?
    isVisible() is the control visible?
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute funwhenever the user exits the control if the value changed, fun is passed the control value
    onEnter(fun) execute fun when enter key hit
    readOnly([flg]) set control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) set control to read-write (or the reverse if the optional argument is false)
    setPassword(val) if true, treat as a password control; if false, treat as text input - previous value is returned
    setValue(val) sets the string inside the control
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) text_label()

Description:
  • This HTML tag, "text-label", adds functionality and a consistent and convenient API to the HTML provided label tag when the 'for' attribute is used or the 'span' tag otherwise.

    Content

    The Content represents the content of the label.

    APIDescription
    clear() erases the contents of the control
    getValue() returns the string associated with the control
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isHidden() is the control hidden?
    isVisible() is the control visible?
    onclick(fun) fun is executed when the user clicks on the text
    setColor(val) sets the color of the text
    setValue(val) sets the string inside the control
    setHTMLValue(val) sets the HTML inside the control
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) textbox_input()

Description:
  • This HTML tag, "textbox-input", adds functionality and a consistent and convenient API to the HTML provided multi-line text input. Static HTML content can be used inside this control.

    AttributeDescription
    minlength="5" sets the minimum acceptable string length
    maxlength="200" sets the maximum number of characters
    placeholder="" text to be displaced in the control until the user enters data
    required an entry is required (at least 1 character)
    upcase when the user enters text, it is auto-upcased

    Content

    The Content represents the placeholder or what is shown as a prompt inside the control when there is no value.

    APIDescription
    clear() erases the contents of the control
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getValue() returns the string associated with the control
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if user changed control contents
    isDisabled() true if control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if user control is hidden (not visible)
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute funwhenever the user exits the control if the value changed, fun is passed the control value
    readOnly([flg]) sets control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) sets control to read-write (or the reverse if the optional argument is false)
    setHtmlValue(val) sets the string inside the control. The string is interpreted as HTML.
    setValue(val) sets the string inside the control
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) time_input()

Description:
  • This HTML tag, "time-input", provides a control where the user can enter a time. The time appear like "3:30 PM". A 24 hour clock is also supported automatically (like 14:30). The values this control interacts with is a plain integer in the form HHMM in a 24 hour clock. So, "1:30 PM" would be 1330. -1 is returned if the field is left blank.

    AttributeDescription
    min="0800" the minimum time allowed (also accept times like "3:30 pm", etc.)
    min="1800" the maximum time allowed (also accept times like "3:30 pm", etc.)
    no-placeholder do not display hh:mm when field is empty
    required an entry is required
    size="20" width of control in number of characters (default 20)
    zero-fill zero fill the display

    Content

    The Content represents the HTML that would normally be inside an HTML select element. This would only be used in cases of a static list. List contents that depended on data would use the add method.

    APIDescription
    clear() remove the value associated with the control
    disable([flg]) the control remains visible but inactive (or the reverse if the optional argument is false)
    enable([flg]) the control is set to visible and enabled (or the reverse if the optional argument is false)
    focus() sets the focus (where the cursor is located) to this control
    getValue() returns the value associated with the control
    hide([flg]) the control is hidden (or the reverse if the optional argument is false)
    isDirty() true if user changed control value
    isDisabled() true if control is disabled
    isError(desc) used for error checking. If error, display error message and return true. desc is a description of the user field.
    isHidden() true if control is hidden (not visible)
    isReadOnly() true if control is read-only
    isVisible() true if control is visible (not hidden)
    onCChange(fun) execute fun whenever the user changes the value (typing, Backspace/Delete, paste, cut, drag-and-drop, or browser autofill), fun is passed the control value
    onChange(fun) execute funwhenever the user exits the control if the value changed, fun is passed the control value
    onEnter(fun) execute fun when enter key hit
    readOnly([flg]) sets control to read-only (or the reverse if the optional argument is false)
    readWrite([flg]) sets control to read-write (or the reverse if the optional argument is false)
    setMaxValue(val) sets the maximum value the control will accept (accept times like 1530, "3:30 pm", etc.)
    setMinValue(val) sets the minimum value the control will accept (accept times like 1530, "3:30 pm", etc.)
    setValue(val) sets the value associated with the control
    show([flg]) the control is made visible (or the reverse if the optional argument is false)
Source:

(static) toast()

Description:
  • This HTML tag, "toast", defines a reusable non-modal notification region. Toasts may also be shown without an explicit tag by calling Utils.toast(message [, options]) or one of Utils.toast.success(), Utils.toast.info(), Utils.toast.warning(), or Utils.toast.error().

    AttributeDescription
    position="top-center" one of top-left, top-center, top-right, bottom-left, bottom-center, or bottom-right. Top positions sit below .app-nav when present.
    type="info" default toast type: info, success, warning, or error
    duration="3000" milliseconds before a toast closes; use 0 to keep it open until dismissed
    time="3000" alias for duration
    auto-dismiss="false" keep the toast open until it is dismissed manually
    manual keep the toast open until it is dismissed manually
    max-visible="3" maximum number of visible toasts in this region
    no-dismiss hide the dismiss button

    Content

    If content is supplied, it is shown as an initial toast.

    APIDescription
    show(message [, options]) displays a toast message and returns an object with close()
    success(message [, options]) displays a success toast
    info(message [, options]) displays an informational toast
    warning(message [, options]) displays a warning toast
    error(message [, options]) displays an error toast
    manual(message [, options]) displays a toast that stays visible until dismissed
    clear() closes all toasts in this region
    configure(options) updates default type, position, duration, maxVisible, or dismissible values
Source: