com.github.fluorumlabs.disconnect.vaadin.ComboBox Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of disconnect-vaadin Show documentation
Vaadin components bindings for Disconnect Zero
The newest version!
package com.github.fluorumlabs.disconnect.vaadin;

import com.github.fluorumlabs.disconnect.core.annotations.WebComponent;
import com.github.fluorumlabs.disconnect.vaadin.elements.ComboBoxElement;
import com.github.fluorumlabs.disconnect.vaadin.mixins.*;
import com.github.fluorumlabs.disconnect.zero.component.*;
import js.lang.Any;
import js.web.dom.Element;

import javax.annotation.Nullable;

/**
 * <vaadin-combo-box> is a combo box element combining a dropdown list with an
 * input field for filtering the list of items. If you want to replace the default
 * input field with a custom implementation, you should use the
 * <vaadin-combo-box-light> element.
 * 
 * Items in the dropdown list must be provided as a list of String values.
 * Defining the items is done using the items property, which can be assigned
 * with data-binding, using an attribute or directly with the JavaScript property.
 *
 * 
<vaadin-combo-box
 *     label="Fruit"
 *     items="[[data]]">
 * </vaadin-combo-box>
 * 
 * combobox.items = ['apple', 'orange', 'banana'];
 * 
 * When the selected value is changed, a value-changed event is triggered.
 * 
 * This element can be used within an iron-form.
 *
 * 
Item rendering
 * <vaadin-combo-box> supports using custom renderer callback function for defining the
 * content of <vaadin-combo-box-item>.
 * 
 * The renderer function provides root, comboBox, model arguments when
 * applicable.
 * Generate DOM content by using model object properties if needed, append it to the root
 * element and control the state of the host element by accessing comboBox. Before generating new
 * content, users are able to check if there is already content in root for reusing it.
 *
 * 
<vaadin-combo-box id="combo-box"></vaadin-combo-box>
 * 
 * const comboBox = document.querySelector('#combo-box');
 * comboBox.items = [{'label': 'Hydrogen', 'value': 'H'}];
 * comboBox.renderer = function(root, comboBox, model) {
 *   root.innerHTML = model.index + ': ' +
 *                    model.item.label + ' ' +
 *                    '<b>' + model.item.value + '</b>';
 * };
 * 
 * Renderer is called on the opening of the combo-box and each time the related model is updated.
 * DOM generated during the renderer call can be reused
 * in the next renderer call and will be provided with the root argument.
 * On first call it will be empty.
 *
 * Item Template
 * Alternatively, the content of the <vaadin-combo-box-item> can be populated by using
 * custom item template provided in the light DOM:
 *
 * <vaadin-combo-box items='[{"label": "Hydrogen", "
 * value": "H"}]'>
 *   <template>
 *     [[index]]: [[item.label]] <b>[[item.value]</b>
 *   </template>
 * </vaadin-combo-box>
 * 
 * The following properties are available for item template bindings:
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Property name Type Description
index Number Index of the item in the items array
item String or Object The item reference
selected Boolean True when item is selected
focused Boolean True when item is focused
 * Lazy Loading with Function Data Provider
 * In addition to assigning an array to the items property, you can alternatively
 * provide the <vaadin-combo-box> data through the
 * dataProvider function property.
 * The <vaadin-combo-box> calls this function lazily, only when it needs more data
 * to be displayed.
 * 
 * See the dataProvider in
 * the API reference below for the detailed data provider arguments description,
 * and the “Lazy Loading“ example on “Basics” page in the demos.
 *
 * Note that when using function data providers, the total number of items
 * needs to be set manually. The total number of items can be returned
 * in the second argument of the data provider callback:
 *
 * 
comboBox.dataProvider = function(params, callback) {
 *   var url = 'https://api.example/data' +
 *       '?page=' + params.page +        // the requested page index
 *       '&per_page=' + params.pageSize; // number of items on the page
 *   var xhr = new XMLHttpRequest();
 *   xhr.onload = function() {
 *     var response = JSON.parse(xhr.responseText);
 *     callback(
 *       response.employees, // requested page of items
 *       response.totalSize  // total number of items
 *     );
 *   };
 *   xhr.open('GET', url, true);
 *   xhr.send();
 * };
 * 
 * Styling
 * The following custom properties are available for styling:
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Custom property Description Default
--vaadin-combo-box-overlay-max-height Property that determines the max height of
 * overlay 65vh
 * The following shadow DOM parts are available for styling:
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Part name Description
text-field The text field
toggle-button The toggle button
 * See
 * <vaadin-overlay> documentation
 * for <vaadin-combo-box-overlay> parts.
 * 
 * See
 * <vaadin-text-field> documentation
 * for the text field parts.
 * 

 * The following state attributes are available for styling:
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Attribute Description Part name
opened Set when the combo box dropdown is open :host
disabled Set to a disabled combo box :host
readonly Set to a read only combo box :host
has-value Set when the element has a value :host
invalid Set when the element is invalid :host
focused Set when the element is focused :host
focus-ring Set when the element is keyboard focused :host
loading Set when new items are expected :host
 * In addition to <vaadin-combo-box> itself, the following internal
 * components are themable:
 *
 * 
 * <vaadin-text-field>
 * <vaadin-combo-box-overlay>
 * <vaadin-combo-box-item>
 * 
 * Note: the theme attribute value set on <vaadin-combo-box> is
 * propagated to the internal themable components listed above.
 * 
 * See
 * ThemableMixin – how to apply styles for shadow parts
 */
