Appendix A. 
Prev   

Table of Contents

A.1. Taglibs
A.1.1. Tags reference
A.1.2. Function reference

This tag sets a scope variable to a specific value. The variable can be in any scope supported by Phable.

AttributeDescription
var The name of the variable which will hold the specified value.
value The value to store in the variable.
scope Optional variable scope. Default is the page scope.

Example A.1. Setting a session scope variable

<html>
  <body>
    <c:set var="planet" scope="session" value="Earth" />
  </body>
</html>

This tag prints the specified expression. In most cases you don't need this tag because you can use the expression language directly for output but this method is here for compatibility reasons to the JSTL and because you might find it useful to specify a default value which will be used if the expression evaluates to null.

AttributeDescription
value The expression to be evaluated.
default Optional default value which is printed if the specified value evaluates to null.
escapeXml Optional flag to determine if the output should be XML-escaped with entities for the special XML characters <, >, &, ' and ". This flag is true by default

Example A.2. Printing the value of a variable

<html>
  <body>
    <c:out value="${planet}" default="No planet" />
  </body>
</html>

This tag removes the specified variable from a particular scope.

AttributeDescription
var The variable to remove.
scope The scope from which the variable should be removed. If not specified then the variable will be removed only from the page scope.

Example A.3. Removing a variable

<html>
  <body>
    <c:remove var="planet" scope="session" />
  </body>
</html>

With these three tags you can build a switch block in HTML. This is usefull if you want to output different HTML blocks depending on the value of a variable. The choose tag is used to encapsulate the whole switch block. The when tag is used to specify the switch cases and the otherwise tag can be used to specify a fallback block which will be executed if no switch case matches. choose and otherwise don't have any parameters so the following list contains the attributes of the when tag:

AttributeDescription
test A condition to check. If it evaluates to true then the switch case is executed. If it evaluates to false then it is ignored.

Example A.4. Conditional HTML in switch block style

<html>
  <body>
    <c:choose>
      <c:when test="${planet == 'earth'}">
        <p>Earth. Mostly harmless.</p>
      </c:when>
      <c:when test="${planet == 'alphacentauri'}">
        <p>
          Alpha Centauri is the Earth's second nearest star. Actually, 
          it isn't, Proxima Centauri is right now, and by the time Alpha 
          Centauri is again, we'll have all snufffed it, but no-one 
          intelligent lives there, so it doesn't count.
        </p>
      </c:when>
      <otherwise>
        <p>Nothing is known about planet ${planet}</p>
      </otherwise>
    </c:choose>
  </body>
</html>

This tag can be used to build a simple conditional block. If the test expression evaluates to true then the body of this tag is executed. Otherwise it is ignored. Additionaly the result of the test expression can be stored in a scoped variable.

AttributeDescription
test A condition to check. If it evaluates to true then the body is executed. If it evaluates to false then it is ignored.
var Optional variable name which will hold the result of the test expression.
scope Optional scope for the variable. If not specified then the variable is stored in page scope.

Example A.5. Conditional HTML with if statement

<html>
  <body>
    <c:if test="${counter > 1000}">
      <p>You were here to often. Go away.</p>
    </c:if>
  </body>
</html>

With the forEach tag you can iterate over a list of items. This list can be an array or hash map in a scope variable but it can also be a comma separated list of values or it can be constructed with the begin, end and step attributes. The varStatus attribute can be used to get detailed informations about the current iteration run.

The forTokens tag is identical to the forEach tag, the only difference is the additional attribute delims which can be used to define the delimiter characters which separates the specified string into items.

AttributeDescription
items A collection of items to iterate over. Can be a comma separated list of values or an expression which evaluates to a comma separated list of values or to a real array or hash map. If this attribute is not used then the begin, end and step attributes are used to build a list of items.
begin Defines on which index of the items the iteration should begin. Default is 0 which means iteration starts at the beginning of the collection.
end Defines on which index of the items collection the iteration should stop. Default is the end of the items collection.
step Defines in which steps the iteration should be performed. Default is 1 so every item of the collection is included in the iteration.
var Defines the variable name which is set to the current value of the iterated items collection.
varStatus Optional. Defines the variable name which is set to an object which holds detailed informations about the current iteration run. See below.
delimiter Optional. Only valid for the forTokens tag. Defines the delimiter characters that separate the tokens in the string.

