The Format of Properties Files"
RebeccaLai (talk | contribs) m |
|||
(9 intermediate revisions by one other user not shown) | |||
Line 3: | Line 3: | ||
__TOC__ | __TOC__ | ||
− | In this section, we will discuss the format of a properties file, such as < | + | In this section, we will discuss the format of a properties file, such as <code>zk-label.properties</code>. |
− | A properties file is a simple text file. The file contains a list of < | + | A properties file is a simple text file. The file contains a list of <code>key=value</code> pairs, such as |
− | < | + | <syntaxhighlight lang='properties'> |
# This is the default LabelsBundle.properties file | # This is the default LabelsBundle.properties file | ||
s1=computer | s1=computer | ||
Line 13: | Line 13: | ||
s3=monitor | s3=monitor | ||
s4=keyboard | s4=keyboard | ||
− | </ | + | </syntaxhighlight> |
The default encoding of a properties file is assumed to be '''UTF-8'''. If you want to use a different encoding, please refer to [[#Use Encoding Other Than UTF-8|the Use Encoding Other Than UTF-8 section]]. | The default encoding of a properties file is assumed to be '''UTF-8'''. If you want to use a different encoding, please refer to [[#Use Encoding Other Than UTF-8|the Use Encoding Other Than UTF-8 section]]. | ||
− | A properties file is usually used to contain the internationalization labels of an application, but technically you could use it in any situation you'd like<ref>If it is used for internationalization labels, it will be loaded automatically. If you want to use it in other | + | A properties file is usually used to contain the internationalization labels of an application, but technically you could use it in any situation you'd like<ref>If it is used for internationalization labels, it will be loaded automatically. If you want to use it in other situations, you have to invoke <javadoc method="load(java.util.Map, java.io.InputStream, boolean)">org.zkoss.util.Maps</javadoc> or similar to load it manually.</ref>. |
<blockquote> | <blockquote> | ||
Line 26: | Line 26: | ||
=Specify a Value with Multiple Lines= | =Specify a Value with Multiple Lines= | ||
− | By default, a property is | + | By default, a property is a text specified right after the equal sign. If the property's value has multiple lines, you could use the following format: |
− | < | + | <syntaxhighlight lang='properties'> |
− | + | multilines={ | |
line 1 | line 1 | ||
line 2 | line 2 | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
+ | |||
+ | Notice that the curly braces must be followed by a line break immediately, and the right brace (<code>}</code>) must be the only character in the line. | ||
+ | |||
+ | Then you should put the value in a multiple-line label: | ||
+ | <syntaxhighlight lang='xml'> | ||
+ | <label multiline="true" value="${labels.multilines}"/> | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | |||
+ | ==Render Multiple Lines == | ||
+ | Alternatively, you can write a value with <code><br></code>: | ||
+ | <syntaxhighlight lang='properties'> | ||
+ | lines=1st line <br> 2nd line | ||
+ | </syntaxhighlight> | ||
− | + | Then render it in an HTML <code>span</code> | |
+ | <syntaxhighlight lang='xml'> | ||
+ | <zk xmlns:h="native"> | ||
+ | <h:span>${labels.lines}</h:span> | ||
+ | </zk> | ||
+ | </syntaxhighlight> | ||
=Specify Segmented Keys= | =Specify Segmented Keys= | ||
− | Since all internationalization labels are stored in the same scope, it is common to separate them by naming the key with | + | Since all internationalization labels are stored in the same scope, it is common to separate them by naming the key with dots ('''.''') like the Java package name. For the sake of description, we call them segmented keys. For example, |
− | < | + | <syntaxhighlight lang='properties'> |
order.fruit.name = Orange | order.fruit.name = Orange | ||
order.fruit.description = A common fruit | order.fruit.description = A common fruit | ||
− | </ | + | </syntaxhighlight> |
It can be simplified by use of the following syntax: | It can be simplified by use of the following syntax: | ||
− | < | + | <syntaxhighlight lang='properties'> |
order.fruit. { | order.fruit. { | ||
name = Orange | name = Orange | ||
description = A common fruit | description = A common fruit | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
As shown, the segmented key could be specified by specifying the prefix and a following right brace ('''{'''). | As shown, the segmented key could be specified by specifying the prefix and a following right brace ('''{'''). | ||
Line 65: | Line 84: | ||
</source> | </source> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | Second, with an EL function called [[ZUML Reference/EL Expressions/Core Methods/l|l] and/or [[ZUML Reference/EL Expressions/Core Methods/l2|l2]]: | + | Second, with an EL function called [[ZUML Reference/EL Expressions/Core Methods/l|l]] and/or [[ZUML Reference/EL Expressions/Core Methods/l2|l2]]: |
<source lang="xml"> | <source lang="xml"> | ||
Line 77: | Line 91: | ||
<label value="${c:l('order.fruit.name')}"> | <label value="${c:l('order.fruit.name')}"> | ||
</source> | </source> | ||
+ | |||
+ | == Under the hood == | ||
+ | The <code>labels</code> object is actually the map returned by <javadoc method="getSegmentedLabels()">org.zkoss.util.resource.Labels</javadoc>. Furthermore, if the key of a property contains dots (<code>.</code>), i.e., segmented, all properties with the same prefix are grouped as another map. For example, <code>${labels.order}</code> (i.e., <code>Labels.getSegmentedLables().get("order")</code>) will return a map containing an entry (<code>fruit</code>) in the above example. | ||
=Specify a Comment = | =Specify a Comment = | ||
Line 82: | Line 99: | ||
You could put a comment line by starting with the sharp sign ('''#'''), such as | You could put a comment line by starting with the sharp sign ('''#'''), such as | ||
− | < | + | <syntaxhighlight lang='properties'> |
#This is a comment line that will be ignored when loaded | #This is a comment line that will be ignored when loaded | ||
− | </ | + | </syntaxhighlight> |
=Use EL Expressions= | =Use EL Expressions= | ||
Line 90: | Line 107: | ||
EL expressions are allowed for a property's value. For example, you could reference a property's value in another property, such as | EL expressions are allowed for a property's value. For example, you could reference a property's value in another property, such as | ||
− | < | + | <syntaxhighlight lang='properties'> |
first=the first label | first=the first label | ||
second=come after ${first} | second=come after ${first} | ||
− | </ | + | </syntaxhighlight> |
− | Segmented keys are also allowed | + | {{versionSince | 5.0.7}}Segmented keys are also allowed: |
− | < | + | <syntaxhighlight lang='properties'> |
group1.first=the first group | group1.first=the first group | ||
group2.second=come after ${group1.first} | group2.second=come after ${group1.first} | ||
− | </ | + | </syntaxhighlight> |
− | In addition to referencing another property, you could reference any implicit object specified in [[ZUML Reference/EL Expressions/Implicit Objects|ZUML Reference: Implicit Objects]] if it is part of | + | In addition to referencing another property, you could reference any implicit object specified in [[ZUML Reference/EL Expressions/Implicit Objects|ZUML Reference: Implicit Objects]] if it is part of an HTTP request (excluding component/page). |
For example, [[ZUML Reference/EL Expressions/Implicit Objects/param|param]] references to a request's parameter: | For example, [[ZUML Reference/EL Expressions/Implicit Objects/param|param]] references to a request's parameter: | ||
− | < | + | <syntaxhighlight lang='properties'> |
message=Thank ${param.user} for using | message=Thank ${param.user} for using | ||
− | </ | + | </syntaxhighlight> |
<blockquote> | <blockquote> | ||
Line 116: | Line 133: | ||
=Use Encoding Other Than UTF-8= | =Use Encoding Other Than UTF-8= | ||
− | By default, the encoding of properties files | + | By default, the encoding of properties files is assumed to be <code>UTF-8</code>. If you prefer another encoding, please specify it in a library property called <code>org.zkoss.util.label.web.charset</code>. It also means all properties files must be encoded in the same character set. |
For more information, please refer to [[ZK Configuration Reference/zk.xml/The Library Properties/org.zkoss.util.label.web.charset|ZK Configuration Reference]]. | For more information, please refer to [[ZK Configuration Reference/zk.xml/The Library Properties/org.zkoss.util.label.web.charset|ZK Configuration Reference]]. | ||
=Version History= | =Version History= | ||
− | + | ||
− | {| | + | {| class='wikitable' | width="100%" |
! Version !! Date !! Content | ! Version !! Date !! Content | ||
|- | |- |
Latest revision as of 02:38, 1 February 2024
In this section, we will discuss the format of a properties file, such as zk-label.properties
.
A properties file is a simple text file. The file contains a list of key=value
pairs, such as
# This is the default LabelsBundle.properties file
s1=computer
s2=disk
s3=monitor
s4=keyboard
The default encoding of a properties file is assumed to be UTF-8. If you want to use a different encoding, please refer to the Use Encoding Other Than UTF-8 section.
A properties file is usually used to contain the internationalization labels of an application, but technically you could use it in any situation you'd like[1].
- ↑ If it is used for internationalization labels, it will be loaded automatically. If you want to use it in other situations, you have to invoke Maps.load(Map, InputStream, boolean) or similar to load it manually.
Specify a Value with Multiple Lines
By default, a property is a text specified right after the equal sign. If the property's value has multiple lines, you could use the following format:
multilines={
line 1
line 2
}
Notice that the curly braces must be followed by a line break immediately, and the right brace (}
) must be the only character in the line.
Then you should put the value in a multiple-line label:
<label multiline="true" value="${labels.multilines}"/>
Render Multiple Lines
Alternatively, you can write a value with <br>
:
lines=1st line <br> 2nd line
Then render it in an HTML span
<zk xmlns:h="native">
<h:span>${labels.lines}</h:span>
</zk>
Specify Segmented Keys
Since all internationalization labels are stored in the same scope, it is common to separate them by naming the key with dots (.) like the Java package name. For the sake of description, we call them segmented keys. For example,
order.fruit.name = Orange
order.fruit.description = A common fruit
It can be simplified by use of the following syntax:
order.fruit. {
name = Orange
description = A common fruit
}
As shown, the segmented key could be specified by specifying the prefix and a following right brace ({).
The segmented key could be accessed in two ways.
First, with an implicit object called labels:
<textbox value="${labels.order.fruit.name}"/>
Second, with an EL function called l and/or l2:
<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>
<label value="${c:l('order.fruit.name')}">
Under the hood
The labels
object is actually the map returned by Labels.getSegmentedLabels(). Furthermore, if the key of a property contains dots (.
), i.e., segmented, all properties with the same prefix are grouped as another map. For example, ${labels.order}
(i.e., Labels.getSegmentedLables().get("order")
) will return a map containing an entry (fruit
) in the above example.
Specify a Comment
You could put a comment line by starting with the sharp sign (#), such as
#This is a comment line that will be ignored when loaded
Use EL Expressions
EL expressions are allowed for a property's value. For example, you could reference a property's value in another property, such as
first=the first label
second=come after ${first}
Since 5.0.7Segmented keys are also allowed:
group1.first=the first group
group2.second=come after ${group1.first}
In addition to referencing another property, you could reference any implicit object specified in ZUML Reference: Implicit Objects if it is part of an HTTP request (excluding component/page).
For example, param references to a request's parameter:
message=Thank ${param.user} for using
Use Encoding Other Than UTF-8
By default, the encoding of properties files is assumed to be UTF-8
. If you prefer another encoding, please specify it in a library property called org.zkoss.util.label.web.charset
. It also means all properties files must be encoded in the same character set.
For more information, please refer to ZK Configuration Reference.
Version History
Version | Date | Content |
---|---|---|
5.0.7 | Mar 2011 | labels implicit object was introduced to access properties without declaring taglib. Also allows label keys of a.b.c format. |