@WebComponent
public class ComboBox extends AbstractComponent>
		implements HasElementMixin, ComboBox>,
		HasControlStateMixin, ComboBox>,
		HasComboBoxDataProviderMixin, ComboBox>,
		HasComboBoxMixin, ComboBox>,
		HasThemableMixin, ComboBox>,
		HasSlots>,
		HasStyle, ComboBox>, HasComponents, ComboBox, Component> {
	public ComboBox() {
		super(ComboBoxElement.TAGNAME());
	}

	/**
	 *
	 */
	public Element inputElement() {
		return getNode().getInputElement();
	}

	/**
	 * Focusable element used by vaadin-control-state-mixin
	 */
	public Element focusElement() {
		return getNode().getFocusElement();
	}

	/**
	 * The label for this element.
	 */
	@Nullable
	public String label() {
		return getNode().getLabel();
	}

	/**
	 * The label for this element.
	 */
	public ComboBox label(String label) {
		getNode().setLabel(label);
		return this;
	}

	/**
	 * Set to true to mark the input as required.
	 */
	public boolean required() {
		return getNode().isRequired();
	}

	/**
	 * Set to true to mark the input as required.
	 */
	public ComboBox required(boolean required) {
		getNode().setRequired(required);
		return this;
	}

	/**
	 * Set to true to disable this input.
	 */
	public boolean disabled() {
		return getNode().isDisabled();
	}

	/**
	 * Set to true to disable this input.
	 */
	public ComboBox disabled(boolean disabled) {
		getNode().setDisabled(disabled);
		return this;
	}

	/**
	 * Set to true to prevent the user from entering invalid input.
	 */
	public boolean preventInvalidInput() {
		return getNode().isPreventInvalidInput();
	}

	/**
	 * Set to true to prevent the user from entering invalid input.
	 */
	public ComboBox preventInvalidInput(boolean preventInvalidInput) {
		getNode().setPreventInvalidInput(preventInvalidInput);
		return this;
	}

	/**
	 * A pattern to validate the input with.
	 */
	@Nullable
	public String pattern() {
		return getNode().getPattern();
	}

	/**
	 * A pattern to validate the input with.
	 */
	public ComboBox pattern(String pattern) {
		getNode().setPattern(pattern);
		return this;
	}

	/**
	 * The error message to display when the input is invalid.
	 */
	@Nullable
	public String errorMessage() {
		return getNode().getErrorMessage();
	}

	/**
	 * The error message to display when the input is invalid.
	 */
	public ComboBox errorMessage(String errorMessage) {
		getNode().setErrorMessage(errorMessage);
		return this;
	}

	public boolean autofocus() {
		return getNode().isAutofocus();
	}

	public ComboBox autofocus(boolean autofocus) {
		getNode().setAutofocus(autofocus);
		return this;
	}

	/**
	 * A placeholder string in addition to the label.
	 */
	@Nullable
	public String placeholder() {
		return getNode().getPlaceholder();
	}

	/**
	 * A placeholder string in addition to the label.
	 */
	public ComboBox placeholder(String placeholder) {
		getNode().setPlaceholder(placeholder);
		return this;
	}

	public boolean readonly() {
		return getNode().isReadonly();
	}

	public ComboBox readonly(boolean readonly) {
		getNode().setReadonly(readonly);
		return this;
	}

	/**
	 * Set to true to display the clear icon which clears the input.
	 */
	public boolean clearButtonVisible() {
		return getNode().isClearButtonVisible();
	}

	/**
	 * Set to true to display the clear icon which clears the input.
	 */
	public ComboBox clearButtonVisible(boolean clearButtonVisible) {
		getNode().setClearButtonVisible(clearButtonVisible);
		return this;
	}

	public HasSlots.Container prefix() {
		return slotted("prefix");
	}
}
Property name	Type	Description
`index`	Number	Index of the item in the `items` array
`item`	String or Object	The item reference
`selected`	Boolean	True when item is selected
`focused`	Boolean	True when item is focused
Attribute	Description	Part name
`opened`	Set when the combo box dropdown is open	:host
`disabled`	Set to a disabled combo box	:host
`readonly`	Set to a read only combo box	:host
`has-value`	Set when the element has a value	:host
`invalid`	Set when the element is invalid	:host
`focused`	Set when the element is focused	:host
`focus-ring`	Set when the element is keyboard focused	:host
`loading`	Set when new items are expected	:host