7.3. JSP Tag Libraries and EL Functions offered by common library

7.3.1. Overview

Below are the JSP Tag Libraries and EL Functions offered by common library as an ability to support the JSP implementation.

7.3.1.1. JSP Tag Library

Below are the JSP Tag Libraries offered by common library.

Sr.No
Tag name
Overview
<t:pagination> Outputs the pagination link.
<t:messagesPanel> Outputs the result message.
<t:transaction> Outputs the transaction token as hidden item.

7.3.1.2. EL Functions

Below are the EL Functions offered by common library.

XSS counter measures

Sr.No
Function Name
Overview
f:h() Converts the specified object into a string and escape the HTML special characters from converted string.
f:js() Escape the JavaScript special characters from the specified string.
f:hjs() After escaping the JavaScript special characters from the specified string, escape the HTML special characters. (short function of f:h(f:js()))

URL related

Sr.No
Function Name
Overview
f:query() Generates UTF-8 URL encoded query string from the specified object.
f:u() Performs UTF-8 URL encoding on specified string.

DOM related

Sr.No
Function Name
Overview
f:link() Generates a hyperlink (<a> tag) for jumping to specified URL.
f:br() Converts the new line character into <br /> tag from the specified string.

Utility

Sr.No
Function Name
Overview
f:cut() Extracts specified number of characters from the specified string.

7.3.2. How to use

The use of JSP Tag Library and EL function offered by common library explained below. The appropriate Hyperlink is placed at appropriate location if detail description explained in other chapters.


7.3.2.1. <t:pagination>

The <t:pagination> tag is a JSP Tag Library to output the pagination link by referring the information stored in page search results (org.springframework.data.domain.Page).

For detail description of pagination and how to use this tag, Refer the following section [Pagination].


7.3.2.2. <t:messagesPanel>

The <t:messagesPanel> tag is a JSP Tag Library to output the processing result message, (Such as org.terasoluna.gfw.common.message.ResultMessage or message having exception).

Refer the following section [Message Management] for how to use this tag.


7.3.2.3. <t:transaction>

