tutorial-webcomponent-events.asciidoc

Using Events with a Polymer Web Component

This tutorial covers listening to events emitted by a web component and is a continuation of the Basic Integration of a Polymer Web Component and Using Attributes and Properties with a Polymer Web Component tutorials. For information about events, see the Listening to User Events tutorial.

The standard way for Polymer Web Components to inform about changes inside the component is through firing events. The events fired by the <paper-slider> element are documented at https://elements.polymer-project.org/elements/paper-slider#events.

For a basic integration, the most important event is value-change. This event is fired whenever the slider’s value changes, regardless of what causes the change (user interaction or API call). To be able to use this event in the server side API, an event class which is bound to the value-change DOM event is needed:

@DomEvent("value-change")
public class ValueChangeEvent extends ComponentEvent<PaperSlider> {
    public ValueChangeEvent(PaperSlider source, boolean fromClient) {
        super(source, fromClient);
    }
}

To be able to access the value on the server, you can add a getter to the component class and annotate it using @Synchronize so that property changes are automatically synchronized/sent from the browser to the server:

public class PaperSlider extends Component {

  @Synchronize("value-change")
  public int getValue() {
      return getElement().getProperty("value", 0);
  }
}

Property synchronization takes place before events are fired so the event listener can use ValueChangeEvent.getSource().getValue() to get the new value. There should be a public addValueChangeListener so the component user can listen to the event:

public class PaperSlider extends Component {
  public EventRegistrationHandle addValueChangeListener(
        ComponentEventListener<ValueChangeEvent> valueChangeListener) {
    return super.addListener(ValueChangeEvent.class, valueChangeListener);
  }
}

The example uses the same event methods described in the Listening to User Events tutorial as there is no difference between configuring an event for a built in element and for a web component element.

The final integration of <paper-slider> with support for value, pin and listening to value change events is:

@DomEvent("value-change")
public class ValueChangeEvent extends ComponentEvent<PaperSlider> {
    public ValueChangeEvent(PaperSlider source, boolean fromClient) {
        super(source, fromClient);
    }
}

@Tag("paper-slider")
@HtmlImport("context://bower_components/paper-slider/paper-slider.html")
public class PaperSlider extends Component {

    public void setValue(int value) {
        getElement().setProperty("value", value);
    }

    @Synchronize("value-change")
    public int getValue() {
        return getElement().getProperty("value", 0);
    }

    public void setPinVisible(boolean pinVisible) {
        getElement().setProperty("pin", pinVisible);
    }

    public boolean isPinVisible() {
        return getElement().getProperty("pin", false);
    }

    public EventRegistrationHandle addValueChangeListener(
            ComponentEventListener<ValueChangeEvent> valueChangeListener) {
        return super.addListener(ValueChangeEvent.class, valueChangeListener);
    }
}