Using Model Encoders

Encoding Property Types
Using Encoders to Split Property Values

Polymer templates are deprecated. Lit templates are recommended instead.

Template model and model data aren’t supported for Lit templates. You may use component API and properties via the Element API directly to achieve the same functionality.

Using ready-made beans in your model can be challenging if you have no control over their properties (because they are provided as binary class files, for example) or their structure is inappropriate for your template model.

Encoding Property Types

You can use the @Encode annotation to encode any property type to a supported type.

A common use case is a database backend with JPA entities that have identifiers of the Long type. Vaadin doesn’t support the Long type, because it can’t be mapped correctly to any JavaScript type.

One solution is to exclude any property of this type using the @Exclude annotation. See PolymerTemplate, Using Model Beans for an example of how to use this annotation.

Alternatively, you can use the @Encode annotation. This is useful when you need a bean property with this identifier on the client side for any reason, for example to reference it. In these circumstances, the @Encode annotation encodes the Long value to a String value and sends it to the client side as a string. When the client sends the value back, it’s decoded back to a Long.

Example: Defining the Person JPA entity class and using the @Encode annotation in the template model class.

@Entity
public class Person implements Serializable {
    @Id
    @GeneratedValue
    private Long id;

    public Long getId() {
        return id;
    }

}

public interface MyModel extends TemplateModel {
   @Encode(value = LongToStringEncoder.class, path = "id")
   void setPerson(Person person);
   Person getPerson();
}

The @Encode annotation parameter path = "id" is used to address the id sub-property of the person property. By default, the path value is "", which means that an encoder is applied to the property itself, in this case the Person.

Example: LongToStringEncoder encoder.

public class LongToStringEncoder implements ModelEncoder<Long, String> {

    @Override
    public String encode(Long modelValue) {
        return Optional.ofNullable(modelValue).map(Object::toString)
                .orElse(null);
    }

    @Override
    public Long decode(String presentationValue) {
        return Optional.ofNullable(presentationValue).map(Long::valueOf)
                .orElse(null);
    }

}

You can access the id property of the Person bean in your code on the client side in the usual way. It’s of the String type, instead of a number.

Using Encoders to Split Property Values

An encoder can also be used to split a single property value into several sub-properties to use them in different UI controls. For example, you may want to have three input fields (day, month, and year) for a birth date field, instead of one.

Example: Using the @Encode annotation in to define the Date property in a template model.

public interface MyModel extends TemplateModel {

    Date getBirthDate();

    @Encode(DateToDateBeanEncoder.class)
    void setBirthDate(Date birthDate);
}

Example: Defining the DateBean class.

public class DateBean implements Serializable {

    private String day;
    private String month;
    private String year;

    public String getDay() {
        return day;
    }

    public void setDay(String day) {
        this.day = day;
    }

    public String getMonth() {
        return month;
    }

    public void setMonth(String month) {
        this.month = month;
    }

    public String getYear() {
        return year;
    }

    public void setYear(String year) {
        this.year = year;
    }

}

Example: Defining the DateToDateBeanEncoder encoder class.

public class DateToDateBeanEncoder implements ModelEncoder<Date, DateBean> {

    @Override
    public DateBean encode(Date modelValue) {
        if (modelValue == null) {
            return null;
        }
        DateBean bean = new DateBean();
        Calendar calendar = GregorianCalendar.getInstance();
        calendar.setTime(modelValue);
        bean.setDay(Integer.toString(calendar.get(Calendar.DAY_OF_MONTH)));
        bean.setMonth(Integer.toString(calendar.get(Calendar.MONTH) + 1));
        bean.setYear(Integer.toString(calendar.get(Calendar.YEAR)));
        return bean;
    }

    @Override
    public Date decode(DateBean presentationValue) {
        if (presentationValue == null) {
            return null;
        }
        int year = Integer.parseInt(presentationValue.getYear());
        int day = Integer.parseInt(presentationValue.getDay());
        int month = Integer.parseInt(presentationValue.getMonth()) - 1;
        Calendar calendar = GregorianCalendar.getInstance();
        calendar.set(year, month, day);
        return calendar.getTime();
    }

}

The Date property is encoded to three sub-properties: day, month and year.

Example: Using the sub-properties in a JavaScript Polymer template (snippet only).

static get template() {
  return html`
    <div style="width: 200px;">
      <label>Birth date:</label>
      <label for="day">Enter your birthday:</label><paper-input id="day" value="{{birthDate.day}}"></paper-input>
      <label for="month">Enter the month of your birthday:</label><paper-input id="month" value="{{birthDate.month}}"></paper-input>
      <label for="year">Enter the year of your birthday:</label><paper-input id="year" value="{{birthDate.year}}"></paper-input>
      <button on-click="commit" id="commit">Commit</button>
    </div>
  `;
}

Each of the three sub-properties (day, month, and year) has its own editor. On the server side, it’s still one property, birthDate.
You need use your original property name (birthDate in this example (not dateBean)) as a prefix to access the sub-properties.

61E9D5CF-4BBB-4EEC-A065-238749537BA3

Documentation

Documentation

Using Model Encoders

Encoding Property Types

Using Encoders to Split Property Values