The Format of Properties Files"

From Documentation
(5 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
__TOC__
 
__TOC__
  
In this section, we discuss the format of a properties file, such as <tt>i3-label.properties</tt>.
+
In this section, we will discuss the format of a properties file, such as <tt>zk-label.properties</tt>.
  
 
A properties file is a simple text file. The file contains a list of <tt>key=value</tt> pairs, such as
 
A properties file is a simple text file. The file contains a list of <tt>key=value</tt> pairs, such as
Line 15: Line 15:
 
</source>
 
</source>
  
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 situation, 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>.
 
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 situation, 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>.
Line 102: Line 102:
 
</source>
 
</source>
  
In additions 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 a HTTP request (excluding component/page).
+
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 a 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:

Revision as of 06:25, 11 April 2017


The Format of Properties Files


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].


  1. If it is used for internationalization labels, it will be loaded automatically. If you want to use it in other situation, 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 the text specified right after the equal sign. If the property's value has multiple lines, you could use the following format:

key={
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.

Specify Segmented Keys

Since all internationalization labels are stored in the same scope, it is common to separate them by naming the key with dot (.) like the Java package name. For sake of description, we call them segmented key. 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}"/>

Under the hood: The labels object is actually the map returned by Labels.getSegmentedLabels(). Furthermore, if the key of a property contains dot (.), 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.

Second, with an EL function called [[ZUML Reference/EL Expressions/Core Methods/l|l] and/or l2:

<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>
<label value="${c:l('order.fruit.name')}">

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}

Segmented keys are also allowed[1]:

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 a HTTP request (excluding component/page).

For example, param references to a request's parameter:

message=Thank ${param.user} for using

  1. The segmented key was supported since 5.0.7

Use Encoding Other Than UTF-8

By default, the encoding of properties files are 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

Last Update : 2017/04/11


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.



Last Update : 2017/04/11

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