JSF标签

JSF标签详解

一、 輸出類標籤

輸出類的標籤包括了outputLabel、outputLink、outputFormat與 outputText，分別舉例說明如下：

outputLabel

　　產生<label> HTML標籤，使用for屬性指定元件的client ID，例如：

<h:inputText id="user" value="#{user.name}"/>
<h:outputLabel for="user" value="#{user.name}"/>

　　這會產生像是以下的標籤：

<input id="user" type="text" name="user" value="guest" />
<label for="user">

outputLink

　　產生<a> HTML標籤，例如：

<h:outputLink value="../index.jsp">
    <h:outputText value="Link to Index"/>
    <f:param name="name" value="MyName"/>
</h:outputLink>

　　你可搭配<f:param>幫鏈結加上參數，所有的參數都會變成 name=value 的型態附加在連結後。

　　value所指定的內容也可以是JSF EL綁定。

outputFormat

　　產生指定的文字訊息，可以搭配<f:param>來設定訊息的參數以格式化文字訊息，例如：

<f:loadBundle basename="messages" var="msgs"/>
 <h:outputFormat value="#{msgs.welcomeText}">
     <f:param value="Hello"/>
     <f:param value="Guest"/>
 </h:outputFormat>

　　如果您的messages.properties包括以下的內容：

welcomeText={0}, Your name is {1}.

　　則{0}與{1}會被取代為<f:param>設定的文字，最後顯示的文字會是：

Hello, Your name is Guest.

　　另一個使用的方法則是：

<h:outputFormat value="{0}, Your name is {1}.">
     <f:param value="Hello"/>
     <f:param value="Guest"/>
 </h:outputFormat>

outputText

　　簡單的顯示指定的值或綁定的訊息，例如：

<h:outputText value="#{user.name}"/>

二、 輸入類標籤

輸入類標籤包括了inputText、inputTextarea、inputSecret、 inputHidden，分別舉例說明如下：

inputText

　　顯示單行輸入欄位，即輸出<input> HTML標籤，其type屬性設定為text，例如：

<h:inputText value="#{user.name}"/>

inputTextarea

　　顯示多行輸入文字區域，即輸出<textarea> HTML標籤，例如：

<h:inputTextarea value="#{user.command}"/>

inputSecret

　　顯示密碼輸入欄位，即輸出<input> HTML標籤，其type屬性設定為password，例如：

<h:inputSecret value="#{user.password}"/>

　　您可以設定redisplay屬性以決定是否要顯示密碼欄位的值，預設是false。

inputHidden

　　隱藏欄位，即輸出<input> HTML標籤，其type屬性設定為hidden，隱藏欄位的值用於保留一些訊息於客戶端，以在下一次發送表單時一併送出，例如：

<h:inputHidden value="#{user.hiddenInfo}"/>

三、 命令類標籤

命令類標籤包括commandButton與commandLink，其主要作用在於提供一個命令按鈕或連結，以下舉例說明：

commandButton

　　顯示一個命令按鈕，即輸出<input> HTML標籤，其type屬性可以設定為button、submit或reset，預設是submit，按下按鈕會觸發 javax.faces.event.ActionEvent，使用例子如下：

<h:commandButton value="送出" action="#{user.verify}"/>

　　您可以設定image屬性，指定圖片的URL，設定了image屬性的話，<input>標籤的type屬性會被設定為image，例如：

<h:commandButton value="#{msgs.commandText}" 
                  image="images/logowiki.jpg"
                  action="#{user.verify}"/>

commandLink

　　產生超連結，會輸出<a> HTML標籤，而href屬性會有'#'，而onclick屬性會含有一段JavaScript程式，這個JavaScript的目的是按下連結後自動提交表單，具體來說其作用就像按鈕，但外觀卻是超連結，包括在本體部份的內容都會成為超連結的一部份，一個使用的例子如下：

<h:commandLink value="#{msgs.commandText}"
                action="#{user.verify}"/>

　　產生的HTML輸出範例如下：

<a href="#" onclick="document.forms['_id3']['_id3:_idcl'].value='_id3:_id13'; document.forms['_id3'].submit(); return false;">Submit</a>

　　如果搭配<f:param>來使用，則所設定的參數會被當作請求參數一併送出，例如：

