The language addon is a XML file providing the component definitions and other language features.
Location of the language addon depends on how you pack your component definitions: JAR or WAR.
If you pack the component definition(s) in a JAR file, the language addon must be named lang-addon.xml and placed at the /metainfo/zk directory accessible by the classpath.
If you pack the component definition(s) in a WAR file, you can specify the path of the XML file in /WEB-INF/zk.xml. For example, let us assume the path of the XML file is /WEB-INF/zk/lang-addon.xml, then specify the following in /WEB-INF/zk.xml. You can specify multiple language addons.
<language-config>
<addon-uri>/WEB-INF/zk/lang-addon.xml</addon-uri>
</language-config>
Here is a sample of the language addon (ZK FCKeditor).
<language-addon>
<addon-name>fckez</addon-name>
<version>
<version-class>org.zkforge.fckez.Version</version-class>
<version-uid>2.5.1_1</version-uid>
<zk-version>2.4.0</zk-version><!-- or later →
</version>
<language-name>xul/html</language-name>
<javascript-module name="fckez.fckez" version="2.5.1_1"/>
<zscript>
import org.zkforge.fckez.*;
</zscript>
<component>
<component-name>fckeditor</component-name>
<component-class>org.zkforge.fckez.FCKeditor</component-class>
<mold>
<mold-name>default</mold-name>
<mold-uri>~./fckez/fckeditor.dsp</mold-uri>
</mold>
</component>
</language-addon>
The headers of the language addon specifies the name of the addon, the language to addon, and so on.
[Required]
<addon-name>name</addon-name>
Specifies the unique name of the language addon.
[Optional]
<depends>another1, another2</depends>
Specifies a list of the names of other addons, which this addon depends on. If specified, this addon won't be loaded until all depended addons are loaded. If not specified, the loading sequence is unpredictable.
[Required]
<language-name>xul/html</language-name>
Specified the language that this addon shall be added to.
[Optional[16]]
<version>
<version-class>org.zkforge.fckez.Version</version-class>
<version-uid>2.5.1_1</version-uid>
<zk-version>2.4.0</zk-version><!-- or later →
</version>
There are two parts: addon version and ZK version. Addon version is specified in version-uid element. In certain environments, it is possible to have several versions of JAR file containing the same set of component definitions[17]. To ensure the correct XML file is loaded, you have to specify a class carrying the version. The class must have a static data member called UID as shown below.
public class Version {
public static final String UID = "2.5.1_1";
}
Then, ZK will compare UID with the value specified in version-uid, and the addon is ignored if not matched – it means the XML file is not from the same JAR file being loaded.
ZK Version that this addon requires is specified in the zk-version element. The addon is ignored if ZK installed is an older version.
[Optional]
<javascript-module name="fckez.fckez" version="2.5.1_1"/>
Specifies the version of JavaScript codes that will run at the client. If specified, ZK will mangle the URL of JavaScript files with the version, such that the browsers won't use the wrong cached version. It is recommended to change the version each time you deliver a new version of your components (so JavaScript files with the most update version will be loaded by the browser).
There are two kinds components: macro and primitive components. By macro we mean to implement a component based on a ZUML page. By primitive we mean to implement the Component interface (actually extending from AbstractComponent, HtmlBasedComponent and others). This guide focuses on the implementation of primitive components. For implementation of macro components, refer to the Developer's Guide.
<component>
<component-name>fckeditor</component-name>
<component-class>org.zkforge.fckez.FCKeditor</component-class>
<mold>
<mold-name>default</mold-name>
<mold-uri>~./fckez/fckeditor.dsp</mold-uri>
</mold>
</component>
[Required]
Specifies the component name. If an existent component is defined with the same name, the existent component is completely invisible in this page.
[Optional]
<mold>
<mold-name>default</mold-name>
<mold-uri>~./fckez/fckeditor.dsp</mold-uri>
</mold>
Specifies a mold. You can have any number of molds for one component definition.
[Required if mold is specified]
Specified the mold name. The default mold shall be named as default.
[Optional]
<custom-attribute>
<attribute-name>my.attr</attribute-name>
<attribute-value>my value</attribute-value>
</custom-attribute>
Specifies an attribute in the component scope. In other words, the setAttribute method of the Component interface will be called to store the attribute.
[Optional]
<property>
<property-name>border</property-name>
<property-value>blue</property-value>
</property>
Specifies a property to initialize. For example, assume the property name is border, then the setBorder method will be called to set the value specified in property-value.
[Optional]
<annotation>
<annotation-name></annotation-name>
<property-name></property-name>
<attribute>
<attribute-name></attribute-name>
<attribute-value></attribute-value>
</attribute>
<attribute>
<attribute-name></attribute-name>
<attribute-value></attribute-value>
</attribute>
</annotation>
Specifies an annotation to the component definition. It can be accessed by the getAnnotationMap method of the ComponentDefinition interface.
<component>
<component-name>mycomp</component-name>
<component-class>com.mine.Mycomp</component-class>
<macro-uri>~./mine/mycomp.zul</macro-uri>
</component>
The syntax of a macro definition is similar to the definition of the primitive component, except
mold is not allowed
macro-uri is required to specify the template (a ZUML file) used to generate the macro component
[Required][EL is not allowed]
Specifies the URI of the ZUML page, which is used as the template to create the macro component.
<component>
<component-name>funnybutton</component-name>
<extends>button</extends>
</component>
In addition to define a new component, you can extend from the existent one. By extending, it inherits all properties such the as component class, molds and so on. You can override any element you want. The syntax is the same, but they are optional except the component-name and extends element.