Minimize Number of JavaScript Files to Load"

From Documentation
m
m ((via JWB))
(18 intermediate revisions by 5 users not shown)
Line 3: Line 3:
 
= Overview =
 
= Overview =
  
ZK loads the required JavaScript files only when it is required. It is similar to Java Virtual Machine's class loader, but ZK's JavaScript loader loads a JavaScript package at once. It minimizes the number of bytes to be loaded to a browser. However, with an Internet connection, a Web page is loaded faster if the number of files to load is smaller (assuming the total number of bytes to transmit is the same).
+
ZK loads the required JavaScript files only when necessary. It is similar to Java Virtual Machine's class loader, but ZK's JavaScript loader loads a JavaScript package once at a time. It minimizes the number of bytes to be loaded to a browser. However, with an Internet connection, a Web page is loaded faster if the number of files to load is smaller (assuming the total number of bytes to transmit is the same).
  
ZK, by default, loads both <tt>zul</tt> and <tt>zul.wgt</tt> packages when the <tt>zk</tt> package is loaded, since they are most common packages a ZK page might use. A ZK page generally uses more packages than that, and you, as an application developer, can pack them together to minimize the number of JavaScript files.
+
ZK, by default, loads both <code>zul</code> and <code>zul.wgt</code> packages when the <code>zk</code> package is loaded, since they are most common packages a ZK page might use. A ZK page generally uses more packages than that, and you, as an application developer, can pack them together to minimize the number of JavaScript files.
  
Notice that the more packages you packed, the larger the file it is. It will then slow down the load time if some of packages are not required. Thus, only packed the packages that will be required by most of users.
+
Notice that the more packages you packed, the larger the file it is. It will then slow down the load time if some of packages are not required. Thus, you only packed the packages that will be required by most of users.
  
 
= Minimize the Number of JavaScript Files for a ZUL Page =
 
= Minimize the Number of JavaScript Files for a ZUL Page =
 
'''Case Study: ZK Sanbox'''
 
'''Case Study: ZK Sanbox'''
  