<h:commandLink>
   <h:outputText value="welcome"/>
   <f:param name="locale" value="zh_TW"/>
 </h:commandLink>

四、 選擇類標籤

選擇類的標籤可略分為單選標籤與多選標籤，依外型的不同可以分為單選鈕（Radio）、核取方塊（CheckBox）、列示方塊（ListBox）與選單（Menu），以下分別先作簡單的說明。

<h:selectBooleanCheckbox>

　　在視圖上呈現一個核取方塊，例如：

我同意 <h:selectBooleanCheckbox value="#\{user.aggree\}"/>

　　value所綁定的屬性必須接受與傳回boolean型態。這個元件在網頁上呈現的外觀如下：

<h:selectOneRadio>、<h:selectOneListbox>、<h: selectOneMenu>

　　這三個標籤的作用，是讓使用者從其所提供的選項中選擇一個項目，所不同的就是其外觀上的差別，例如：

<h:selectOneRadio value="#{user.education}">
   <f:selectItem itemLabel="高中" itemValue="高中"/>
   <f:selectItem itemLabel="大學" itemValue="大學"/>
   <f:selectItem itemLabel="研究所以上" itemValue="研究所以上"/>
 </h:selectOneRadio><p>

　　value所綁定的屬性可以接受字串以外的型態或是自訂型態，但記得如果是必須轉換的型態或自訂型態，必須搭配 標準轉換器 或 自訂轉換器 來轉換為物件，<h:selectOneRadio>的外觀如下：

　　您也可以設定layout屬性，可設定的屬性是lineDirection、pageDirection，預設是lineDirection，也就是由左到右來排列選項，如果設定為pageDirection，則是由上至下排列選項，例如設定為：

<h:selectOneRadio layout="pageDirection" 
                   value="#{user.education}">
   <f:selectItem itemLabel="高中" itemValue="高中"/>
   <f:selectItem itemLabel="大學" itemValue="大學"/>
   <f:selectItem itemLabel="研究所以上" itemValue="研究所以上"/>
 </h:selectOneRadio><p>

　　則外觀如下：

　　<h:selectOneListbox>、<h:selectOneMenu>的設定方法類似於<h: selectOneRadio>，以下分別列出<h:selectOneListbox>、<h: selectOneMenu>的外觀：

　<h:selectManyCheckbox>、<h:selectManyListbox>、<h: selectManyMenu>

　　這三個標籤提供使用者複選項目的功能，一個<h:selectManyCheckbox>例子如下：

<h:selectManyCheckbox layout="pageDirection" 
                       value="#{user.preferColors}">
     <f:selectItem itemLabel="紅" itemValue="false"/>
     <f:selectItem itemLabel="黃" itemValue="false"/>
     <f:selectItem itemLabel="藍" itemValue="false"/>
 </h:selectManyCheckbox><p>

　　value所綁定的屬性必須是陣列或集合（Collection）物件，在這個例子中所使用的是boolean陣列，例如：

UserBean.java

package onlyfun.caterpillar;

 public class UserBean {
    private boolean[] preferColors;

    public boolean[] getPreferColors() {
        return preferColors;
    }

    public void setPreferColors(boolean[] preferColors) {
        this.preferColors = preferColors;
    }

    ......
 }

　　如果是其它型態的物件，必要時必須搭配轉換器（Converter）進行字串與物件之間的轉換。

　　下圖是<h:selectManyCheckbox>的外觀，這是將layout設定為pageDirection的外觀：

　　<h:selectManyListbox>的設定方法類似，其外觀如下：

　　<h:selectManyMenu>在不同的瀏覽器中會有不同的外觀，在Mozilla Firefox中是這樣的：

　　在Internet Explorer則是這樣的：

選擇類標籤可以搭配<f:selectItem>或<f:selectItems>標籤來設定選項，例如：

<f:selectItem itemLabel="高中" 
               itemValue="高中"
               itemDescription="學歷"
               itemDisabled="true"/>

　　itemLabel屬性設定顯示在網頁上的文字，itemValue設定發送至伺服端時的值，itemDescription 設定文字描述，它只作用於一些工具程式，對HTML沒有什麼影響，itemDisabled設定是否選項是否作用，這些屬性也都可以使用JSF Expression Language來綁定至一個值。

　　<f:selectItem>也可以使用value來綁定一個傳回javax.faces.model.SelectItem的方法，例如：

