Getting Started

{{ZKDevelopersGuidePageHeader}}

This chapter describes how to write your first [http://books.zkoss.org/wiki/ZK_ZUML_Reference/The_ZK_User_Interface_Markup_Language '''ZUML''' ](ZK User interface Markup Language) page, and demonstrates some ZK's features in really simple examples.

==Hello World!==
After ZK is installed into your favorite Web server<ref>Refer to the Quick Start Guide.</ref>, writing applications is straightforward. Just create a ZUML file, say hello.zul<ref>The other way to try examples is to use [http://www.zkoss.org/zksandbox/userguide ZK Sandbox] to run them.</ref>, as follows under one of the Web application's directories just like as you do for a HTML file.

<source lang="xml" >
 <window title="My First ZK Application" border="normal">
 	Hello World!
 </window>
</source>


Then, browse to the right URL, say http://localhost/myapp/hello.zul, and you got it.

[[Image:dgGettingStartedHello.zul.png]]

In a ZUML page, a XML element describes what component to create. In this example, it is a <tt>window</tt> . The XML attributes are used to assign values to properties of the window component. In this example, it sets the window's <tt>title</tt> to <tt>"My First ZK Application"</tt> and <tt>border</tt> to <tt>normal</tt>.

The text enclosed in the XML elements is also interpreted as a special component called <tt>label</tt>. Thus, the above example is equivalent to the following.

<source lang="xml" >
 <window title="My First ZK Application" border="normal">
	<label value="Hello World!"/>
</window>
</source>

==Say Hello in Ajax way==

Let us put some interactivity into it.

<source lang="xml" >
 <button label="Say Hello" onClick='Messagebox.show("Hello World!")'/>
</source>

Then, when you click the button, you see as follows.

[[Image:DgGettingStartedHello2.png‎]]

The <tt>onClick</tt> attribute is a special attribute used to add an event listener to the component, such that it is invoked when an end user clicks it. The attribute value could be any legal Java code. Notice that it is not JavaScript, and we have to use the double quotes (") to represent a string. Furthermore, to specify a double quote in a XML attribute, we could use single quotes (') to enclose it<ref>If you are not familiar with XML, you might take a look at [[ZK_Developer%27s_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/XML |the XML section]].</ref>.

Here we invoke <javadoc method="show(java.lang.String)">org.zkoss.zul.Messagebox</javadoc> to show a message box as depicted above.

The Java code is interpreted by [http://www.beanshell.org/ BeanShell] at run time. In additions to event handling, we could embed the code in a ZUML page by specifying it in a special element called <tt>zscript</tt>. For example, we could define a function to simply the code as follows.

<source lang="xml" >
 <window title="My First ZK Application" border="normal">
 	<button label="Say Hello" onClick='alert("Hello World!")'/>
 	<zscript>
 		void alert(String message){ //declare a function
 			Messagebox.show(message);
 		}
 	</zscript>
 </window>
</source>

In fact, <tt>alert</tt> is a built-in function that you can use it directly in the embedded Java code.

==It is Java and runs at the server==
The embedded Java code runs at the server so it could access any resource available at the server. For example,

<source lang="xml" >
<window title="Property Retrieval" border="normal">
    Enter a property name: <textbox/>
    <button label="Retrieve" onClick="alert(System.getProperty(self.getPreviousSibling().getValue()))"/>
</window>
</source>

where <tt>self</tt> is a built-in variable that references to the component receiving the event. If we entered <tt>java.version</tt> and clicks the button, the result is as follows.

[[Image:DgGettingStartedProperty.png‎]]

==Access Component by ID==
After you assign the <tt>id</tt> attribute of a component, then you can easily access it by <tt>id</tt> . Like the following code, you can change the <tt>label</tt> of a  <tt>button</tt> by writing <tt>zscript</tt> .

<source lang="xml" >
 <window title="ZK app 4">	
 	<button id="btn" label="Before" onClick="change()"/>
 	<zscript>
 		void change(){ 		
 			btn.label="After";
 		}
 	</zscript>
 </window>
</source>

[[Image:getting_started_app_4.JPG]]

In this example, we set the id of the button as 「btn」, then you can treat it as a declared global instance.

==Assign component's attribute value without hard coding==
Like JSP(JavaServer Pages), you could use EL expressions in ZUML pages. EL expressions use the syntax <tt>${expr}</tt>. In the following sample, we set the label value of  <tt>btn_2</tt> to the label value of <tt>btn_1</tt> .

<source lang="xml" >
 <window title="ZK app 5">	
 	<button id="btn_1" label="Say Hello"/>
 	<button id="btn_2" label="${btn_1.label}"/>
 </window>
</source>

[[Image:getting_started_app_5.JPG]]

Chapter. ZK User interface Markup Language will provide more details on EL expressions. The Developer's Reference and JSP 2.0 tutorials or guides are also good references if you want to know even more.

==Design pattern: MVC==
If you prefer the [http://en.wikipedia.org/wiki/Model-view-controller MVC](Model-View-Controller) approadch, i.e. you prefer not to embed the handling codes in the <tt>window</tt> (the view), you can implement a class to handle events. In the example below, <tt>onClick</tt> event of the button is forwarded to <tt>window</tt> , and handled by applied class <tt>MyComposer</tt> .

<source lang="xml" >
 <window id="win" title="ZK app 6" apply="MyComposer">
 	<button label="Say Hello" forward="onSayHello" />
 </window>
</source>


<source lang="java" >
 //MyComposer.java
 import org.zkoss.zk.ui.event.Event;
 import org.zkoss.zk.ui.util.GenericComposer;
 import org.zkoss.zul.Label;
 
 public class MyComposer extends GenericComposer {
 	public void onSayHello(Event evt) {
 		evt.getTarget().appendChild(new Label("Hello")); 
 	}
 }
</source>

[[Image:getting_started_app_6.JPG]]

For more information, please refer to our smalltalk.

==Other Feature==
ZK has many other features to help you develop your web application easily. Like Data-Binding, Live Data. Please visit our live demo and play around. You'll find the beauty of simple.

'''Notes'''

<references/>

== Quiz ==
#What event is triggered when a <tt>button</tt> is clicked? Hint: onXXX?
#What element should be used if you want to write java code in your ZUML?
#What's the benefit to assign id to a component?
#<tt>${expr}</tt> is the syntax of?
#What design pattern is mentioned here?


{{ZKDevelopersGuidePageFooter}}