The varStatus object contains the following properties:

PropertyDescription
current The current iteration value.
index The current numerical index of the iteration.
first A boolean which is set to true on the first iteration run. Useful to perform special actions for the first item in the collection.
last A boolean which is set to true on the last iteration run. Useful to perform special actions for the last item in the collection.
count An iteration counter. Starts by 0 and is increased on each iteration run.
key The hash key of the current collection item.

Example A.6. Iterations with forEach and forTokens

<html>
  <body>
    <c:forEach items="Mercury,Vernus,Earth,Mars" var="planet">
      <p>Planet: ${planet}</p>
    </c:forEach>
    <c:forTokens items="Mercury:Vernus:Earth:Mars" var="planet" delims=".">
      <p>Planet: ${planet}</p>
    </c:forEach>
    <c:forEach items="${planets}" var="planet">
      <p>Planet: ${planet}</p>
    </c:forEach>
    <c:forEach begin="1800" end="2100" step="100" var="century">
      <p>Century: ${century}</p>
    </c:forEach>
    <c:forEach items="${hashmap}" varStatus="status">
      <p>Hash-Key: ${status.key}}</p>
      <p>Hash-Value: ${status.current}}</p>
    </c:forEach>
  </body>
</html>

This tag imports the contents of a url into a variable or directly into the current page.

PropertyDescription
url The URL to be imported.
var Name of a variable to hold the content of the URL. If not specified then the content will be printed direclty to the page.
scope The scope of the variable.

Example A.7. Importing local and remote pages

<html>
  <body>
    <c:import url="header.php" />

    <!-- Import the goole website into a variable -->
    <c:import url="http://www.google.com/" var="google" />

    <c:import url="footer.php" />
  </body>
</html>

This tag can be used to redirect the user to another page.

PropertyDescription
url The URL to redirect to.

Example A.8. Perform a redirect

<html>
  <body>
    <c:if test="${age < 18}">
      <c:redirect url="http://www.disney.com/" />
    </c:if>
  </body>
</html>

bool contains(subject, search);
string subject;
string search;

Checks if subject contains the substring search.

bool containsIgnoreCase(subject,  
 search); 
string  subject;
string  search;

Checks if subject contains the substring search. The check is done case-insensitive.

bool endsWith(subject, end);
string subject;
string end;

Checks if subject ends with the string end.

string escapeXml(string);
string string;

Escape XML-characters in string and return the escaped string.

int indexOf(subject, search);
string subject;
string search;

Returns the index of the substring search in the string subject. If the substring is not found then -1 is returned.

string join(items, delimiter);
array items;
string delimiter;

Joins all elements of items into a string. The elements are separated by delimiter. The joined string is then returned.

int length(subject);
mixed subject;

Returns the size of subject. This works with strings and arrays.

string replace(subject,  
 search,  
 replace); 
string  subject;
string  search;
string  replace;

Replaces all occurrences of search in subject with replace and returns the new string.

array split(items, delimiter);
string items;
string delimiter;

Splits a string into an array of substrings which are separated by delimiter.

boolean startsWith(subject,  
 search); 
string  subject;
string  search;

Checks if subject starts with the string search.

string substring(subject,  
 begin,  
 end); 
string  subject;
int  begin;
int  end;

Returns a substing of subject. Setting end to -1 means match the rest of the subject.

string substringAfter(subject,  
 search); 
string  subject;
string  search;

Returns the substring behind search. subject.

string substringBefore(subject,  
 search); 
string  subject;
string  search;

Returns the substring before search. subject.

string toLowerCase(string);
string string;

Returns lowercase version of string.

string toUpperCase(string);
string string;

Returns upperrcase version of string.

string trim(string);
string string;

Removes whitespaces from both ends of string.

string append(str1, str1);
string str1;
string str1;

Call this function get the width of the current device. Appends str2 to str1 and returns the resulting string.

Prev Up 
2.9. Writing your own taglibs Home