From 3ada7ef8f5ba8df5a608f0ba33875592474e10b6 Mon Sep 17 00:00:00 2001
From: Erik Lumme <erik@vaadin.com>
Date: Thu, 14 Sep 2017 13:03:22 +0300
Subject: [PATCH] Migrate CreatingYourOwnConverterForString

---
 ...CreatingYourOwnConverterForString.asciidoc | 103 ++++++++++++++++++
 documentation/articles/contents.asciidoc      |   1 +
 2 files changed, 104 insertions(+)
 create mode 100644 documentation/articles/CreatingYourOwnConverterForString.asciidoc

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]
-- 
2.39.5