Get Spreadsheet Up and Running Quickly"

From Documentation
(upgrade version)
(Use Different Version of ZK for Premium Users)
Line 118: Line 118:
 
=== Sample of pom.xml for EE Evaluation ===
 
=== Sample of pom.xml for EE Evaluation ===
 
Here is a sample of pom.xml for a simple Java web project that uses the ZK Spreadsheet.
 
Here is a sample of pom.xml for a simple Java web project that uses the ZK Spreadsheet.
<source lang='xml' high='7, 51'>
+
<source lang='xml' high='7, 35, 40, 57'>
 
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
Line 148: Line 148:
 
<dependency>
 
<dependency>
 
<groupId>org.zkoss.zk</groupId>
 
<groupId>org.zkoss.zk</groupId>
<artifactId>zul</artifactId>
+
<artifactId>zkex</artifactId>
 +
<version>${zk.version}</version>
 +
</dependency>
 +
<dependency><!-- to override dependency from zpoi -->
 +
<groupId>org.zkoss.common</groupId>
 +
<artifactId>zcommon</artifactId>
 
<version>${zk.version}</version>
 
<version>${zk.version}</version>
</dependency>
+
</dependency>
<dependency>
+
<dependency><!-- optional, only required when using zssjsf, zssjsp -->
 
<groupId>org.zkoss.zk</groupId>
 
<groupId>org.zkoss.zk</groupId>
<artifactId>zkex</artifactId>
+
<artifactId>zkplus</artifactId>
 
<version>${zk.version}</version>
 
<version>${zk.version}</version>
</dependency>
+
</dependency>
 
<!-- ZSS -->
 
<!-- ZSS -->
 
<dependency>
 
<dependency>
Line 176: Line 181:
 
</project>
 
</project>
 
</source>
 
</source>
* Line 7: ZK Spreadsheet 3.0.1 depends on ZK 6.5.4.
+
* Line 7: ZK Spreadsheet 3.0.1 depends on ZK 6.5.4 by default.
* Line 51: The dependency to zsspdf is optional. You will need it only when you use features related to exporting to PDF.
+
* Line 57: The dependency to <tt>zsspdf</tt> is optional. You will need it only when you use features related to exporting to PDF.
 +
 
 +
==== Use Different Version of ZK for Premium Users ====
 +
For premium users, if you require "IE 11 support" feature, you should override ZK dependency with '''6.5.5'''. If we take above sample pom.xml as an example, just set property <tt>zk.version</tt> to 6.5.5.
  
 
=== Trouble Shooting ===
 
=== Trouble Shooting ===

Revision as of 02:40, 12 February 2014


Get Spreadsheet Up and Running Quickly





Overview

This chapter tells you how to run Spreadsheet App and get ready to develop with Spreadsheet. If you are interested in using spreadsheet in JSP, please refer to Get Spreadsheet Running Quickly in JSP. If you are going to use Spreadhsheet in JSF, please refer to Get Spreadsheet Running Quickly in JSF.

Download and Experience

If you want to quickly run ZK Spreadsheet at your local site, please download Spreadsheet App which is an Excel-like web application. We created it to demonstrate Spreadsheet numerous powerful features.

After you download, please:

  1. Deploy the Spreadsheet App's war file to your application server according to its instruction.
    For Tomcat just put the war file in [CATALINA_HOME]\webapps.
  2. Start your application server and connect it with your browser.
    For Tomcat, just visit http://localhost:8080/zssapp then you can start to experience the power of Spreadsheet.

The full introduction of Spreadsheet App's function is covered in Spreadsheet App and the Spreadsheet's features are described in Features and Usage.


The purpose of following paragraphs is to tell you how to prepare an environment for working with Spreadsheet in API.

Prerequisites

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

  • 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

If you have to create a project by your own, you can follow the steps below:

  1. Create a dynamic web project
  2. Install Spreadsheet library
    1. Download ZK Spreadsheet component (binary). Choose "Open Source Downloads" or "Free Evaluation Downloads" from product page or EE from premium download.
    2. Extract the zip and copy those JAR files under /dist/lib and /dist/lib/ext to /WEB-INF/lib under your web project's root folder.
  3. Set up web.xml
    Please refer to Sample of web.xml.

Steps to Prepare a Maven Project

You can download sample Maven project mentioned in previous page to save your time. If you have to create from scratch, please follow the instructions below.

