Migrate documentation files and change typo

documentation/articles/AccessingWebPageAndBrowserInformation.asciidoc

@@ -0,0 +1,50 @@
+[[accessing-web-page-and-browser-information]]
+Accessing web page and browser information
+------------------------------------------
+
+Vaadin 7 includes a new *Page* class offering access to various
+client-side information and events concerning the web page and browser
+window in which the Vaadin UI resides. The Page instance corresponding
+to a given UI is accessed via the `getPage()` method of the UI or using
+a static method `Page.getCurrent()`.
+
+You can access the browser window size and add size change listeners:
+
+[source,java]
+....
+Page page = someUI.getPage();
+page.addBrowserWindowResizeListener(new BrowserWindowResizeListener() {
+  public void browserWindowResized(BrowserWindowResizeEvent event) {
+    Notification.show("Window width=" + event.getWidth() + ", height=" + event.getHeight());
+  }
+});
+....
+
+You can access the optional fragment part of the location URI and add
+fragment change listeners:
+
+[source,java]
+....
+page.setUriFragment(page.getUriFragment() + "foo");
+page.addUriFragmentChangedListener(new UriFragmentChangedListener() {
+  public void uriFragmentChanged(UriFragmentChangedEvent event) {
+    Notification.show("Fragment=" + event.getUriFragment());
+  }
+});
+....
+
+You can access client browser details:
+
+[source,java]
+....
+Notification.show("IP" + browser.getAddress() +
+                "User-Agent:" + browser.getBrowserApplication() +
+                "Linux: " + browser.isLinux());
+....
+
+https://demo.vaadin.com/sampler/#foundation/advanced/browser-information[Live
+Demo]
+
+Note: If you are using a reverse proxy, you must get the value
+`X-Forwarded-For` from request headers. You cannot get a browser name,
+but you can check which browser are using.

documentation/articles/ConfiguringPushForYourEnviroment.asciidoc → documentation/articles/ConfiguringPushForYourEnvironment.asciidoc

@@ -1,6 +1,6 @@
 [[configuring-push-for-your-environment]]
