From fb207248d5567a2661d5729d5149c7c8920a2efa Mon Sep 17 00:00:00 2001 From: Henri Muurimaa Date: Mon, 11 Sep 2017 11:57:15 +0300 Subject: Migrate wiki articles to Vaadin documentation (#9912) * Vaadin Tutorial For Swing Developers * Setting And Reading Session Attributes * Enabling Server Push * Cleaning Up Resources In A UI * Sending Email From Java Applications * Using Parameters With Views * Optimizing Sluggish UI * Configuring Push For Your Enviroment * Setting And Reading Cookies * Using Polling * Creating An Application That Preserves State On Refresh * Finding The Current UI And Page And Vaadin Session * Sending Events From The Client To The Server Using RPC * Handling Logout * Remember To Set The Locale * Scalable Web Applications * MVC Basics In ITMill Toolkit * Access Control For Views * Customizing The Startup Page In An Application --- ...stomizingTheStartupPageInAnApplication.asciidoc | 114 +++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 documentation/articles/CustomizingTheStartupPageInAnApplication.asciidoc (limited to 'documentation/articles/CustomizingTheStartupPageInAnApplication.asciidoc') diff --git a/documentation/articles/CustomizingTheStartupPageInAnApplication.asciidoc b/documentation/articles/CustomizingTheStartupPageInAnApplication.asciidoc new file mode 100644 index 0000000000..d48fcc6e39 --- /dev/null +++ b/documentation/articles/CustomizingTheStartupPageInAnApplication.asciidoc @@ -0,0 +1,114 @@ +[[customizing-the-startup-page-in-an-application]] +Customizing the startup page in an application +---------------------------------------------- + +In Vaadin 6, the startup page - used to bootstrap a new Vaadin UI +instance in the browser - was generated as a monolithic chunk of HTML +and was not easily customizable. In Vaadin 7, we added a new facility +for registering special _bootstrap listeners_ that are invoked before +the bootstrap response is sent. In addition, instead of bare HTML in a +string, the response is now built as a DOM tree that is easy to +manipulate programmatically. + +Here's an example of a simple bootstrap listener: + +[source,java] +.... +import org.jsoup.nodes.Comment; +import org.jsoup.nodes.Element; +import org.jsoup.nodes.Node; +import org.jsoup.parser.Tag; + +// ... + +new BootstrapListener() { + @Override + public void modifyBootstrapPage(BootstrapPageResponse response) { + response.getDocument().body().appendChild(new Comment("Powered by Vaadin!", "")); + } + + @Override + public void modifyBootstrapFragment(BootstrapFragmentResponse response) { + // Wrap the fragment in a custom div element + Element myDiv = new Element(Tag.valueOf("div"), ""); + List nodes = response.getFragmentNodes(); + for(Node node : nodes) { + myDiv.appendChild(node); + } + nodes.clear(); + nodes.add(myDiv); + } +} +.... + +The HTML library we use is http://jsoup.org/[jsoup]. It provides a very +convenient API for traversing, manipulating and extracting data from a +DOM, and is HTML5 compliant. + +The `BootstrapListener` interface contains two methods, one of which is +usually left empty. This is because a Vaadin application can be either +stand-alone, in which case it "owns" the whole page its UI resides in, +or embedded, such as a portlet, in which case it does not control the +content of the page it is embedded in. + +The `modifyBootstrapFragment` method is called in both cases. It +receives a `BootstrapFragmentResponse` that represents the HTML fragment +that is inserted in the host page, whether the page is controlled by +Vaadin or not. Hence, you only need to implement this method if you do +not care about the host page, whether your application is embedded or +standalone. + +The `modifyBootstrapPage` method is called with a +`BootstrapPageResponse` argument that represents the whole bootstrap +page, including the fragment mentioned above. Thus, it is only invoked +when the application is standalone and actually responsible for +generating the page. This method allows you to, for instance, add things +to the `head` element. The `BootstrapPageResponse` class also allows +setting arbitrary HTTP response headers: + +[source,java] +.... +public void modifyBootstrapPage(BootstrapPageResponse response) { + response.setHeader("X-Powered-By", "Vaadin 7"); +} +.... + +But how and where should the bootstrap listeners be registered? It +should be only once per session, and right in the beginning, so that +they are already added when the first response is sent. + +To do that you should write a custom servlet that extends +`VaadinServlet`, or a custom portlet extending `VaadinPortlet`, and a +session init listener that adds the bootstrap listener to the new +session. + +[source,java] +.... +class MyVaadinServlet extends VaadinServlet { + @Override + protected void servletInitialized() throws ServletException { + super.servletInitialized(); + getService().addSessionInitListener(new SessionInitListener() { + @Override + public void sessionInit(SessionInitEvent event) { + event.getSession().addBootstrapListener(listener); + } + }); + } +} + +// Or... + +class MyVaadinPortlet extends VaadinPortlet { + @Override + protected void portletInitialized() throws PortletException { + super.portletInitialized(); + getService().addSessionInitListener(new SessionInitListener() { + @Override + public void sessionInit(SessionInitEvent event) { + event.getSession().addBootstrapListener(listener); + } + }); + } +} +.... -- cgit v1.2.3