1. Create a Maven project.
You should set packaging to war.
2. Setup Maven Repository.
First, you should setup zk maven repository according to what Spreadsheet edition you use, and EE requires authentication.

Repository for Open Source Edition (OSE)

 <repositories>
    <repository>
      <id>ZK CE</id>
      <url>http://mavensync.zkoss.org/maven2</url>
    </repository>
  </repositories>


Repository for EE Evaluation

 <repositories>
    <repository>
      <id>ZK PE/EE Evaluation</id>
      <url>http://mavensync.zkoss.org/eval/</url>
    </repository>
  </repositories>

Repository for EE Premium Users Only

Please refer to setup Maven repository for premium users.


3. Setup Maven dependency.

Open Source Edition (OSE)

If you use Open Source Edition (OSE), add the dependency org.zkoss.zss:zss:
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zss</artifactId>
			<version>${zss.version}</version>
		</dependency>
  • ${zss.version} can be 3.0.1 or above.


Enterprise Edition (Evaluation and premium users )

If you use Enterprise Edition (EE Evaluation or EE for premium users), you should add org.zkoss.zss:zssex.
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zssex</artifactId>
			<version>${zss.version}</version>
		</dependency>
  • If ${zss.version} is 3.0.1 or above.

You can reference the pom.xml in our example project to verify your own pom.xml.


4. Set up web.xml.
Please refer to Sample of web.xml.

Sample of pom.xml for EE Evaluation

Here is a sample of pom.xml for a simple Java web project that uses the ZK Spreadsheet.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>sample</groupId>
	<artifactId>myapp</artifactId>
	<properties>
		<zk.version>6.5.4</zk.version>
		<zss.version>3.0.1</zss.version>
		<servlet.version>2.4</servlet.version>
	</properties>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>war</packaging>
	<name>My App</name>
	<repositories>
		<repository>
			<id>ZK Evaluation Repository</id>
			<url>http://mavensync.zkoss.org/eval/</url>
		</repository>
	</repositories>
	<dependencies>
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>servlet-api</artifactId>
			<version>${servlet.version}</version>
			<scope>provided</scope>
		</dependency>
		<!-- ZK -->
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkex</artifactId>
			<version>${zk.version}</version>
		</dependency>				
		<dependency><!-- to override dependency from zpoi -->
			<groupId>org.zkoss.common</groupId>
			<artifactId>zcommon</artifactId>
			<version>${zk.version}</version>
		</dependency>		
		<dependency><!-- optional, only required when using zssjsf, zssjsp -->
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkplus</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<!-- ZSS -->
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zss</artifactId>
			<version>${zss.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zssex</artifactId>
			<version>${zss.version}</version>
		</dependency>
		<!-- Export to PDF -->
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zsspdf</artifactId>
			<version>${zss.version}</version>
		</dependency>
 	</dependencies>
</project>
  • Line 7: ZK Spreadsheet 3.0.1 depends on ZK 6.5.4 by default.
  • Line 57: The dependency to zsspdf is optional. You will need it only when you use features related to exporting to PDF.

Use Different Version of ZK for Premium Users

For premium users, if you require "IE 11 support" feature, you should override ZK dependency with 6.5.5. If we take above sample pom.xml as an example, just set property zk.version to 6.5.5.

Trouble Shooting

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

Verify Your Project

After completing above steps, preparation for working with Spreadsheet 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 a index.zul file with content below:

index.zul

	<window title="My First ZK Spreadsheet Application" height="100%" width="100%">
		<spreadsheet src="/sample.xlsx"
		 vflex="1" hflex="1" maxVisibleRows="150" maxVisibleColumns="40"
		 showToolbar="true" showSheetbar="true" showFormulabar="true"/>
	</window>
  • Line 2: Specify your file path in src attribute.


3. Deploy and run your project in an application server.
4. Visit the index.zul in a browser.

If you see that Spreadsheet displays your sample Excel file in your browser. Congratulation! Your setup is correct.


Working with Spreadsheet

After using for a while, you might think "Great! But I hope its width can be smaller". Don't worry. Spreadsheet provides various options which can be configured via ZUL to fulfill your requirements, and you can even use its API to implement your own business logic in order to react to events. Please read Working with Spreadsheet for details.



All source code listed in this book is at Github.

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