Locale-Dependent Resources"

From Documentation
 
(26 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{ZKDevelopersGuidePageHeader}}
+
{{ZKDevelopersReferencePageHeader}}
  
=== Browser and Locale-Dependent URI ===
+
= Overview =
Many resources depend on the Locale and, sometimes, the browser that a user is used to visit the Web page. For example, you need to use a larger font for Chinese characters to have better readability.
+
Many resources depend on the Locale and, sometimes, the browser. For example, you might need to use a larger font for Chinese characters to have better readability. ZK provides a way to load locale and browser-dependent resources including JavaScript, CSS, and images.
  
ZK can handle this for you automatically, if you specify the URL of the style sheet with "*". The algorithm is as follows.
+
=Specifying Locale and Browser-Dependent URL=
  
# If there is one "*" is specified in an URI such as <tt>/my*.css</tt>, then "*" will be replaced with a proper Locale depending on the preferences of user's browser.For example, user's preferences is <tt>de_DE</tt>, then ZK searches <tt>/my_de_DE.css</tt>, <tt>/my_de.css</tt>, and <tt>/my.css</tt> one-by-one from your Web site, until any of them is found. If none of them is found, <tt>/my.css </tt>is still used.
+
ZK can handle this for you automatically by specifying a URL with '''asterisk''' <code>*</code>. This feature is supported by all components that accept a URL, e.g. the src of [[ZK%20Component%20Reference/Essential%20Components/Script| &lt;script>]] or [[ZUML%20Reference/ZUML/Processing%20Instructions/script| &lt;?script?>]]. The algorithm is as follows.
# If two or more "*" are specified in an URI such as "/my*/lang*.css", then the first "*" will be replaced with "<tt>ie</tt>" for Internet Explorer, "saf" for Safari, and "<tt>moz</tt>" for other browsers<ref>In the future editions, we will use different codes for browsers other than Internet Explorer, Firefox and Safari.</ref>. Moreover, the last asterisk will be replaced with a proper Locale as described in the above step.In summary, the last asterisk represents the Locale, while the first asterisk represents the browser type.  
+
==Absolute or Relative Path==
# All other "*" are ignored.
+
You can only specify an absolute path to load a locale-dependent resource at 9.x and before.  
 +
{{versionSince | 10.0.0}}
 +
Relative path is supported.
  
'''Note''': The lat asterisk that represents the Locale must be placed right before the first dot ("."), or at the end if no dot at all. Furthermore, no following slash (/) is allowed, i.e., it must be part of the filename, rather than a directory. If the last asterisk doesn't fulfill this constraint, it will be eliminated (not ignored).
+
== One "*" for Locale Code ==
 +
If you specify only one <code>*</code> in a URL, such as <code>/my*.css</code>, then <code>*</code> will be replaced with a '''locale code''' depending on the current locale that ZK detects. For example:
 +
 
 +
* URI: '''<code>/my*.css</code>'''
 +
