From Documentation

Jump to: navigation, search








Contents

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.6 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

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>org.zkoss.zss</groupId>
    <artifactId>sample</artifactId>
    <description>A project to demonstrate sample pom.xml.</description>
    <properties>
        <zss.version>3.8.1</zss.version>
        <!--
        <zk.version>6.5.5</zk.version>
        -->
    </properties>
    <version>1.0.0</version>
    <packaging>war</packaging>
    <name>zss maven sample</name>
    <repositories>
		<repository>
			<id>ZK EVAL</id>
      		<name>ZK Evaluation Repository</name>
			<url>http://mavensync.zkoss.org/eval</url>
		</repository>        
    </repositories>
    <dependencies>        
        <!-- Required if using ZK Spreadsheet OSE -->
		<dependency>
			<groupId>org.zkoss.zss</groupId>
			<artifactId>zss</artifactId>
			<version>${zss.version}</version>
		</dependency>
        <!-- Required if using ZK Spreadsheet EE -->
        <dependency>
            <groupId>org.zkoss.zss</groupId>
            <artifactId>zssex</artifactId>
            <version>${zss.version}</version>
        </dependency>
        <!-- [Optional] Using ZK Spreadsheet PDF Exporter -->
        <dependency>
            <groupId>org.zkoss.zss</groupId>
            <artifactId>zsspdf</artifactId>
            <version>${zss.version}</version>
        </dependency>
        <!-- ZK -->
        <!-- Uncomment here to use a different version of ZK dependencies
        <dependency>
            <groupId>org.zkoss.common</groupId>
            <artifactId>zcommon</artifactId>
            <version>${zk.version}</version>
        </dependency>     
        <dependency>
            <groupId>org.zkoss.zk</groupId>
            <artifactId>zkplus</artifactId>
            <version>${zk.version}</version>
        </dependency>
        <dependency>
            <groupId>org.zkoss.zk</groupId>
            <artifactId>zkex</artifactId>
            <version>${zk.version}</version>
        </dependency>
         -->        
    </dependencies>
</project>


Version Dependency and Naming

Different versions of ZK Spreadsheet depends on different ZK version. Here are the suggested versions,

ZK Spreadsheet 3.0.1: ZK 6.5.4 and later
ZK Spreadsheet 3.5: ZK 7.0.2 and later

For customers using 3.0.1, if you require "IE 11 support" feature, you should override ZK dependencies with 6.5.5 because 3.0.1 depends on ZK 6.5.4 by default. If we take above sample pom.xml as an example, just uncomment those ZK dependencies and set property zk.version to 6.5.5.

Also note that starting from version 3.5, evaluation copies are renamed with a post-fix of Eval. For example the version number of ZSS 3.5.0 evaluation copy is now 3.5.0-Eval.

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.