-Configuring Push For Your Enviroment
-------------------------------------
+Configuring push for your environment
+-------------------------------------
 
 Server push and especially websockets are emerging technologies and not
 all servers and browsers handle them correctly (or even close to
@@ -37,7 +37,7 @@ Tomcat 6 + Streaming
 For Tomcat 6, falling back to streaming always results in an error message such as
 [source]
 ....
-Failed using comet support: org.atmosphere.container.TomcatCometSupport, error: Tomcat failed to detect this is a Comet application because context.xml is missing or the Http11NioProtocol Connector is not enabled.If that's not the case, you can also remove META-INF/context.xml and WEB-INF/lib/atmosphere-compat-tomcat.jar Is the Nio or Apr Connector enabled?WARNING: Using org.atmosphere.container.BlockingIOCometSupport`
+Failed using comet support: org.atmosphere.container.TomcatCometSupport, error: Tomcat failed to detect this is a Comet application because context.xml is missing or the Http11NioProtocol Connector is not enabled.If that's not the case, you can also remove META-INF/context.xml and WEB-INF/lib/atmosphere-compat-tomcat.jar Is the Nio or Apr Connector enabled?WARNING: Using org.atmosphere.container.BlockingIOCometSupport
 ....
 
 Atmosphere is expecting the Servlet to implement Tomcat's proprietary interface https://tomcat.apache.org/tomcat-6.0-doc/api/org/apache/catalina/CometProcessor.html[CometProcessor]. (See https://github.com/Atmosphere/atmosphere/blob/atmosphere-project-1.0.14/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereServlet.java[AtmosphereServlet])
@@ -116,10 +116,10 @@ Glassfish 3 + Websockets
 As a rule of thumb, don't do this.
 
 The Grizzly version shipped with Glassfish 3.1.2.2 contains a
-https://java.net/jira/browse/GRIZZLY-1289[fatal bug] which prevents
+https://github.com/javaee/grizzly/issues/1289[fatal bug] which prevents
 Vaadin from working. Replace *glassfish/modules/grizzly-websockets.jar*
 with
-https://java.net/jira/secure/attachment/50681/grizzly-websockets-1.9.50-fix.jar
+http://central.maven.org/maven2/com/sun/grizzly/grizzly-websockets/1.9.56/grizzly-websockets-1.9.56.jar
 to get websockets working (with Vaadin 7.3). *This version is actually
 also broken in many ways, so you may or may not get it to work. If you
 want websockets, you should upgrade to Glassfish 4.*

documentation/articles/GeneratingDynamicResourcesBasedOnURIOrParameters.asciidoc

@@ -0,0 +1,61 @@
+[[generating-dynamic-resources-based-on-uri-or-parameters]]
+Generating dynamic resources based on URI or parameters
+-------------------------------------------------------
+
+You can dynamically generate responses based on e.g. query parameters by
+creating your own `RequestHandler` and registering it with the session.
+
+In this way, you can for instance create an image that draws a text,
+given as a parameter to the image. This has been done in the example
+below:
+
+[source,java]
+....
+public class DynamicImageUI extends UI {
+  public static final String IMAGE_URL = "myimage.png";
+
+  private final RequestHandler requestHandler = new RequestHandler() {
+    @Override
+    public boolean handleRequest(VaadinSession session,
+          VaadinRequest request, VaadinResponse response)
+          throws IOException {
+      if (("/" + IMAGE_URL).equals(request.getPathInfo())) {
+        // Create an image, draw the "text" parameter to it and output
+        // it to the browser.
+        String text = request.getParameter("text");
+        BufferedImage bi = new BufferedImage(100, 30,
+                BufferedImage.TYPE_3BYTE_BGR);
+        bi.getGraphics().drawChars(text.toCharArray(), 0,
+                text.length(), 10, 20);
+        response.setContentType("image/png");
+        ImageIO.write(bi, "png", response.getOutputStream());
+
+        return true;
+      }
+      // If the URL did not match our image URL, let the other request
+      // handlers handle it
+      return false;
+    }
+  };
+
+  @Override
+  public void init(VaadinRequest request) {
+    Resource resource = new ExternalResource(IMAGE_URL + "?text=Hello!");
+
+    getSession().addRequestHandler(requestHandler);
+
+    // Add an image using the resource
+    Image image = new Image("A dynamically generated image", resource);
+
+    setContent(image);
+  }
+
+  @Override
+  public void detach() {
+    super.detach();
+
+    // Clean up
+    getSession().removeRequestHandler(requestHandler);
+  }
+}
+....

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);
+....

documentation/articles/contents.asciidoc

@@ -21,7 +21,7 @@ are great, too.
 - link:SendingEmailFromJavaApplications.asciidoc[Sending email from Java applications]
 - link:OptimizingSluggishUI.asciidoc[Optimizing sluggish UI]
 - link:UsingParametersWithViews.asciidoc[Using parameters with views]
-- link:ConfiguringPushForYourEnviroment.asciidoc[Configuring push for your environment]
+- link:ConfiguringPushForYourEnvironment.asciidoc[Configuring push for your environment]
 - link:SettingAndReadingCookies.asciidoc[Setting and reading cookies]
 - link:UsingPolling.asciidoc[Using polling]
 - link:FindingTheCurrentUIAndPageAndVaadinSession.asciidoc[Finding the current UI and page and Vaadin Session]
@@ -32,3 +32,6 @@ are great, too.
 - link:RememberToTheSetTheLocale.asciidoc[Remember to the set the locale]
 - link:MVCBasicsInITMillToolkit.asciidoc[MVC Basics in IT Mill Toolkit]
 - link:CustomizingTheStartupPageInAnApplication.asciidoc[Customizing the startup page in an application]
+- link:UsingURIFragments.asciidoc[Using URI fragments]
+- link:AccessingWebPageAndBrowserInformation.asciidoc[Accessing web page and browser information]
+- link:GeneratingDynamicResourcesBasedOnURIOrParameters.asciidoc[Generating dynamic resources based on URI or parameters]