Get Spreadsheet Up and Running Quickly"

From Documentation
(Created page with "{{ZKSpreadsheetEssentials3PageHeader}} = Overview = This chapter tells you how to run Spreadsheet App and get ready to develop with Spreadsheet. If you are interested in usin...")
 
m (correct highlight (via JWB))
 
(46 intermediate revisions by 4 users not shown)
Line 8: Line 8:
  
 
= Download and Experience =  
 
= Download and Experience =  
If you want to quickly run ZK Spreadsheet at your local site, please download [http:// Spreadsheet App] which is a Excel-like web application. We create it to demonstrate Spreadsheet various powerful features.
+
== 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.
  
 
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.
  
The full introduction of Spreadsheet App's function is covered in [[ZK Spreadsheet Essentials 3/Spreadsheet App | Spreadsheet App]] and the Spreadsheet's features are described in [[ZK Spreadsheet Essentials 3/Features and Usage| Features and Usage]].
+
The full introduction of Spreadsheet App's function is covered in [[ZK Spreadsheet Essentials 3/Using Spreadsheet in ZK/Spreadsheet App| Spreadsheet App]] and the Spreadsheet's features are described in [[ZK Spreadsheet Essentials 3/Features and Usage| Features and Usage]].
  
  
 
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 softwares:
+
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 ==
 +
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.
  
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.
+
== Start from Scratch ==
 +
:1. Create a Maven project.
 +
:: You should set packaging to '''war'''.
  
 +
:2. Setup Maven Repository.
 +
::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]].
  
== Steps to Prepare an Eclipse Dynamic Web Project ==
 
To save your time from creating a project out of nothing, you could just [https://zkbooks.googlecode.com/files/zssessentials.zip download the sample project] which is a ready-to-run Eclipse dynamic web project.
 
  
If you have to create a project by your own, you can follow the steps below:
+
== Repository for Open Source Edition (OSE) ==
# Create a dynamic web project
+
<source lang="xml">
# Install Spreadsheet library
+
<repositories>
## 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].
+
    <repository>
##:
+
      <id>ZK CE</id>
## 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.
+
      <url>http://mavensync.zkoss.org/maven2</url>
# Set up web.xml
+
    </repository>
#: Please refer to [[ZK_Installation_Guide/ZK_Background/Sample_of_web.xml|Sample of web.xml]].
+
  </repositories>
 +
</source>
  
  
== Steps to Prepare a Maven Project ==
+
== Repository for EE Evaluation ==
You can download [http:// download our sample Maven project] to save your time. If you have to create from scratch, please follow the instructions below.
+
<source lang="xml">
 +
<repositories>
 +
    <repository>
 +
      <id>ZK PE/EE Evaluation</id>
 +
      <url>http://mavensync.zkoss.org/eval/</url>
 +
    </repository>
 +
  </repositories>
 +
</source>
 +
 
 +
== 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]].
  
:1. Create a Maven project.
 
:: You should set packaging to '''war'''.
 
  
: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.
 
  
::If you use Open Source Edition (OSE), add the dependency <tt>org.zkoss.zss:zss</tt>:
+
:3. Setup Maven dependency.
 +
==Open Source Edition (OSE) ==
 +
::If you use Open Source Edition (OSE), add the dependency <code>org.zkoss.zss:zss</code>:
  
 
<source lang='xml'>
 
<source lang='xml'>
Line 68: Line 86:
  
 
</source>
 
</source>
* <tt>${zss.version}</tt> can be 3.0.0 or above.
+
* <code>${zss.version}</code> can be 3.0.1 or above.
 +
 
  
::If you use Enterprise Edition (EE), you should add <tt>org.zkoss.zss:zssex</tt>.
+
==Enterprise Edition (Evaluation and premium users ) ==
 +
 
 +
::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 79: Line 100:
 
</dependency>
 
</dependency>
 
</source>
 
</source>
* If <tt>${zss.version}</tt> is 3.0.0 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.
  
: 3. Set up web.xml.  
+
 
 +
: 4. Set up web.xml.  
 
:: 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  ==
 +
Here is a sample of pom.xml for a simple Java web project that uses the ZK Spreadsheet.
 +
<source lang='xml' >
 +
<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>
 +
</source>
 +
 +
 +
=== 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<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].
 +
 +
 +
= 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 94: 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 110: 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>
  
= Adjust Spreadsheet upon Your Requirement =
+
= Working with Spreadsheet =
After playing 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, see the next section, [[ZK Spreadsheet Essentials 3/Working with Spreadsheet/Control Components| Control Components]], for details.
+
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 [[ZK Spreadsheet Essentials 3/Working with Spreadsheet| Working with Spreadsheet]] for details.
  
  

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.