Migrate CreatingYourOwnConverterForString

2 files changed, 104 insertions, 0 deletions

diff --git a/documentation/articles/CreatingYourOwnConverterForString.asciidoc b/documentation/articles/CreatingYourOwnConverterForString.asciidoc
new file mode 100644
index 0000000000..b18975cd2b
--- /dev/null
+++ b/documentation/articles/CreatingYourOwnConverterForString.asciidoc
@@ -0,0 +1,103 @@
+[[creating-your-own-converter-for-string]]
+Creating your own converter for String
+--------------------------------------
+
+If you have custom types that you want to represent using the built in
+field components, you can easily create your own converter to take care
+of converting between your own type and the native data type of the
+field.
+
+A sample custom type, in this case a Name object with separate fields
+for first and last name.
+
+[source,java]
+....
+public class Name {
+  private String firstName;
+  private String lastName;
+
+  public Name(String firstName, String lastName) {
+    this.firstName = firstName;
+    this.lastName = lastName;
+  }
+
+  public String getFirstName() {
+    return firstName;
+  }
+
+  public void setFirstName(String firstName) {
+    this.firstName = firstName;
+  }
+
+  public String getLastName() {
+    return lastName;
+  }
+
+  public void setLastName(String lastName) {
+    this.lastName = lastName;
+  }
+}
+....
+
+A converter for the name, assuming the parts are separated with a space
+and that there are only two parts of a name.
+
+[source,java]
+....
+public class StringToNameConverter implements Converter<String, Name> {
+  public Name convertToModel(String text, Locale locale)
+      throws ConversionException {
+    if (text == null) {
+      return null;
+    }
+    String[] parts = text.split(" ");
+    if (parts.length != 2) {
+      throw new ConversionException("Can not convert text to a name: " + text);
+    }
+    return new Name(parts[0], parts[1]);
+  }
+
+  public String convertToPresentation(Name name, Locale locale)
+      throws ConversionException {
+    if (name == null) {
+      return null;
+    } else {
+      return name.getFirstName() + " " + name.getLastName();
+    }
+  }
+
+  public Class<Name> getModelType() {
+    return Name.class;
+  }
+
+  public Class<String> getPresentationType() {
+    return String.class;
+  }
+}
+....
+
+Hooking up the Name type and its Converter to a TextField can then be
+done like this
+
+[source,java]
+....
+Name name = new Name("Rudolph", "Reindeer");
+
+final TextField textField = new TextField("Name");
+textField.setConverter(new StringToNameConverter());
+textField.setConvertedValue(name);
+
+addComponent(textField);
+addComponent(new Button("Submit value", new ClickListener() {
+  public void buttonClick(ClickEvent event) {
+    try {
+      Name name = (Name) textField.getConvertedValue();
+      Notification.show(
+              "First name: " + name.getFirstName() +
+              "<br />Last name: " + name.getLastName());
+    } catch (ConversionException e) {
+      Notification.show(e.getCause().getMessage());
+    }
+  }
+}));
+....
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 0c5ce7f0af..b76b66d54f 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -5,3 +5,4 @@
 - link:LazyQueryContainer.asciidoc[Lazy query container]
 - link:UsingJDBCwithLazyQueryContainerAndFilteringTable.asciidoc[Using JDBC with Lazy Query Container and FilteringTable]
 - link:OfflineModeForTouchKit4MobileApps.asciidoc[Offline mode for TouchKit 4 mobile apps]
+- link:CreatingYourOwnConverterForString.asciidoc[Creating your own converter for String]