Get Spreadsheet Up and Running Quickly"

From Documentation
(Use Alternative ZK Dependencies)
m (correct highlight (via JWB))
 
(23 intermediate revisions by 3 users not shown)
Line 8: Line 8:
  
 
= Download and Experience =  
 
= Download and Experience =  
 +
== Start with WAR ==
 
If you want to quickly run ZK Spreadsheet at your local site, please download [http://www.zkoss.org/download/zkspreadsheet Spreadsheet App] which is an Excel-like web application. We created it to demonstrate Spreadsheet numerous powerful features.
 
If you want to quickly run ZK Spreadsheet at your local site, please download [http://www.zkoss.org/download/zkspreadsheet Spreadsheet App] which is an Excel-like web application. We created it to demonstrate Spreadsheet numerous powerful features.
  
 
After you download, please:
 
After you download, please:
 
# Deploy the Spreadsheet App's war file to your application server according to its instruction.
 
# Deploy the Spreadsheet App's war file to your application server according to its instruction.
#: For Tomcat just put the war file in <tt>[CATALINA_HOME]\webapps</tt>.   
+
#: For Tomcat just put the war file in <code>[CATALINA_HOME]\webapps</code>.   
 
# Start your application server and connect it with your browser.
 
# 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.
 
#: For Tomcat, just visit http://localhost:8080/zssapp then you can start to experience the power of Spreadsheet.
Line 20: Line 21:
  
 
The purpose of following paragraphs is to tell you how to prepare an environment for working with Spreadsheet in API.
 
The purpose of following paragraphs is to tell you how to prepare an environment for working with Spreadsheet in API.
 +
 +
 +
== Start with Example Project ==
 +
Clone [https://github.com/zkoss/zssessentials the example project] and follow the steps in readme to start it.
  
 
= Prerequisites =
 
= Prerequisites =
  
 
Before developing a web application with Spreadsheet, you should prepare the following software:
 
Before developing a web application with Spreadsheet, you should prepare the following software:
* 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.6 or above
 
* Install an application server
 
* Install an application server
 
** You can install any Java web 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.
Line 30: Line 35:
 
**  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.
  
= Prepare a Project =
+
= Develop with Maven =
 
+
==Example 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.
+
Download [https://github.com/zkoss/zssessentials example Maven project] that contains source code in this book can save your time. You can base on that project to start your owned one.
 
 
 
 
== Steps to Prepare an Eclipse Dynamic Web Project ==
 
 
 
If you have to create a project by your own, you can follow the steps below:
 
# Create a dynamic web project
 
# Install Spreadsheet library
 
## Download ZK Spreadsheet component (binary). Choose "Open Source Downloads" or "Free Evaluation Downloads" from [http://www.zkoss.org/download/zkspreadsheet product page] or 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>''' under your web project's root folder.
 
# Set up web.xml
 
#: Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
 
 
 
== Steps to Prepare a Maven Project ==
 
You can download sample Maven project mentioned in [[ZK_Spreadsheet_Essentials_3/Introduction#Example_Source_Code| previous page]] to save your time. If you have to create from scratch, please follow the instructions below.
 
  
 +
== Start from Scratch ==
 
:1. Create a Maven project.
 
:1. Create a Maven project.
 
:: You should set packaging to '''war'''.
 
:: You should set packaging to '''war'''.
Line 55: Line 46:
 
::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]] according to what Spreadsheet edition you use, and EE [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving_ZK_Framework_Artifacts_via_Maven#Login_authentication| requires 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]] according to what Spreadsheet edition you use, and EE [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving_ZK_Framework_Artifacts_via_Maven#Login_authentication| requires authentication]].
  
=== Repository for Open Source Edition (OSE) ===
+
 
 +
== Repository for Open Source Edition (OSE) ==
 
<source lang="xml">
 
<source lang="xml">
 
  <repositories>
 
  <repositories>
Line 66: Line 58:
  
  
=== Repository for EE Evaluation ===
+
== Repository for EE Evaluation ==
 
<source lang="xml">
 
<source lang="xml">
 
  <repositories>
 
  <repositories>
Line 76: Line 68:
 
</source>
 
</source>
  
=== Repository for EE Premium Users Only ===
+
== Repository for EE Premium Users Only ==
 
Please refer to [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving_ZK_Framework_Artifacts_via_Maven#3._PE_.2F_EE_.28premium_users_only.29|setup Maven repository for premium users]].
 
Please refer to [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Artifacts/Resolving_ZK_Framework_Artifacts_via_Maven#3._PE_.2F_EE_.28premium_users_only.29|setup Maven repository for premium users]].
  
Line 82: Line 74:
  
 
:3. Setup Maven dependency.
 
:3. Setup Maven dependency.
===Open Source Edition (OSE) ===
+
==Open Source Edition (OSE) ==
::If you use Open Source Edition (OSE), add the dependency <tt>org.zkoss.zss:zss</tt>:
+
::If you use Open Source Edition (OSE), add the dependency <code>org.zkoss.zss:zss</code>:
  
 
<source lang='xml'>
 
<source lang='xml'>
Line 94: Line 86:
  
 
</source>
 
</source>
* <tt>${zss.version}</tt> can be 3.0.1 or above.
+
* <code>${zss.version}</code> can be 3.0.1 or above.
  
  
===Enterprise Edition (Evaluation and premium users ) ===
+
==Enterprise Edition (Evaluation and premium users ) ==
  
::If you use Enterprise Edition (EE Evaluation or EE for premium users), you should add <tt>org.zkoss.zss:zssex</tt>.  
+
::If you use Enterprise Edition (EE Evaluation or EE for premium users), you should add <code>org.zkoss.zss:zssex</code>.  
 
<source lang='xml'>
 
<source lang='xml'>
  
Line 108: Line 100:
 
</dependency>
 
</dependency>
 
</source>
 
</source>
* If <tt>${zss.version}</tt> is 3.0.1 or above.
+
* If <code>${zss.version}</code> is 3.0.1 or above.
  
 
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.
Line 116: Line 108:
 
:: Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
 
:: Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
  
=== Sample of pom.xml for EE Evaluation ===
+
== Sample of pom.xml ==
 
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' >
 
<source lang='xml' >
<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"  
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
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>
 
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>org.zkoss.zss</groupId>
 
     <groupId>org.zkoss.zss</groupId>
Line 126: Line 120:
 
     <description>A project to demonstrate sample pom.xml.</description>
 
     <description>A project to demonstrate sample pom.xml.</description>
 
     <properties>
 
     <properties>
         <zss.version>3.0.1</zss.version>
+
         <zss.version>3.9.5-Eval</zss.version>
        <!--
+
         <zk.version>8.0.5-Eval</zk.version>
         <zk.version>6.5.5</zk.version>
 
        -->
 
 
     </properties>
 
     </properties>
     <version>3.0.1</version>
+
     <version>1.0.0</version>
 
     <packaging>war</packaging>
 
     <packaging>war</packaging>
 
     <name>zss maven sample</name>
 
     <name>zss maven sample</name>
Line 142: Line 134:
 
     </repositories>
 
     </repositories>
 
     <dependencies>         
 
     <dependencies>         
         <!-- Using ZK Spreadsheet -->
+
         <!-- Required if using ZK Spreadsheet OSE -->
 
<dependency>
 
<dependency>
 
<groupId>org.zkoss.zss</groupId>
 
<groupId>org.zkoss.zss</groupId>
Line 148: Line 140:
 
<version>${zss.version}</version>
 
<version>${zss.version}</version>
 
</dependency>
 
</dependency>
         <!-- [Optional] Using ZK Spreadsheet EE -->
+
         <!-- Required if using ZK Spreadsheet EE -->
 
         <dependency>
 
         <dependency>
 
             <groupId>org.zkoss.zss</groupId>
 
             <groupId>org.zkoss.zss</groupId>
Line 161: Line 153:
 
         </dependency>
 
         </dependency>
 
         <!-- ZK -->
 
         <!-- ZK -->
        <!-- Uncomment to use alternative ZK dependencies, e.g. 6.5.5
 
 
         <dependency>
 
         <dependency>
 
             <groupId>org.zkoss.common</groupId>
 
             <groupId>org.zkoss.common</groupId>
Line 177: Line 168:
 
             <version>${zk.version}</version>
 
             <version>${zk.version}</version>
 
         </dependency>
 
         </dependency>
        -->       
 
 
     </dependencies>
 
     </dependencies>
 
</project>
 
</project>
Line 183: Line 173:
  
  
==== Use Alternative ZK Dependencies for Premium Users ====
+
=== Version Dependency and Naming ===
For premium users, if you require "IE 11 support" feature, you should override ZK dependencies with '''6.5.5''' because 3.0.1 depends ZK 6.5.4 by default. If we take above sample pom.xml as an example, just uncomment those ZK dependencies and set property <tt>zk.version</tt> to 6.5.5.
+
Different versions of ZK Spreadsheet depends on different ZK version. Here are the suggested versions,
  
=== Trouble Shooting ===
+
ZK Spreadsheet 3.5: ZK 7.0.3<br/>
 +
ZK Spreadsheet 3.9: ZK 8.0.5
 +
 
 +
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 <code>zk.version</code> 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 [http://books.zkoss.org/wiki/ZK_Installation_Guide/Setting_up_IDE/Maven/Resolving_ZK_Framework_Artifacts_via_Maven#Trouble_Shooting here].
 
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].
 +
 +
 +
= Develop with Eclipse Dynamic Web Project =
 +
 +
If you have to create a project by your own, you can follow the steps below:
 +
# Create a dynamic web project
 +
# Install Spreadsheet library
 +
## Download ZK Spreadsheet component (binary). Choose "Open Source Downloads" or "Free Evaluation Downloads" from [http://www.zkoss.org/download/zkspreadsheet product page] or EE from [http://www.zkoss.org/download/premium premium download].
 +
##:
 +
## 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>''' under your web project's root folder.
 +
# Set up web.xml
 +
#: Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
  
 
= Verify Your Project=
 
= Verify Your Project=
Line 197: Line 206:
  
 
'''index.zul'''
 
'''index.zul'''
<source lang='xml' high='2'>
+
<source lang='xml' highlight='2'>
<window title="My First ZK Spreadsheet Application" height="100%" width="100%">
+
<spreadsheet src="/sample.xlsx"
<spreadsheet src="/sample.xlsx"
+
height="100%" width="100%" maxVisibleRows="150" maxVisibleColumns="40"
vflex="1" hflex="1" maxVisibleRows="150" maxVisibleColumns="40"
+
showToolbar="true" showSheetbar="true" showFormulabar="true"/>
showToolbar="true" showSheetbar="true" showFormulabar="true"/>
+
 
</window>
 
 
</source>
 
</source>
* Line 2: Specify your file path in <tt>src</tt> attribute.
+
* Line 2: Specify your file path in <code>src</code> attribute.
  
  
Line 213: Line 221:
 
If you see that Spreadsheet displays your sample Excel file in your browser. Congratulation! Your setup is correct.
 
If you see that Spreadsheet displays your sample Excel file in your browser. Congratulation! Your setup is correct.
  
 +
= Work with ZK 8.5 or Later =
 +
Since ZK 8.5.0, the default theme is '''iceblue''' which is not supported by Spreadsheet. You have to manually switch to one of the classic themes (breeze, sapphire, silvertail) with the following steps:
  
 +
== 1. Add a classic theme jar ==
 +
In maven pom.xml:
 +
<source lang='xml'>
 +
        <dependency>
 +
            <groupId>org.zkoss.theme</groupId>
 +
            <artifactId>breeze</artifactId>
 +
            <version>${zk.version}</version>
 +
        </dependency>
 +
</source>
 +
 +
== 2. Specify Preferred Theme==
 +
In zk.xml
 +
 +
<source lang='xml'>
 +
<library-property>
 +
<name>org.zkoss.theme.preferred</name>
 +
<value>breeze</value>
 +
</library-property>
 +
</source>
  
 
= Working with Spreadsheet =
 
= Working with Spreadsheet =

Latest revision as of 12:49, 19 January 2022


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

Start with WAR

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.


Start with Example Project

Clone the example project and follow the steps in readme to start it.

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.

Develop with Maven

Example Project

Download example Maven project that contains source code in this book can save your time. You can base on that project to start your owned one.

Start from Scratch

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.9.5-Eval</zss.version>
        <zk.version>8.0.5-Eval</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 -->
        <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.5: ZK 7.0.3
ZK Spreadsheet 3.9: ZK 8.0.5

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.


Develop with 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.

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

<spreadsheet src="/sample.xlsx"
height="100%" width="100%" maxVisibleRows="150" maxVisibleColumns="40"
showToolbar="true" showSheetbar="true" showFormulabar="true"/>
  • 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.

Work with ZK 8.5 or Later

Since ZK 8.5.0, the default theme is iceblue which is not supported by Spreadsheet. You have to manually switch to one of the classic themes (breeze, sapphire, silvertail) with the following steps:

1. Add a classic theme jar

In maven pom.xml:

        <dependency>
            <groupId>org.zkoss.theme</groupId>
            <artifactId>breeze</artifactId>
            <version>${zk.version}</version>
        </dependency>

2. Specify Preferred Theme

In zk.xml

	<library-property>
		<name>org.zkoss.theme.preferred</name>
		<value>breeze</value>
	</library-property>

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.