Creating ZK Component with Maven Archetype"

From Documentation
(Created page with "=How to create ZK Component Maven project= == Create Project of Maven== *'''[File]''' -> '''[New]''' -> '''[Other]''' --> '''[Maven Project]''' *:[[File:ZK_Installation_Guide_Mav...")
 
m (→‎Create a Maven Project: Fix reference zk link)
 
(21 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=How to create ZK Component Maven project=
+
{{ZKComponentDevelopmentEssentialsPageHeader}}
== Create Project of Maven==
+
 
 +
=How to create a ZK Component Maven project=
 +
== Create a Maven Project==
 
*'''[File]''' -> '''[New]''' -> '''[Other]''' --> '''[Maven Project]'''
 
*'''[File]''' -> '''[New]''' -> '''[Other]''' --> '''[Maven Project]'''
 
*:[[File:ZK_Installation_Guide_Maven_step1.png]]
 
*:[[File:ZK_Installation_Guide_Maven_step1.png]]
*Make sure ''Create a simple project'' is not ticked in the first screen of the New Maven Project wizard and click '''Next >'''.
+
*Make sure ''Create a simple project'' is unticked in the first screen of the New Maven Project wizard and click '''Next >'''.
 
*:[[File:ZK_Installation_Guide_Maven_Archetype_step1.png]]
 
*:[[File:ZK_Installation_Guide_Maven_Archetype_step1.png]]
*From the ''Select an Archetype'' screen, we'll need to add the ZK archetype catalog. Click '''Configure...'''.
+
*From the ''Select an Archetype'' screen, select '''zk'''<ref>To add a ZK archetype catalog, click '''Configure''' then refer to [[ZK_Installation_Guide/Quick_Start/Create_and_Run_Your_First_ZK_Application_with_Eclipse_and_Maven | Create and Run Your First ZK Application with Eclipse and Maven]] for the complete instruction.</ref> from the catalog dropdown list.
*:[[File:ZK_Installation_Guide_Maven_Archetype_step2.png]]
 
*From the Maven archetypes catalogs setting, click ''Add Remote Catalog''... and add the catalog file:
 
*:[[File:ZK_Installation_Guide_Maven_Archetype_step3.png]]
 
http://mavensync.zkoss.org/maven2/
 
*Click '''Verify...''' and then '''OK''' to add the catalog.
 
**Remote catalog is <font color="red">empty</font>.<ref>
 
If you receive the error message Remote catalog is empty, this is most likely due to a bug in the m2eclipse plugin in v0.12.x, [https://issues.sonatype.org/browse/MNGECLIPSE-2757 MNGECLIPSE-2757].
 
Until m2eclipse 0.13.x or newer are released, there are two possible workarounds:
 
#Install the "''Older version''" 0.10.x from the [http://m2eclipse.sonatype.org/installing-m2eclipse.html Installing m2eclipse] website. You'll need to first uninstall m2eclipse 0.12.x, restart and then install 0.10.x from these install sites:
 
#: http://m2eclipse.sonatype.org/sites/m2e/0.10.2.20100623-1649/
 
#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. please refer to [[#Use_the_command_line_version_of_Maven_for_creating_the_project |  Use the command line version of Maven for creating the project]].
 
</ref>
 
*Click '''OK''' in the "Preferences" dialogue.
 
*Now you should be able to find '''zk''' in the Catalog dropdown list.  
 
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp4.png‎]]
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp4.png‎]]
 
*Select the ''zk-archetype-component'' from the list. (At time of writing this is at version '''0.8.0''').
 
*Select the ''zk-archetype-component'' 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.
 
*Next, fill in details for ''group id, artifact id, version'' number and ''package'' name.
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp5.png‎]]
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp5.png‎]]
**Property zk-version-since is <font color="red">missing</font>.<ref>
+
**If property ''zk-version-since'' or ''component class'' is <font color="red">missing</font>.<ref>
The first time you run this wizard, m2eclipse will not yet have downloaded the zk archetype, and might not populate the zk-version-since property correctly, leading to an error message like:
+
Users who are running this wizard for the first time, zk archetype would not have been downloaded into m2eclipse yet, and as a result may not populate the property ''zk-version-since'' correctly, leading to an error message as such:
* Unable to create project from archetype [org.zkoss:zk-archetype-component:0.8.0 -> http://mavensync.zkoss.org/maven2/], Archetype org.zkoss:zk-archetype-component:0.8.0 is not configured Property zk-version-since is missing.
+
* Unable to create project from archetype [org.zkoss:zk-archetype-component:0.8.0 -> http://mavensync.zkoss.org/maven2/], Archetype org.zkoss:zk-archetype-component:0.8.0 is not configured property ''zk-version-since'' is missing.
  
The simple workaround is to just try again - this time the zk-version-since property should appear in the list. If it is still missing - add it with the value Example and try again.
+
The simple workaround for this problem is to just try again and the ''zk-version-since'' property should appear in the list. (The same apply to all other properties)
 
  </ref>
 
  </ref>
*Click '''Finish''' and the Eclipse status bar should say ' ''Creating zk-archetype-component'' ' and ' ''Updating Maven Dependencies'' '. If this is the first time you deal with ZK libraries, Maven will download the necessary dependencies to compile and run this example, and would be stored in ''.m2/repository'' in your home directory.
+
*Click '''Finish''' and the Eclipse status bar should say ' ''Creating zk-archetype-component'' ' and ' ''Updating Maven Dependencies'' '. If this is 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 your home directory.
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp6.png‎]]
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp6.png‎]]
 
----
 
----
Line 37: Line 25:
  
 
== How to run Maven project on Run-Jetty-Run ==
 
== How to run Maven project on Run-Jetty-Run ==
#Goto '''Run Configurations'''
+
#Go to '''Run Configurations'''
 
#: [[File:ZKComDevEss_Maven_CreateComponent_run1.png]]
 
#: [[File:ZKComDevEss_Maven_CreateComponent_run1.png]]
 
#Double click on '''Jetty Webapp'''  
 
#Double click on '''Jetty Webapp'''  
#* It will auto fill '''Project''' / '''Port''' / '''Context''' / '''WebApp Dir '''
+
#* It will automatically  fill-out '''Project''' / '''Port''' / '''Context''' / '''WebApp Dir '''
 
#: [[File:ZKComDevEss_Maven_CreateComponent_run2.png]]
 
#: [[File:ZKComDevEss_Maven_CreateComponent_run2.png]]
#Click '''Run''' and browse http://127.0.0.1:8080/mycomps/
+
#Click '''Run''' and start browsing local ZK application at http://127.0.0.1:8080/mycomps/
 +
 
 
== Packing your component==
 
== Packing your component==
#Goto '''Run As''' > '''Maven package'''
+
#Go to '''Run As''' > '''Maven package''' (or  '''Maven install ''')
 
#: [[File:ZKComDevEss_Maven_CreateComponent_pak1.png]]
 
#: [[File:ZKComDevEss_Maven_CreateComponent_pak1.png]]
#Your project will be pack into a war file and a zip file with source code.
+
#The project will then be packed into a jar file and a zip file with source code.
 
#: [[File:ZKComDevEss_Maven_CreateComponent_pak2.png]]
 
#: [[File:ZKComDevEss_Maven_CreateComponent_pak2.png]]
  
== Use the command line version of Maven for creating the project==
+
== Use the command line version of Maven to create a project==
*Here describes how to set up [http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Maven].
+
*For instructions on how to set up maven, please refer to [http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Maven].
*Go to the folder for your Eclipse workspace, then run this command.
+
*Go to the folder in 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. Just enter the number of the archetype.
+
*Calling ''archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/'' the plugin will first ask to choose the archetype from the zk catalog - just enter the number of the archetype.
*It then asks you to enter the values for the groupId, the artifactId and the version of the project to create and the base package for the sources.
+
*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 then asks for confirmation of the configuration and performs the creation of the project.
 
*It then asks for confirmation of the configuration and performs the creation of the project.
*In the following example, we selected the component archetype (numbered 1) and set ''groupId'' to '''org.test''', ''artifactId'' to '''mycomps''', ''version'' to '''1.0-SNAPSHOT''' and ''package'' to '''org.test.mycomps'''.
+
*In the following example, component archetype (number 1) is selected and ''groupId'' is set to '''org.test''', ''artifactId'' to '''mycomps''', ''version'' to '''1.0-SNAPSHOT''' and ''package'' to '''org.test.mycomps'''.
<source lang="dos" >
+
<source lang="text" >
 
$ mvn archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/
 
$ mvn archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/
 
[INFO] Scanning for projects...
 
[INFO] Scanning for projects...
Line 101: Line 90:
 
[INFO] ------------------------------------------------------------------------
 
[INFO] ------------------------------------------------------------------------
 
</source>
 
</source>
 +
 
== Import Maven project into Eclipse==
 
== Import Maven project into Eclipse==
 
*'''[File]''' -> '''[Import]''' -> '''[Maven]''' -->  '''[Existing Maven Projects]'''
 
*'''[File]''' -> '''[Import]''' -> '''[Maven]''' -->  '''[Existing Maven Projects]'''
 
*:[[File:ZKComDevEss_Maven_CreateComponent_import1.png]]
 
*:[[File:ZKComDevEss_Maven_CreateComponent_import1.png]]
*After this you should get three new projects in your Package explorer.
+
*After this, the user should now get a new project in the Package explorer.  
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp6.png‎]]
 
*:[[File:ZKComDevEss_Maven_CreateComponent_setp6.png‎]]

Latest revision as of 02:05, 6 December 2019


Creating ZK Component with Maven Archetype



How to create a ZK Component Maven project

Create a Maven Project

  • [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, select zk[1] from the catalog dropdown list.
    ZKComDevEss Maven CreateComponent setp4.png
  • Select the zk-archetype-component 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.
    ZKComDevEss Maven CreateComponent setp5.png
    • If property zk-version-since or component class is missing.[2]
  • Click Finish and the Eclipse status bar should say ' Creating zk-archetype-component ' and ' Updating Maven Dependencies '. If this is 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 your home directory.
    ZKComDevEss Maven CreateComponent setp6.png

  1. To add a ZK archetype catalog, click Configure then refer to Create and Run Your First ZK Application with Eclipse and Maven for the complete instruction.
  2. Users who are running this wizard for the first time, zk archetype would not have been downloaded into m2eclipse yet, and as a result may not populate the property zk-version-since correctly, leading to an error message as such:
    • Unable to create project from archetype [org.zkoss:zk-archetype-component:0.8.0 -> http://mavensync.zkoss.org/maven2/], Archetype org.zkoss:zk-archetype-component: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. (The same apply to all other properties)

How to run Maven project on Run-Jetty-Run

  1. Go to Run Configurations
    ZKComDevEss Maven CreateComponent run1.png
  2. Double click on Jetty Webapp
    • It will automatically fill-out Project / Port / Context / WebApp Dir
    ZKComDevEss Maven CreateComponent run2.png
  3. Click Run and start browsing local ZK application at http://127.0.0.1:8080/mycomps/

Packing your component

  1. Go to Run As > Maven package (or Maven install )
    ZKComDevEss Maven CreateComponent pak1.png
  2. The project will then be packed into a jar file and a zip file with source code.
    ZKComDevEss Maven CreateComponent 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 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 - 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 then asks for confirmation of the configuration and performs the creation of the project.
  • In the following example, component archetype (number 1) is selected and groupId is set to org.test, artifactId to mycomps, version to 1.0-SNAPSHOT and package to org.test.mycomps.
$ 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: : 1
Downloading: http://mavensync.zkoss.org/maven2//org/zkoss/zk-archetype-component/0.8.0/zk-archetype-component-0.8.0.jar
20K downloaded  (zk-archetype-component-0.8.0.jar)
Downloading: http://mavensync.zkoss.org/maven2//org/zkoss/zk-archetype-component/0.8.0/zk-archetype-component-0.8.0.pom
1K downloaded  (zk-archetype-component-0.8.0.pom)
Define value for property 'groupId': : org.test
Define value for property 'artifactId': : mycomps
Define value for property 'version': 1.0-SNAPSHOT:
Define value for property 'package': org.test: org.test.mycomps
Define value for property 'component-class': : Mylabel
Define value for property 'component-name': : mylabel
[INFO] Using property: zk-version-since = 5.0.6
Confirm properties configuration:
groupId: org.test
artifactId: mycomps
version: 1.0-SNAPSHOT
package: org.test.mycomps
component-class: Mylabel
component-name: mylabel
zk-version-since: 5.0.6
Y:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 34 seconds
[INFO] Finished at: Thu Jul 28 16:27:55 CST 2011
[INFO] Final Memory: 13M/150M
[INFO] ------------------------------------------------------------------------

Import Maven project into Eclipse

  • [File] -> [Import] -> [Maven] --> [Existing Maven Projects]
    ZKComDevEss Maven CreateComponent import1.png
  • After this, the user should now get a new project in the Package explorer.
    ZKComDevEss Maven CreateComponent setp6.png