Get Spreadsheet Running Quickly in JSF"

From Documentation
m (correct highlight (via JWB))
 
(20 intermediate revisions by 4 users not shown)
Line 8: Line 8:
 
{{ZSS EE}}
 
{{ZSS EE}}
  
= Download ZSS JSF Example Project =  
+
= Start with ZSS JSF Example Project =  
If you want to run ZK spreadsheet JSF demo in your local site, just [http:// download the example project WAR file] and deploy to your application server.  
+
If you want to run ZK spreadsheet JSF demo in your local site, just [https://github.com/zkoss/zssjsfdemo download the example maven project] and run it in your environment.
  
 +
== How to Run==
 +
[https://maven.apache.org/download.cgi Install Maven first], then start the project in a jetty server with the command:
 +
  mvn jetty:run
 +
 +
Then, visit http://localhost:8080/zssjsfdemo with a browser
  
 
= Create and Run a JSF Project =
 
= Create and Run a JSF Project =
Line 21: Line 26:
 
* Install [http://www.oracle.com/technetwork/java/javase/downloads/index.html JDK] 1.5 or above
 
* Install [http://www.oracle.com/technetwork/java/javase/downloads/index.html JDK] 1.5 or above
 
* Install an application server
 
* Install an application server
** You can install any JavaEE application server you like. If you don't have one, [http://tomcat.apache.org Tomcat] is a good choice.
+
** You can install any Java web server you like. If you don't have one, [http://tomcat.apache.org Tomcat] is a good choice.
 
* Install a development tool.
 
* Install a development tool.
 
**  In this book, we will use [http://www.eclipse.org/downloads Eclipse]  as the default IDE to explain related setup.
 
**  In this book, we will use [http://www.eclipse.org/downloads Eclipse]  as the default IDE to explain related setup.
Line 27: Line 32:
 
== Prepare a Project ==
 
== Prepare a Project ==
  
To develop a web application in Eclipse, you could use a '''dynamic web project''' or a '''maven project'''. We will describe steps to create these two kind of project respectively.
+
To develop a web application in Eclipse, you can use a '''dynamic web project''' or a '''maven project'''. We will describe steps to create these two kind of project respectively.
  
  
Line 34: Line 39:
 
# Create a dynamic web project
 
# Create a dynamic web project
 
# Install JSF  
 
# Install JSF  
## [http://javaserverfaces.java.net/download.html Download JSF Reference Implementation], and file name might be <tt>javax.faces-2.1.24.jar</tt>.
+
## [http://javaserverfaces.java.net/download.html Download JSF Reference Implementation], and file name might be <code>javax.faces-2.1.24.jar</code>.
## Put the JAR file to '''<tt>/WEB-INF/lib</tt>''' in your web project.
+
## Put the JAR file to '''<code>/WEB-INF/lib</code>''' in your web project.
 
# Install Spreadsheet library
 
# Install Spreadsheet library
 
## Download ZK Spreadsheet component (binary). Choose [http://www.zkoss.org/download/zkspreadsheet "Free Evaluation Downloads" from product page] or licensed  EE from [http://www.zkoss.org/download/premium premium download].
 
## Download ZK Spreadsheet component (binary). Choose [http://www.zkoss.org/download/zkspreadsheet "Free Evaluation Downloads" from product page] or licensed  EE from [http://www.zkoss.org/download/premium premium download].
 
##:  
 
##:  
## Extract the zip and copy those JAR files under '''<tt>/dist/lib</tt>''' and '''<tt>/dist/lib/ext</tt>''' to '''<tt>/WEB-INF/lib</tt>''' of your web project's folder.
+
## Extract the zip and copy those JAR files under '''<code>/dist/lib</code>''' and '''<code>/dist/lib/ext</code>''' to '''<code>/WEB-INF/lib</code>''' of your web project's folder.
##: Make sure '''zssjsf.jar''' existed in <tt>/WEB-INF/lib</tt>.
+
##: Make sure '''zssjsf.jar''' existed in <code>/WEB-INF/lib</code>.
# Set up web.xml
+
# Set up web.xml (in '''<code>/WEB-INF</code>''')
## Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]] and  [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml_for_Servlet_2.3| Sample of web.xml for Servlet 2.3]] ''(For some web container which support Servlet 2.3 only (e.g. Tomcat 4.x)'' to setup web.xml for ZK.
+
## Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
 
## Add servlet mapping for JSF:
 
## Add servlet mapping for JSF:
 
<source lang='xml'>
 
<source lang='xml'>
Line 75: Line 80:
 
:1. Create a Maven project.
 
:1. Create a Maven project.
 
:: You should set packaging to '''war'''.
 
:: You should set packaging to '''war'''.
:: We recommend you to [[ZK_Installation_Guide/Quick_Start/Create_and_Run_Your_First_ZK_Application_with_Eclipse_and_Maven#Create_a_.22Hello_World.22_application_with_ZK_Maven_Archetype| create a project from an archetype]], then you can skip step 3.
 
  
 
:2. Setup Maven dependency.
 
:2. Setup Maven dependency.
::First, you should [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving ZK Framework Artifacts via Maven#Add_to_your_Maven_projects | setup zk maven repository]]. Notice that different edition has a different repository, and licensed products even require authentication.
+
::First, you should [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving ZK Framework Artifacts via Maven#Add_to_your_Maven_projects | setup zk maven repository]] to use "EE Evaluation" or "EE". Notice that different editions are available at different repositories, and EE [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving_ZK_Framework_Artifacts_via_Maven#Login_authentication| requires authentication]].
  
 
::Because this feature is only available in EE, you should add following dependencies:
 
::Because this feature is only available in EE, you should add following dependencies:
Line 87: Line 91:
 
<artifactId>jsf-api</artifactId>
 
<artifactId>jsf-api</artifactId>
 
<version>${jsf-api.version}</version>
 
<version>${jsf-api.version}</version>
<scope>compile</scope>
 
 
</dependency>  
 
</dependency>  
 
<dependency>
 
<dependency>
Line 93: Line 96:
 
<artifactId>jsf-impl</artifactId>
 
<artifactId>jsf-impl</artifactId>
 
<version>${jsf-api.version}</version>
 
<version>${jsf-api.version}</version>
<scope>compile</scope>
 
 
</dependency>
 
</dependency>
  
 
<!-- ZK -->
 
<!-- ZK -->
<dependency>
 
<groupId>org.zkoss.zk</groupId>
 
<artifactId>zkmax</artifactId>
 
<version>${zk.version}</version>
 
</dependency>
 
 
<dependency>
 
<dependency>
 
<groupId>org.zkoss.zss</groupId>
 
<groupId>org.zkoss.zss</groupId>
Line 114: Line 111:
  
 
</source>
 
</source>
 
+
* You can browser ZK maven repository to know available ZSS version.
* If <tt>${zss.version}</tt> is 3.0.0 or above, <tt>${zk.version}</tt> should be 6.5.2.
 
  
 
::You can reference the pom.xml in our example project to verify your own pom.xml.
 
::You can reference the pom.xml in our example project to verify your own pom.xml.
  
 
:3. Set up web.xml
 
:3. Set up web.xml
:: 1. Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]] and  [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml_for_Servlet_2.3| Sample of web.xml for Servlet 2.3]] ''(For some web container which support Servlet 2.3 only (e.g. Tomcat 4.x)'' to setup web.xml for ZK.
+
:: 1. Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
 
::2. Add servlet mapping for JSF:
 
::2. Add servlet mapping for JSF:
 
<source lang='xml'>
 
<source lang='xml'>
Line 148: Line 144:
 
</servlet-mapping>
 
</servlet-mapping>
 
</source>
 
</source>
 +
 +
=== Trouble Shooting ===
 +
If you have problem switching from the evaluation repository to the licensed one, please check [http://books.zkoss.org/wiki/ZK_Installation_Guide/Setting_up_IDE/Maven/Resolving_ZK_Framework_Artifacts_via_Maven#Trouble_Shooting here].
  
 
== Verify Your Project ==  
 
== Verify Your Project ==  
After completing above steps, preparation for working with Spreadsheet and JSP is done. You can use a simple page to verify your preparation. Steps are as follows:
+
After completing the above steps, preparation for working with Spreadsheet and JSP is done. You can use a simple page to verify your preparation. Steps are as follows:
 
# Create a simple Excel file or use the sample file in our example project. Put the file under your web application's root folder.
 
# Create a simple Excel file or use the sample file in our example project. Put the file under your web application's root folder.
# Create <tt>index.xhtml</tt> with content below:
+
# Create <code>index.xhtml</code> with content below:
<source lang='xml' high='5, 10, 15'>
+
<source lang='xml' highlight='5, 10, 15'>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"  
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"  
Line 181: Line 180:
 
* Line 5: Declare a tag name space for Spreadsheet JSF component.
 
* Line 5: Declare a tag name space for Spreadsheet JSF component.
 
* Line 10: The head tag generates ZK required JS and CSS.
 
* Line 10: The head tag generates ZK required JS and CSS.
* Line 13: Use Spreadsheet JSF tag with prefix you specified previously.
+
* Line 15: Use Spreadsheet JSF tag with prefix you specified previously.
 +
 
 +
Now, deploy the project to your application server and visit <code>index.xhtml</code> to see if you can see the Spreadsheet.
 +
 
 +
 
 +
 
  
Now, deploy the project to your application server and visit <tt>index.xhtml</tt> to see if you can see the Spreadsheet.
+
{{ZKSpreadsheetEssentialsPageFooter}}

Latest revision as of 12:47, 19 January 2022


Get Spreadsheet Running Quickly in JSF





Available in ZK Spreadsheet EE only

Start with ZSS JSF Example Project

If you want to run ZK spreadsheet JSF demo in your local site, just download the example maven project and run it in your environment.

How to Run

Install Maven first, then start the project in a jetty server with the command:

 mvn jetty:run

Then, visit http://localhost:8080/zssjsfdemo with a browser

Create and Run a JSF Project

The following sections tell you how to prepare an environment for working with Spreadsheet in JSF.

Prerequisites

Before developing a web application with Spreadsheet, you should prepare the following softwares:

  • Install JDK 1.5 or above
  • Install an application server
    • You can install any Java web server you like. If you don't have one, Tomcat is a good choice.
  • Install a development tool.
    • In this book, we will use Eclipse as the default IDE to explain related setup.

Prepare a Project

To develop a web application in Eclipse, you can use a dynamic web project or a maven project. We will describe steps to create these two kind of project respectively.


Steps to Prepare an Eclipse Dynamic Web Project

  1. Create a dynamic web project
  2. Install JSF
    1. Download JSF Reference Implementation, and file name might be javax.faces-2.1.24.jar.
    2. Put the JAR file to /WEB-INF/lib in your web project.
  3. Install Spreadsheet library
    1. Download ZK Spreadsheet component (binary). Choose "Free Evaluation Downloads" from product page or licensed EE from premium download.
    2. Extract the zip and copy those JAR files under /dist/lib and /dist/lib/ext to /WEB-INF/lib of your web project's folder.
      Make sure zssjsf.jar existed in /WEB-INF/lib.
  4. Set up web.xml (in /WEB-INF)
    1. Please refer to Sample of web.xml.
    2. Add servlet mapping for JSF:
<!-- JSF mapping -->
	<servlet>
		<servlet-name>Faces Servlet</servlet-name>
		<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
		<load-on-startup>1</load-on-startup>
	</servlet>
 
	<!-- Map these files with JSF -->
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>/faces/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.jsf</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.faces</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.xhtml</url-pattern>
	</servlet-mapping>

Steps to Prepare a Maven Project

1. Create a Maven project.
You should set packaging to war.
2. Setup Maven dependency.
First, you should setup zk maven repository to use "EE Evaluation" or "EE". Notice that different editions are available at different repositories, and EE requires authentication.
Because this feature is only available in EE, you should add following dependencies:
		<!-- JSF -->
		<dependency>
			<groupId>com.sun.faces</groupId>
			<artifactId>jsf-api</artifactId>
			<version>${jsf-api.version}</version>
		</dependency> 
		<dependency>
			<groupId>com.sun.faces</groupId>
			<artifactId>jsf-impl</artifactId>
			<version>${jsf-api.version}</version>
		</dependency>

		<!-- ZK -->
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zssex</artifactId>
			<version>${zss.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zssjsf</artifactId>
			<version>${zss.version}</version>
		</dependency>
  • You can browser ZK maven repository to know available ZSS version.
You can reference the pom.xml in our example project to verify your own pom.xml.
3. Set up web.xml
1. Please refer to Sample of web.xml.
2. Add servlet mapping for JSF:
<!-- JSF mapping -->
	<servlet>
		<servlet-name>Faces Servlet</servlet-name>
		<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
		<load-on-startup>1</load-on-startup>
	</servlet>
 
	<!-- Map these files with JSF -->
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>/faces/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.jsf</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.faces</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.xhtml</url-pattern>
	</servlet-mapping>

Trouble Shooting

If you have problem switching from the evaluation repository to the licensed one, please check here.

Verify Your Project

After completing the above steps, preparation for working with Spreadsheet and JSP is done. You can use a simple page to verify your preparation. Steps are as follows:

  1. Create a simple Excel file or use the sample file in our example project. Put the file under your web application's root folder.
  2. Create index.xhtml with content below:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:zssjsf="http://www.zkoss.org/jsf/zss"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html">
<h:head>
	<title>Application for Leave</title>
	<zssjsf:head/>
</h:head>
<h:body>
	<h:form>
		<div>
		<zssjsf:spreadsheet id="myzss" 
			src="/hellozss.xlsx"
			width="1024px" height="768px"  
			maxVisibleRows="50" maxVisibleColumns="20"
			showToolbar="true" showFormulabar="true" showContextMenu="true" showSheetbar="true"/>
		</div>
	</h:form>

</h:body>
</html>
  • Line 5: Declare a tag name space for Spreadsheet JSF component.
  • Line 10: The head tag generates ZK required JS and CSS.
  • Line 15: Use Spreadsheet JSF tag with prefix you specified previously.

Now, deploy the project to your application server and visit index.xhtml to see if you can see the Spreadsheet.



All source code listed in this book is at Github.


Last Update : 2022/01/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.