implementing.rst 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223
  1. .. _wicket_ui_implementing:
  2. Implementing a Wicket UI Extension
  3. ==================================
  4. This section describes how to implement an extension to the GeoServer Wicket
  5. user interface. The extension will be extremely simple and will be a basic page
  6. that is linked from the main menu and displays the message "Hello World".
  7. Prerequisites
  8. -------------
  9. Before being able to proceed, GeoServer must be built on the local system. See
  10. the :ref:`source` and :ref:`quickstart` sections for details.
  11. Create a new module
  12. -------------------
  13. #. Create a new module named ``hello_web`` somewhere on the file system
  14. #. Add the following ``pom.xml`` to the root of the new module:
  15. .. code-block:: xml
  16. <project xmlns="http://maven.apache.org/POM/4.0.0"
  17. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  18. xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd ">
  19. <modelVersion>4.0.0</modelVersion>
  20. <parent>
  21. <groupId>org.geoserver</groupId>
  22. <artifactId>web</artifactId>
  23. <version>2.8-SNAPSHOT</version> <!-- change this to the proper GeoServer version -->
  24. </parent>
  25. <groupId>org.geoserver</groupId>
  26. <artifactId>hello_web</artifactId>
  27. <packaging>jar</packaging>
  28. <version>1.0-SNAPSHOT</version>
  29. <name>hello_web</name>
  30. <dependencies>
  31. <dependency>
  32. <groupId>org.geoserver.web</groupId>
  33. <artifactId>gs-web-core</artifactId>
  34. <version>2.8-SNAPSHOT</version> <!-- change this to the proper GeoServer version -->
  35. </dependency>
  36. </dependencies>
  37. </project>
  38. #. Create the directory ``src/main/java`` under the root of the new module::
  39. [hello_web]% mkdir -p src/main/java
  40. Create the page class
  41. ---------------------
  42. #. The class ``org.geoserver.web.GeoServerBasePage`` is the base class for all
  43. pages in GeoServer. Create a new class called ``HelloPage`` in the package
  44. ``org.geoserver.helloweb``, which extends from ``GeoServerBasePage``:
  45. .. code-block:: java
  46. package org.geoserver.helloweb;
  47. import org.geoserver.web.GeoServerBasePage;
  48. public class HelloPage extends GeoServerBasePage {
  49. }
  50. #. The first task is to implement the constructor. In Wicket a page or component
  51. builds itself in its constructor. This page is basic and will simply create
  52. a label which has the value "Hello World!":
  53. .. code-block:: java
  54. import org.apache.wicket.markup.html.basic.Label;
  55. ...
  56. public HelloPage() {
  57. add( new Label( "hellolabel", "Hello World!") );
  58. }
  59. In the above code, an instance of ``Label`` is created. The first argument
  60. to its constructor is the **component id**. In Wicket every component must
  61. have an id. In the next section this id will be used to bind the component to
  62. its HTML presentation. The second argument to the ``Label`` constructor is
  63. the value of the world, in this case the string "Hello World!"
  64. Create the page presentation
  65. ----------------------------
  66. #. With the page completed, the next step is to create the HTML presentation for
  67. the page. To do this create a file named ``HelloPage.html`` in the same
  68. directory as the ``HelloPagejava`` class:
  69. .. code-block:: html
  70. <html>
  71. <body>
  72. <wicket:extend>
  73. <div wicket:id="hellolabel"></div>
  74. </wicket:extend>
  75. </body>
  76. </html>
  77. There are few things to note about the HTML. The first is the use of the
  78. ``<wicket:extend>`` element. This tells wicket that ``HelloPage`` is an
  79. extension of another page, in this case ``GeoServerBasePage``, and it should
  80. inherit presentation from that page.
  81. The second thing to note is the attribute ``wicket:id`` on the ``<div>``
  82. element. This is what binds the ``<div>`` tag to the ``Label`` component
  83. created in the previous section. The value of ``wicket:id`` must match the
  84. id given to the component, in this case "hellolabel".
  85. Create the i18n file
  86. --------------------
  87. With Wicket (and any web application framework), any string that appears in the
  88. web application should be interationalized. In GeoServer, this is performed by
  89. creating an internationalization (i18n) file named
  90. ``GeoServerApplication.properties``.
  91. #. Create the directory ``src/main/resources`` under the root of the
  92. ``hello_web`` module::
  93. [hello_web]% mkdir -p src/main/resources
  94. #. Create the (i18n) file ``GeoServerApplication.properties`` in the ``src/main/resources`` directory::
  95. HelloPage.page.title=Hello
  96. HelloPage.page.description=A page to say hello
  97. HelloPage.title=Hello Page Title
  98. HelloPage.description=This is the description of the page
  99. The first two keys in the above i18n file declare the title of the page and the description
  100. of the page. This will be the title of the link to the page and the tooltip for the page link.
  101. The next two keys are the title and description that are displayed on the page itself.
  102. Create the application context
  103. -------------------------------
  104. #. The final step is to create an application context which tells GeoServer
  105. about the page created in the previous section. Add the following
  106. ``applicationContext.xml`` file to the ``src/main/java`` directory, under the root
  107. of the ``hello_web`` module:
  108. .. code-block:: xml
  109. <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
  110. <beans>
  111. <bean id="helloPage" class="org.geoserver.web.MenuPageInfo">
  112. <property name="id" value="helloPage"/>
  113. <property name="titleKey" value="HelloPage.page.title"/>
  114. <property name="descriptionKey" value="HelloPage.page.description"/>
  115. <property name="componentClass" value="org.geoserver.helloweb.HelloPage"/>
  116. </bean>
  117. </beans>
  118. The above bean declaration declares an instance of the ``MenuPageInfo`` class
  119. which is a descriptor for pages linked from the main page of the GeoServer
  120. web application. The property ``titleKey`` is the title of the page and it
  121. receives the value of the title i18n key created in the previous section.
  122. Similar for the ``descriptionKey`` property.
  123. Test the extension
  124. ------------------
  125. At this point, the ``hello_web`` module should look like the following::
  126. hello_web/
  127. pom.xml
  128. src/main/resources
  129. GeoServerApplication.properties
  130. src/main/java
  131. applicationContext.xml
  132. org/geoserver/helloweb/
  133. HelloPage.java
  134. HelloPage.html
  135. #. Build the ``hello_web`` module::
  136. [hello_web]% mvn install
  137. #. Copy the ``hello_web-1.0-SNAPSHOT.jar`` file from the ``hello_web/target``
  138. directory into the ``WEB-inf/lib`` directory of a GeoServer installation::
  139. [hello_web]% cp target/hello-1.0-SNAPSHOT.jar /home/bob/geoserver-2.0/webapps/geoserver/WEB-INF/lib
  140. .. note::
  141. If running GeoServer from eclipse you can edit the :file:`web-app/pom.xml` with the following dependency:
  142. .. code-block:: xml
  143. <dependency>
  144. <groupId>org.geoserver</groupId>
  145. <artifactId>hello_web</artifactId>
  146. <version>1.0-SNAPSHOT</version>
  147. </dependency>
  148. You will need to run `mvn eclipse:eclipse` after editing :file:`web-app/pom.xml` and then you can refresh the :file:`gs-web-app` project in eclipse so it notices the new jar.
  149. #. Start or restart GeoServer
  150. #. Navigate to http://localhost:8080/geoserver/web
  151. Upon success a link titled ``Hello`` should appear in the menu on the left side
  152. of the main GeoServer page. Following the link brings up the ``HelloPage``
  153. .. image:: test.jpg