* User's preferences (current locale): '''<code>de_DE</code>'''
 +
 
 +
Then ZK looks for files in the order below one-by-one in your website until any of them is found:
 +
 
 +
# <code>/my_de_DE.css</code>
 +
# <code>/my_de.css</code>
 +
# <code>/my.css</code>
 +
 
 +
 
 +
== Two "*" for Locale and Browser Code ==
 +
Such as "/my*/lang*.css", then the first "*" will be replaced with a '''browser code''' as follows:
 +
* <code>ie</code> for Internet Explorer
 +
* <code>saf</code> for Chrome, Safari
 +
* <code>moz</code> for Firefox and other browsers<ref>In the future editions, we will use different codes for browsers other than Internet Explorer, Firefox and Safari.</ref>.
 +
 
 +
Moreover, the last asterisk will be replaced with a proper Locale as described in the previous rule. In summary, the last asterisk represents the Locale, while the first asterisk represents the browser type.
 +
 
 +
For example:
 +
 
 +
'''zul'''
 +
<source lang='xml'>
 +
<style src="/i18n/css-*/mycss*.css" />
 +
</source>
 +
 
 +
 
 +
The result in an HTML with Chrome:
 +
<source lang='html'>
 +
<link ... href="/i18n/css-saf/mycss.css" ...>
 +
</source>
 +
 
 +
== All other "*" are ignored ==
 +
 
 +
 
 +
== Note ==
 +
The last asterisk that represents the Locale must be placed right before the first dot ("."), or at the end if no dot at all. Furthermore, no following slash (/) is allowed, i.e., it must be part of the filename, rather than a directory. If the last asterisk doesn't fulfill this constraint, it will be eliminated (not ignored).
  
 
For example, "/my/lang.css*" is equivalent to "/my/lang.css".
 
For example, "/my/lang.css*" is equivalent to "/my/lang.css".
Line 16: Line 56:
 
In other words, you can consider it as neutral to the Locale.
 
In other words, you can consider it as neutral to the Locale.
  
'''Tip''': We can apply this rule to specify an URI depending on the browser type, but not depending on the Locale. For example, "/my/lang*.css*" will be replaced with "/my/langie.css" if Internet Explorer is the current user's browser.
+
'''Tip''': We can apply this rule to specify a URI depending on the browser type, but not depending on the Locale. For example, "/my/lang*.css*" will be replaced with "/my/langie.css" if Internet Explorer is the current user's browser.
  
'''Notes'''
+
<blockquote>
 +
----
 
<references/>
 
<references/>
 +
</blockquote>
  
 
+
==Example==
In the following examples, we assume the preferred Locale is <tt>de_DE</tt> and the browser is Internet Explorer.
+
In the following example, we assume the preferred Locale is <code>de_DE</code> and the browser is Internet Explorer.
  
  
{| border="1px"
+
{| class='wikitable' | width="100%"
 
! <center>URI</center>
 
! <center>URI</center>
 
! <center>Resources that are searched</center>
 
! <center>Resources that are searched</center>
Line 31: Line 73:
 
|-
 
|-
 
| /css/norm*.css
 
| /css/norm*.css
| # /norm_de_DE.css
+
|  
 +
# /norm_de_DE.css
 
# /norm_de.css
 
# /norm_de.css
 
# /norm.css
 
# /norm.css
Line 39: Line 82:
 
|-
 
|-
 
| /css-*/norm*.css
 
| /css-*/norm*.css
| # /css-ie/norm_de_DE.css
+
|  
 +
# /css-ie/norm_de_DE.css
 
# /css-ie/norm_de.css
 
# /css-ie/norm_de.css
 
# /css-ie/norm.css
 
# /css-ie/norm.css
Line 47: Line 91:
 
|-
 
|-
 
| /img*/pic*/lang*.png
 
| /img*/pic*/lang*.png
| # /imgie/pic*/lang_de_DE.png
+
|  
 +
# /imgie/pic*/lang_de_DE.png
 
# /imgie/pic*/lang_de.png
 
# /imgie/pic*/lang_de.png
 
# /imgie/pic*/lang.png
 
# /imgie/pic*/lang.png
Line 55: Line 100:
 
|-
 
|-
 
| /img*/lang.gif
 
| /img*/lang.gif
| # /img/lang.gif
+
|  
 +
# /img/lang.gif
  
  
Line 61: Line 107:
 
|-
 
|-
 
| /img/lang*.gif*
 
| /img/lang*.gif*
| # /img/langie.gif
+
|  
 +
# /img/langie.gif
  
  
Line 67: Line 114:
 
|-
 
|-
 
| /img*/lang*.gif*
 
| /img*/lang*.gif*
| # /imgie/lang*.gif
+
|  
 +
# /imgie/lang*.gif
  
  
  
 
|}
 
|}
=== Locating Browser and Locale Dependent Resources in Java ===
 
In additions to component attributes and ZUML attributes, you could handle browser and Locale dependent resource programmingly in Java. Here are a list of methods that you could use.
 
  
* The <tt>encodeURL</tt>, <tt>forward</tt>, and <tt>include</tt> methods in <javadoc>org.zkoss.zk.ui.Execution</javadoc> for encoding URL, forwarding to another page and including a page. In most cases, these methods are all you need.
+
= Locating Locale- and browser-dependent resources in Java =
* The <tt>locate</tt>, <tt>forward</tt>, and <tt>include</tt> method in <javadoc>org.zkoss.web.servlet.Servlets</javadoc> for locating Web resouces. You rarely need them when developing ZK applications, but useful for writing a servlet, portlet or filter.
+
 
* The <tt>encodeURL</tt> method in <javadoc>org.zkoss.web.servlet.http.Encodes</javadoc> for encoding URL. You rarely need them when developing ZK applications, but useful for writing a servlet, portlet or filter.
+
In addition to ZUML, you can also load browser- and Locale-dependent resources in Java. Here is a list of methods that you can use.
 +
 
 +
* The <code>encodeURL</code>, <code>forward</code>, and <code>include</code> methods in <javadoc>org.zkoss.zk.ui.Execution</javadoc> for encoding URL, forwarding to another page and including a page. In most cases, these methods are all you need.
 +
* The <code>locate</code>, <code>forward</code>, and <code>include</code> method in <javadoc>org.zkoss.web.servlet.Servlets</javadoc> for locating Web resouces. You rarely need them when developing ZK applications, but useful for writing a servlet, portlet or filter.
 +
* The <code>encodeURL</code> method in <javadoc>org.zkoss.web.servlet.http.Encodes</javadoc> for encoding URL. You rarely need them when developing ZK applications, but useful for writing a Servlet, Portlet or Filter.
 +
 
 +
* The <code>locate</code> method in <javadoc>org.zkoss.util.resource.Locators</javadoc> for locating class resources.
  
* The <tt>locate</tt> method in <javadoc>org.zkoss.util.resource.Locators</javadoc> for locating class resources.
 
  
  
{{ ZKDevelopersGuidePageFooter}}
+
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 01:44, 25 April 2024


Locale-Dependent Resources


Overview

Many resources depend on the Locale and, sometimes, the browser. For example, you might need to use a larger font for Chinese characters to have better readability. ZK provides a way to load locale and browser-dependent resources including JavaScript, CSS, and images.

Specifying Locale and Browser-Dependent URL

ZK can handle this for you automatically by specifying a URL with asterisk *. This feature is supported by all components that accept a URL, e.g. the src of <script> or <?script?>. The algorithm is as follows.

Absolute or Relative Path

You can only specify an absolute path to load a locale-dependent resource at 9.x and before. Since 10.0.0 Relative path is supported.

One "*" for Locale Code

If you specify only one * in a URL, such as /my*.css, then * will be replaced with a locale code depending on the current locale that ZK detects. For example:

  • URI: /my*.css
  • User's preferences (current locale): de_DE

Then ZK looks for files in the order below one-by-one in your website until any of them is found:

  1. /my_de_DE.css
  2. /my_de.css
  3. /my.css


Two "*" for Locale and Browser Code

Such as "/my*/lang*.css", then the first "*" will be replaced with a browser code as follows:

  • ie for Internet Explorer
  • saf for Chrome, Safari
  • moz for Firefox and other browsers[1].

Moreover, the last asterisk will be replaced with a proper Locale as described in the previous rule. In summary, the last asterisk represents the Locale, while the first asterisk represents the browser type.

For example:

zul

<style src="/i18n/css-*/mycss*.css" />


The result in an HTML with Chrome:

<link ... href="/i18n/css-saf/mycss.css" ...>

All other "*" are ignored

Note

The last asterisk that represents the Locale must be placed right before the first dot ("."), or at the end if no dot at all. Furthermore, no following slash (/) is allowed, i.e., it must be part of the filename, rather than a directory. If the last asterisk doesn't fulfill this constraint, it will be eliminated (not ignored).

For example, "/my/lang.css*" is equivalent to "/my/lang.css".

In other words, you can consider it as neutral to the Locale.

Tip: We can apply this rule to specify a URI depending on the browser type, but not depending on the Locale. For example, "/my/lang*.css*" will be replaced with "/my/langie.css" if Internet Explorer is the current user's browser.


  1. In the future editions, we will use different codes for browsers other than Internet Explorer, Firefox and Safari.

Example

In the following example, we assume the preferred Locale is de_DE and the browser is Internet Explorer.


URI
Resources that are searched
/css/norm*.css
  1. /norm_de_DE.css
  2. /norm_de.css
  3. /norm.css


/css-*/norm*.css
  1. /css-ie/norm_de_DE.css
  2. /css-ie/norm_de.css
  3. /css-ie/norm.css


/img*/pic*/lang*.png
  1. /imgie/pic*/lang_de_DE.png
  2. /imgie/pic*/lang_de.png
  3. /imgie/pic*/lang.png


/img*/lang.gif
  1. /img/lang.gif


/img/lang*.gif*
  1. /img/langie.gif


/img*/lang*.gif*
  1. /imgie/lang*.gif


Locating Locale- and browser-dependent resources in Java

In addition to ZUML, you can also load browser- and Locale-dependent resources in Java. Here is a list of methods that you can use.

  • The encodeURL, forward, and include methods in Execution for encoding URL, forwarding to another page and including a page. In most cases, these methods are all you need.
  • The locate, forward, and include method in Servlets for locating Web resouces. You rarely need them when developing ZK applications, but useful for writing a servlet, portlet or filter.
  • The encodeURL method in Encodes for encoding URL. You rarely need them when developing ZK applications, but useful for writing a Servlet, Portlet or Filter.
  • The locate method in Locators for locating class resources.




Last Update : 2024/04/25

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