Migrate documentation files and change typo

1 files changed, 87 insertions, 0 deletions

diff --git a/documentation/articles/UsingURIFragments.asciidoc b/documentation/articles/UsingURIFragments.asciidoc
new file mode 100644
index 0000000000..eebdf78303
--- /dev/null
+++ b/documentation/articles/UsingURIFragments.asciidoc
@@ -0,0 +1,87 @@
+[[using-uri-fragments]]
+Using URI fragments
+-------------------
+
+[[reading-fragment-when-initializing-ui]]
+Reading Fragment when Initializing UI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+URI fragments can either be used for initializing the UI and/or read or
+modified in any listener. In the UI.init method you get a "VaadinRequest
+request" parameter. The UI's Page contains a information about the HTTP
+request used to initialize the application and you can get the URI
+fragment using
+
+....
+getPage().geUriFragment()
+....
+
+A simple init that depends on the URI fragment is thus:
+
+[source,java]
+....
+public class MyUI extends UI {
+  @Override
+  protected void init(VaadinRequest request) {
+    layout = new VerticalLayout();
+    layout.setMargin(true);
+    setContent(layout);
+
+    Label label = new Label("Hello, your fragment is "
+            + getPage().getUriFragment());
+    layout.addComponent(label);
+  }
+}
+....
+
+[[reading-fragment-changes]]
+Reading Fragment Changes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The URI fragment can be changed also when the application is running,
+either manually in the location bar in browser or from user code. These
+changes can be caught with a **FragmentChangedListener**. Notice,
+however, that there is no event fired for the initial URL fragment. The
+easiest way to handle both cases in the same way is to call the same
+method from the FragmentChangedListener and the init method:
+
+[source,java]
+....
+public class MyUI extends UI {
+  // ...
+
+  // React to fragment changes
+  getPage().addUriFragmentChangedListener(new UriFragmentChangedListener() {
+    @Override
+    public void uriFragmentChanged(UriFragmentChangedEvent source) {
+      handleFragment(source.getUriFragment());
+    }
+  });
+
+  // Handle the fragment received in the initial request
+  handleFragment(getPage().getUriFragment());
+
+  addComponent(new Button("Show and set fragment", new Button.ClickListener() {
+    @Override
+      public void buttonClick(ClickEvent event) {
+        handleFragment(getPage().getUriFragment());
+        getPage().setUriFragment("customFragment");
+      }
+  }));
+....
+
+[[reading-and-writing-the-fragment]]
+Reading and Writing the Fragment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To later on read the fragment you can use
+
+....
+Page.getCurrent().getUriFragment();
+....
+
+and to set the fragment
+
+....
+Page.getCurrent().setUriFragment(String fragment);
+....