Create and Run Your First ZK Application with Eclipse and Maven

From Documentation


DocumentationZK Installation GuideQuick StartCreate and Run Your First ZK Application with Eclipse and Maven
Create and Run Your First ZK Application with Eclipse and Maven



How to create ZK Maven web project

Create Project of Maven

  • [File] -> [New] -> [Other] --> [Maven Project]
    ZK Installation Guide Maven step1.png
  • Make sure Create a simple project is unticked in the first screen of the New Maven Project wizard and click Next >.
    ZK Installation Guide Maven Archetype step1.png
  • From the Select an Archetype screen, to add the ZK archetype catalog. Click Configure.
    ZK Installation Guide Maven Archetype step2.png
  • A "Preferences"screen will pop up and from the Maven archetypes catalogs setting, click Add Remote Catalogand type in the catalog file as illustrated:
    ZK Installation Guide Maven Archetype step3.png
http://mavensync.zkoss.org/maven2/
  • Click Verify and then OK to add the catalog.
    • If the Remote catalog is empty.[1]
  • Now click OK in the "Preferences" dialogue box.
  • Now the user should be able to find zk from the Catalog dropdown list.
    ZK Installation Guide Maven Archetype step4.png
  • Select zk-archetype-webapp from the list. (At time of writing this is at version 0.8.0).
  • Next, fill in details for group id, artifact id, version number and package name.
    ZK Installation Guide Maven Archetype step5.png
    • If the property zk-version-since is missing.[2]
  • Click Finish and the Eclipse status bar should say ' Creating zk-archetype-webapp ' and ' Updating Maven Dependencies '. If this the user's first time dealing with ZK libraries, Maven will download the necessary dependencies to compile and run this example, and would be stored in .m2/repository in the user's home directory.
    ZK Installation Guide Maven Archetype step6.png

  1. If an error message appears stating that the Remote catalog is empty, this is most likely due to a bug in the m2eclipse plugin in v0.12.x, MNGECLIPSE-2757. Until m2eclipse 0.13.x or newer versions are released and available, there are two possible workarounds:
    1. Install the "Older version" 0.10.x from the Installing m2eclipse website. Users will first need to uninstall m2eclipse 0.12.x, restart, and then install 0.10.x available from the following site:
      http://m2eclipse.sonatype.org/sites/m2e/0.10.2.20100623-1649/
    2. Create the plugin from the archetype using the Maven command line tool mvn, then use import existing maven project to add the generated project to Eclipse. For more details, please refer to Use the command line version of Maven for creating the project.
  2. Users who are running this wizard for the first time, m2eclipse will not have downloaded the zk archetype yet, and as a result may not populate the zk-version-since property correctly, leading to an error message like the following:
    • Unable to create project from archetype [org.zkoss:zk-archetype-webapp:0.8.0 -> http://mavensync.zkoss.org/maven2/], Archetype org.zkoss:zk-archetype-webapp:0.8.0 is not configured property zk-version-since is missing.
    The simple workaround for this problem is to just try again and the zk-version-since property should appear in the list.

How to run Maven project on Run-Jetty-Run

  1. Go to Run Configurations
    ZK Installation Guide maven Archetype run1.png
  2. Double click on Jetty Webapp
    • It will automatically fill-out Project / Ports / Context / WebApp Dir
    ZK Installation Guide maven Archetype run2.png
  3. Click Run and start browsing local ZK application at http://127.0.0.1:8080/myapp/

Packing your project

  1. Goto Run As > Maven package
    ZK Installation Guide maven Archetype pak1.png
  2. The project will then be packed into a war file and a zip file with source code.
    ZK Installation Guide maven Archetype pak2.png

Use the command line version of Maven to create a project

  • For instructions on how to set up maven, please refer to Maven.
  • Go to the folder in the Eclipse workspace, then run the following command:
  • Calling archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/ - the plugin will first ask to choose the archetype from the zk catalog, please just enter the number of the archetype.
  • It will then ask the user to enter the values for groupId, the artifactId and the version of the project to create and the base package for the sources.
  • It will then ask for confirmation of the configuration and perform the creation of the project.
  • In the following example, we selected the webapp archetype (numbered 2) and set groupId to org.test, artifactId to myapp, version to 1.0-SNAPSHOT and package to org.test.myapp.
$ mvn archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] [archetype:generate {execution: default-cli}]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: http://mavensync.zkoss.org/maven2/ -> zk-archetype-component (zk-archetype-component)
2: http://mavensync.zkoss.org/maven2/ -> zk-archetype-webapp (zk-archetype-webapp)
Choose a number: : 2
Downloading: http://mavensync.zkoss.org/maven2//org/zkoss/zk-archetype-webapp/0.8.0/zk-archetype-webapp-0.8.0.jar
11K downloaded  (zk-archetype-webapp-0.8.0.jar)
Downloading: http://mavensync.zkoss.org/maven2//org/zkoss/zk-archetype-webapp/0.8.0/zk-archetype-webapp-0.8.0.pom
1K downloaded  (zk-archetype-webapp-0.8.0.pom)
Define value for property 'groupId': : org.test
Define value for property 'artifactId': : myapp
Define value for property 'version': 1.0-SNAPSHOT:
Define value for property 'package': org.test: org.test.myapp
[INFO] Using property: zk-version-since = 5.0.6
Confirm properties configuration:
groupId: org.test
artifactId: myapp
version: 1.0-SNAPSHOT
package: org.test.myapp
zk-version-since: 5.0.6
Y:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 22 seconds
[INFO] Finished at: Thu Jul 28 12:07:19 CST 2011
[INFO] Final Memory: 12M/150M
[INFO] ------------------------------------------------------------------------

Import Maven project into Eclipse

  • [File] -> [Import] -> [Maven] --> [Existing Maven Projects]
    ZK Installation Guide Maven Archetype import1.png
  • After this you should get three new projects in your Package explorer.
    ZK Installation Guide Maven Archetype step6.png