<f:selectItem value="#{user.sex}"/>

　　則綁定的Bean上必須提供下面這個方法：

....
     public SelectItem getSex()  {
        return new SelectItem("男");
     }
 ....

　　如果要一次提供多個選項，則可以使用<f:selectItems>，它的value綁定至一個提供傳回SelectItem?的陣列、集合，或者是Map物件的方法，例如：

<h:selectOneRadio value="#{user.education}">
     <f:selectItems value="#{user.educationItems}"/>
 </h:selectOneRadio><p>

　　這個例子中<f:selectItems>的value綁定至user.educationItems，其內容如下：

....
     private SelectItem[] educationItems; 
    
    public SelectItem[] getEducationItems() {
        if(educationItems == null) {
            educationItems = new SelectItem[3];    
            educationItems[0] = 
                  new SelectItem("高中", "高中");
            educationItems[1] = 
                  new SelectItem("大學", "大學");
            educationItems[2] = 
                  new SelectItem("研究所以上", "研究所以上");
        }
        
        return educationItems;
    }
 ....

　　在這個例子中，SelectItem的第一個建構參數用以設定value，而第二個參數用以設定label，SelectItem還提供有數個建構函式，記得可以參考一下線上API文件。

　　您也可以提供一個傳回Map物件的方法，Map的key-value會分別作為選項的label-value，例如：

<h:selectManyCheckbox layout="pageDirection" 
                       value="#{user.preferColors}">
    <f:selectItems value="#{user.preferColorItems}"/>
 </h:selectManyCheckbox><p>

　　您要提供下面的程式來搭配上面這個例子：

....
    private Map preferColorItems;
    
    public Map getPreferColorItems() {
        if(preferColorItems == null) {
            preferColorItems = new HashMap();
            preferColorItems.put("紅", "Red");
            preferColorItems.put("黃", "Yellow");
            preferColorItems.put("藍", "Blue");
        }
        
        return preferColorItems;
    }
 ....

五、 其它標籤

<h:messages>或<h:message>標籤的介紹，在 錯誤訊息處理 中已經有介紹了。

<h:graphicImage>

　　這個標籤會繪製一個HTML <img>標籤，value可以指定路徑或圖片URL，路徑可以指定相對路徑或絕對路徑，例如：

<h:graphicImage value="/images/logowiki.jpg"/>

<h:panelGrid>

　　這個標籤可以用來作簡單的元件排版，它會使用HTML表格標籤來繪製表格，並將元件置於其中，主要指定columns屬性，例如設定為 2：

<h:panelGrid columns="2">
    <h:outputText value="Username"/>
    <h:inputText id="name" value="#{userBean.name}"/>
    <h:outputText value="Password"/>  		    
    <h:inputText id="password" value="#{userBean.password}"/>
    <h:commandButton value="submit" action="login"/>
    <h:commandButton value="reset" type="reset"/>
 </h:panelGrid>

　　則自動將元件分作 2 個 column來排列，排列出來的樣子如下：

　　<h:panelGrid>的本體間只能包括JSF元件，如果想要放入非JSF元件，例如簡單的樣版（template）文字，則要使用 <f:verbatim>包括住，例如：

<h:panelGrid columns="2">
    <f:verbatim>Username</f:verbatim>
    <h:inputText id="name" value="#{userBean.name}"/>
    <f:verbatim>Password</f:verbatim>
    <h:inputText id="password" value="#{userBean.password}"/>
    <h:commandButton value="submit" action="login"/>
    <h:commandButton value="reset" type="reset"/>
 </h:panelGrid>

<h:panelGroup>

　　這個元件用來將數個JSF元件包裝起來，使其看來像是一個元件，例如：

<h:panelGrid columns="2">
    <h:outputText value="Username"/>
    <h:inputText id="name" value="#{userBean.name}"/>
    <h:outputText value="Password"/>  		    
    <h:inputText id="password" value="#{userBean.password}"/>
    <h:panelGroup>
        <h:commandButton value="submit" action="login"/>
        <h:commandButton value="reset" type="reset"/>
    </h:panelGroup>
 </h:panelGrid>

　　在<h:panelGroup>中包括了兩個<h:commandButton>，這使得< h:panelGrid>在處理時，將那兩個<h:commandButton>看作是一個元件來看待，其完成的版面配置如下所示：