The <t:transaction> tag is a JSP Tag Library to output the transaction token as hidden item (<input type="hidden">").

Refer the following section [Double Submit Protection] for the transaction token check feature and how to use this tag.

Note

This tag is used for sending a transaction token to the server while using standard HTML <form> tag.

No need to use this tag if spring framework offered <form:form> tag (JSP Tag Library) has been used because org.terasoluna.gfw.web.token.transaction.TransactionTokenRequestDataValueProcessor offered by the common library has been already mechanized to handle a transaction token.


7.3.2.4. f:h()

The f:h() is an EL Function which converts the specified object into a string and escape the HTML special characters from converted string.

Refer [Output Escaping] for the specification of HTML special characters and escaping.

7.3.2.4.1. f:h() function specification

Argument

Sr.No Type Description
java.lang.Object Object that contain HTML special characters

Note

Specified objects,

  • In case of array, java.util.Arrays#toString method
  • In case of not array, toString method of specified object

is called for the string conversions.

Return value

Sr.No Type Description
java.lang.String

String after HTML escaping

If the object specified in argument is null , returns the empty string("").

7.3.2.4.2. f:h() how to use

For the information about how to use f:h() function, refer [Example of escaping output value using f:h() function].


7.3.2.5. f:js()

The f:js() is an EL Function which escape the JavaScript special characters from the specified string argument.

Refer [JavaScript Escaping] for the specification of JavaScript special characters and escaping.

7.3.2.5.1. f:js() function specification

Argument

Sr.No Type Description
java.lang.String String that contain JavaScript special characters

Return value

Sr.No Type Description
java.lang.String

String after JavaScript escaping

If the string specified in argument is null , it returns the empty string("").

7.3.2.5.2. f:js() how to use

For the information about how to use f:js() function, refer [Example of escaping output value using f:js() function].


7.3.2.6. f:hjs()

The f:hjs() is an EL Function which escapes the HTML special characters after escaping the JavaScript special characters from the specified string argument, (short function of f:h(f:js())).

7.3.2.6.1. f:hjs() function specification

Argument

Sr.No Type Description
java.lang.String String that contain HTML special characters or JavaScript special characters

Return value

Sr.No Type Description
java.lang.String

String after JavaScript and HTML escaping.

If the string specified in argument is null , it returns the empty string("").

7.3.2.6.2. f:hjs() how to use

For the information about how to use f:hjs() function, refer [Example of escaping output value using f:hjs() function].


7.3.2.7. f:query()

The f:query() is an EL Function which generates the query string from java.util.Map object or JavaBean (form object) that is specified in the argument. Parameter names and parameter values in the query string are URL encoded in UTF-8.

URL encoding specification explained below.

In this function, the parameter name and parameter value of the query string are encoded on RFC 3986 basis. In RFC 3986, the part of query string is defined as follows.

../_images/TagLibAndELFunctionsRFC3986UriSyntax.png
  • query = *( pchar / "/" / "?")
  • pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
  • unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
  • sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
  • pct-encoded = "%" HEXDIG HEXDIG

In this function, one of the character that can be used as a query string,

  • "=" (Separator character of the parameter name and parameter value)
  • "&" (Separator character when dealing with multiple parameters)
  • "+" (Character that represent a space when you submit HTML Form)

are encoded in the pct-encoded formatting string.

7.3.2.7.1. f:query() function specification

Argument

Sr.No Type Description
java.lang.Object

Object from which the query string generated (JavaBean or Map)

Property name will be a request parameter name if you have specified a JavaBean and key name will be a request parameter name if you specified the Map.

Supported value types of JavaBean’s property and value of Map are as follows:

  • Classes which implements Iterable interface
  • Array
  • Classes which implements Map interface
  • JavaBean
  • Simple Types (classes that can converted to String type the using DefaultFormattingConversionService)

From the terasoluna-gfw-web 5.0.1.RELEASE, it has been improved to be able specify a nested structured JavaBean or Map.

Note

A simple type property value of the specified object is converted into string using the convert method of org.springframework.format.support.DefaultFormattingConversionService. Refer Spring Framework Reference Documentation(Spring Type Conversion)for the ConversionService.

Return value

Sr.No Type Description
java.lang.String

Query string that is generated based on the specified object in the argument (URL encoded string in UTF-8)

If the object specified in argument is other than the JavaBean or Map, it returns the empty string("").

Note

Rules for conversion to the query string

f:query() converts an object so that the Spring Web MVC can handle it at binding process provided.

[Request parameter name]

Conditions Conversion specification of parameter name Conversion examples
Case that property type is an instance of Iterable Property name + [element position] status[0]=accepting
Case that property type is an instance of Iterable or Array and the value of the element is empty
Property name
(Does not append [element position])
status=
Case that property type is an instance of Map Property name + [Map's key name] status[accepting]=Accepting Order
Case that property type(including element type in Iterable,Array and Map) is JavaBean Value that combined a property name with "."(dot)
mainContract.name=xxx
subContracts[0].name=xxx
Case that property type is a simple type Property name userId=xxx
Case that property value is null _(underscore) + Property name
_mainContract.name=
_status[0]=
_status[accepting]=

[Request parameter value]

Conditions Conversion specification of parameter value Conversion examples
Case that property value is null Empty string _userId=
Case that property type is an instance of Iterable or Array and the value of the element is empty Empty string status=
Case that property value is not null Value that can be converted to String type using the DefaultFormattingConversionService targetDate=20150801

7.3.2.7.2. f:query() how to use

For the information about how to use f:query() function, refer [Carrying forward search conditions using page link]. Here, this function is used as to carry forward the search criteria while switching the pages using the pagination link. Further, function description and the specification also described here and that should be read.


7.3.2.8. f:u()

The f:u() is an EL Function which performs UTF-8 URL encoding on specified string argument.

This function is provided for performing URL encoding on those values which are going to be set as parameter values in the query string. For the URL encoding specification, refer [f:query()]

7.3.2.8.1. f:u() function specification

Argument

Sr.No Type Description
java.lang.String String that contain URL encoding required characters

Return value

Sr.No Type Description
java.lang.String

String after URL encoding

If the string specified in argument is null , it returns the empty string("").

7.3.2.8.2. f:u() how to use

<div id="url">
    <a href="https://search.yahoo.com/search?p=${f:u(bean.searchString)}">  <!-- (1) -->
        Go to Yahoo Search
    </a>
</div>
Sr.No Description
(1)
In the above example, sets the URL-encoded value to the request parameters of the search site using this function.

7.3.2.10. f:br()

The f:br() is an EL Function which converts the new line character (CRLF, LF, CR) specified in the argument into <br /> tag.

Tip

If you want to display a string containing new line code as a newline on browser, it is necessary to convert the new line code into `` <br /> `` tag.

For example, if you want to display the string entered in the textarea (<textarea>) of the input screen as it is on the confirmation screen or completion screen, it is advisable to use this function.

7.3.2.10.1. f:br() function specification

Argument

Sr.No Type Description
java.lang.String String that contain new line code

Return value

Sr.No Type Description
java.lang.String

String after conversion

If the string specified in argument is null , it returns the empty string("").

7.3.2.10.2. f:br() how to use

<div id="text">
    ${f:br(f:h(bean.text))}">  <!-- (1) -->
</div>
Sr.No Description
(1)
The newline displays on the browser by converting the new line character into <br /> tag from the specified string argument.

Note

When you display a string on the screen, there is a need to escape the HTML special character as [XSS Countermeasures].

if you are converting new line code into <br /> tag using f:br() function, as in the above example, a string that has escaped the HTML special characters need to pass as an argument to f:br() function.

The string obtained by converting new line code into <br /> tag using f:br() function passes as an argument to the f:h() function, the letter "<br />" get displayed on the browser hence be careful in order to call the function.


7.3.2.11. f:cut()

The f:cut() is an EL Function which extracts specified number of characters from the specified string.

7.3.2.11.1. f:cut() function specification

Argument

Sr.No Type Description
java.lang.String String from which extraction is done
int The number of characters that can extracted

Return value

Sr.No Type Description
java.lang.String

The extracted string (String part that exceeds the specified number of characters has been destroyed)

If the string specified in argument is null , it returns the empty string("").

7.3.2.11.2. f:cut() how to use

<div id="cut">
    ${f:h(f:cut(bean.originText, 5))}  <!-- (1) -->
</div>
Sr.No Description
(1)
In the above example, you can extract the first five characters of the string that was specified in the argument and displays on the screen.

Note

There is a need to escape the HTML special character as [XSS Countermeasures] while displaying the extracted string on the screen. In the above example, string is escaped by using f:h() function.