In [http://zk1.svn.sourceforge.net/viewvc/zk1/releases/5.0.0/zkdemo/src/archive/userguide/index.zul?revision=13711&view=markup index.zul] of [http://www.zkoss.org/zksandbox/userguide ZK Sanbox] there are about 15 JavaScript files that will be initially loaded:
+
In [http://zk1.svn.sourceforge.net/viewvc/zk1/releases/5.0.7/zksandbox/src/archive/index.zul?view=log index.zul] of [http://www.zkoss.org/zksandbox ZK Sanbox] there are about 15 JavaScript files that will be initially loaded:
  
  * http://www.zkoss.org/zkdemo/zkau/web/947199ea/js/zk.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/947199ea/js/zk.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/947199ea/js/zul.lang.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/947199ea/js/zul.lang.wpd
  * http://www.zkoss.org/zkdemo/userguide/macros/category.js
+
  * http://www.zkoss.org/zksandbox/macros/category.js
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zkmax.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zkmax.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.wgt.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.wgt.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.utl.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.utl.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.layout.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.layout.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.wnd.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.wnd.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.tab.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.tab.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.inp.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.inp.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.box.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.box.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.sel.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.sel.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zk.fmt.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zk.fmt.wpd
  * http://www.zkoss.org/zkdemo/zkau/web/_zv2010062914/js/zul.mesh.wpd
+
  * http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.mesh.wpd
  
This means the browser will trigger 15 requests to load the 15 JavaScript files. Even if each file is not too big, it still takes more time to connect to the server and download it.
+
This means that the browser will trigger 15 requests to load the 15 JavaScript files. Even if each file is not too big, it still takes more time to connect to the server and download it.
However, we can specify a [http://books.zkoss.org/wiki/ZK_Developer%27s_Guide/Beyond_zk/DSP DSP] file to include several JavaScript into one and declare it at the top of the index.zul.
+
However, we can specify a [[ZK Developer's Reference/Supporting Utilities/DSP| DSP]] file to include several JavaScript into one and declare it at the top of the index.zul.
  
 
For example,
 
For example,
'''zkdemo.js.dsp'''
+
'''/macros/zksandbox.js.dsp'''
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
 
<%@ page contentType="text/javascript;charset=UTF-8" %>
 
<%@ page contentType="text/javascript;charset=UTF-8" %>
 
<%@ taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c" %>
 
<%@ taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c" %>
${z:setCacheControl(null, 24)}
+
<%@ taglib uri="http://www.zkoss.org/dsp/zk/core" prefix="z" %>
 +
${z:setCWRCacheControl()}
 
<c:include page="~./js/zk.fmt.wpd"/>
 
<c:include page="~./js/zk.fmt.wpd"/>
 
<c:include page="~./js/zul.mesh.wpd"/>
 
<c:include page="~./js/zul.mesh.wpd"/>
Line 49: Line 50:
 
<c:include page="~./js/zul.box.wpd"/>
 
<c:include page="~./js/zul.box.wpd"/>
 
<c:include page="~./js/zul.sel.wpd"/>
 
<c:include page="~./js/zul.sel.wpd"/>
<c:include page="/userguide/macros/category.js"/>
+
<c:include page="/macros/category.js"/>
</syntax>
+
</syntaxhighlight>
  
 
'''Note:'''
 
'''Note:'''
Line 56: Line 57:
 
#The ''zk.wpd'' is a ZK core JavaScript file hence you don't need to include it
 
#The ''zk.wpd'' is a ZK core JavaScript file hence you don't need to include it
 
#The ''zul.lang.wpd'' is an I18N message, so you don't need to include it.
 
#The ''zul.lang.wpd'' is an I18N message, so you don't need to include it.
#In ZK 5.0.4 we introduced a new feature([[#System-wide_Minimizing_the_Number_of_JavaScript_Files]]).  However, since the release of this new feature the packages '''zul, zul.wgt, and zkmax''' will be merged automatically into the ZK package, so you don't specify them in the  the ''zkdemo.js.dsp'' file.
+
#In ZK 5.0.4 we introduced a new feature([[#System-wide_Minimizing_the_Number_of_JavaScript_Files]]).  However, since the release of this new feature the packages '''zul, zul.wgt, and zkmax''' will be merged automatically into the ZK package, so you don't specify them in the  the ''zksandbox.js.dsp'' file.
 
#<javadoc method="setCacheControl(java.lang.String, int)">org.zkoss.zk.fn.DspFns</javadoc> is used to set the Cache-Control and Expires headers to 24 hours, so the JavaScript file will be cached for a day.
 
#<javadoc method="setCacheControl(java.lang.String, int)">org.zkoss.zk.fn.DspFns</javadoc> is used to set the Cache-Control and Expires headers to 24 hours, so the JavaScript file will be cached for a day.
  
 
'''index.zul'''
 
'''index.zul'''
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
<?script type="text/javascript" src="/userguide/macros/zkdemo.js.dsp"?>
+
<?script type="text/javascript" src="/macros/zksandbox.js.dsp"?>
 
// omitted
 
// omitted
</syntax>
+
</syntaxhighlight>
  
 
= System-wide Minimizing the Number of JavaScript Files =
 
= System-wide Minimizing the Number of JavaScript Files =
  
[since 5.0.4]
+
{{versionSince|5.0.4}}
  
If a package is used by all your pages, you could configure it system wide by specifying the packages in the language addon. Please refer to [[ZK Configuration Reference/zk.xml/The language-config Element]] for how to specify a language addon.
+
If a package is used by all your pages, you could configure it system wide by specifying the packages in the language add-on. Please refer to [[ZK Configuration Reference/zk.xml/The language-config Element]] for how to specify a language add-on.
  
For example, if the zul.wnd package (<javadoc directory="jsdoc">zul.wnd.Window</javadoc>) is required for all pages, then you could add the following to the language addon.
+
For example, if the zul.wnd package (<javadoc directory="jsdoc">zul.wnd.Window</javadoc>) is required for all pages, then you could add the following to the language add-on.
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
 
<javascript package="zul.wnd" merge="true"/>
 
<javascript package="zul.wnd" merge="true"/>
</syntax>
+
</syntaxhighlight>
  
Notice that you have to specify the merge attribute which indicates the JavaScript code of the package will be loaded with the <tt>zk</tt> package. In other words, the <tt>~./js/zk.wpd</tt> will contain all the packages specified with the merge attribute.
+
Notice that you have to specify the merge attribute which indicates that the JavaScript code of the package will be loaded with the <code>zk</code> package. In other words, the <code>~./js/zk.wpd</code> will contain all the packages specified with the merge attribute.
  
 
Also notice that if you use several DSP/JSP file to load multiple packages in a file as described in the previous section, you generally don't specify them here. Otherwise, you will load the same package twice (though it is safe, it wastes time).
 
Also notice that if you use several DSP/JSP file to load multiple packages in a file as described in the previous section, you generally don't specify them here. Otherwise, you will load the same package twice (though it is safe, it wastes time).
Line 85: Line 86:
 
== Turn Off the Merging of JavaScript Packages ==
 
== Turn Off the Merging of JavaScript Packages ==
  
As described above, both <tt>zul</tt> and <tt>zul.wgt</tt> packages are merged into the <tt>zk</tt> package. If you prefer to load them separately, you could disable it by specifying the ondemand attribute as follows.
+
As described above, both <code>zul</code> and <code>zul.wgt</code> packages are merged into the <code>zk</code> package. If you prefer to load them separately, you could disable it by specifying the ondemand attribute as follows.
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
 
<javascript package="zul" ondemand="true"/>
 
<javascript package="zul" ondemand="true"/>
 
<javascript package="zul.wgt" ondemand="true"/>
 
<javascript package="zul.wgt" ondemand="true"/>
</syntax>
+
</syntaxhighlight>
  
Notice that all packages are default to load-on-demand, you rarely need to specify the ondemand attribute, unless you want to undo the package that has been specified with the <tt>merge</tt> attribute.
+
Notice that all packages are default to load-on-demand, you rarely need to specify the ondemand attribute, unless you want to undo the package that has been specified with the <code>merge</code> attribute.
  
 
=Version History=
 
=Version History=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Revision as of 07:36, 8 July 2022


DocumentationZK Developer's ReferencePerformance TipsMinimize Number of JavaScript Files to Load
Minimize Number of JavaScript Files to Load


Overview

ZK loads the required JavaScript files only when necessary. It is similar to Java Virtual Machine's class loader, but ZK's JavaScript loader loads a JavaScript package once at a time. It minimizes the number of bytes to be loaded to a browser. However, with an Internet connection, a Web page is loaded faster if the number of files to load is smaller (assuming the total number of bytes to transmit is the same).

ZK, by default, loads both zul and zul.wgt packages when the zk package is loaded, since they are most common packages a ZK page might use. A ZK page generally uses more packages than that, and you, as an application developer, can pack them together to minimize the number of JavaScript files.

Notice that the more packages you packed, the larger the file it is. It will then slow down the load time if some of packages are not required. Thus, you only packed the packages that will be required by most of users.

Minimize the Number of JavaScript Files for a ZUL Page

Case Study: ZK Sanbox

In index.zul of ZK Sanbox there are about 15 JavaScript files that will be initially loaded:

* http://www.zkoss.org/zksandbox/zkau/web/947199ea/js/zk.wpd
* http://www.zkoss.org/zksandbox/zkau/web/947199ea/js/zul.lang.wpd
* http://www.zkoss.org/zksandbox/macros/category.js
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zkmax.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.wgt.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.utl.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.layout.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.wnd.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.tab.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.inp.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.box.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.sel.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zk.fmt.wpd
* http://www.zkoss.org/zksandbox/zkau/web/_zv2010062914/js/zul.mesh.wpd

This means that the browser will trigger 15 requests to load the 15 JavaScript files. Even if each file is not too big, it still takes more time to connect to the server and download it. However, we can specify a DSP file to include several JavaScript into one and declare it at the top of the index.zul.

For example, /macros/zksandbox.js.dsp

 1 <%@ page contentType="text/javascript;charset=UTF-8" %>
 2 <%@ taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c" %>
 3 <%@ taglib uri="http://www.zkoss.org/dsp/zk/core" prefix="z" %>
 4 ${z:setCWRCacheControl()}
 5 <c:include page="~./js/zk.fmt.wpd"/>
 6 <c:include page="~./js/zul.mesh.wpd"/>
 7 <c:include page="~./js/zul.utl.wpd"/>
 8 <c:include page="~./js/zul.layout.wpd"/>
 9 <c:include page="~./js/zul.wnd.wpd"/>
10 <c:include page="~./js/zul.tab.wpd"/>
11 <c:include page="~./js/zul.inp.wpd"/>
12 <c:include page="~./js/zul.box.wpd"/>
13 <c:include page="~./js/zul.sel.wpd"/>
14 <c:include page="/macros/category.js"/>

Note:

  1. The included JavaScript files have their own sequence, so you cannot place them in randomly.
  2. The zk.wpd is a ZK core JavaScript file hence you don't need to include it
  3. The zul.lang.wpd is an I18N message, so you don't need to include it.
  4. In ZK 5.0.4 we introduced a new feature(#System-wide_Minimizing_the_Number_of_JavaScript_Files). However, since the release of this new feature the packages zul, zul.wgt, and zkmax will be merged automatically into the ZK package, so you don't specify them in the the zksandbox.js.dsp file.
  5. DspFns.setCacheControl(String, int) is used to set the Cache-Control and Expires headers to 24 hours, so the JavaScript file will be cached for a day.

index.zul

1 <?script type="text/javascript" src="/macros/zksandbox.js.dsp"?>
2 // omitted

System-wide Minimizing the Number of JavaScript Files

Since 5.0.4

If a package is used by all your pages, you could configure it system wide by specifying the packages in the language add-on. Please refer to ZK Configuration Reference/zk.xml/The language-config Element for how to specify a language add-on.

For example, if the zul.wnd package (Window) is required for all pages, then you could add the following to the language add-on.

1 <javascript package="zul.wnd" merge="true"/>

Notice that you have to specify the merge attribute which indicates that the JavaScript code of the package will be loaded with the zk package. In other words, the ~./js/zk.wpd will contain all the packages specified with the merge attribute.

Also notice that if you use several DSP/JSP file to load multiple packages in a file as described in the previous section, you generally don't specify them here. Otherwise, you will load the same package twice (though it is safe, it wastes time).

Note: if you merge several JavaScript file into your own lang-addon.xml, but some JavaScript files need to be counted on zul.lang.wpd, such as the package zul.inp, thus, you can't include this package into your lang-addon.xml.(it will be fixed in ZK 5.0.5+)

Turn Off the Merging of JavaScript Packages

As described above, both zul and zul.wgt packages are merged into the zk package. If you prefer to load them separately, you could disable it by specifying the ondemand attribute as follows.

1 <javascript package="zul" ondemand="true"/>
2 <javascript package="zul.wgt" ondemand="true"/>

Notice that all packages are default to load-on-demand, you rarely need to specify the ondemand attribute, unless you want to undo the package that has been specified with the merge attribute.

Version History

Version Date Content
     



Last Update : 2022/07/08

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.