Стандартные JSF components

Стандартные JSF componets разделены на две части: базовые компоненты JSF и HTML компоненты JSF. В таблице представлены по колонкам базовые и HTML компоненты.

Базовые компоненты JSF

К базовым относятся компоненты JSF, которые не связаны с рендерингом страницы HTML или с каким-либо другим механизмом отображения информации. Среди прочего они используются для преобразования типов и проверка допустимости значений.

f:actionListener

Тег определяет выполнение метода действия слушателя processAction(), определяемый атрибутом type тега. Значение атрибута type должно быть полностью определенным (квалифицированным) именем класса, реализующего интерфейс javax.faces.event.ActionListener. Этот тег обычно является дочерним тегом h:commandButton или h:commandLink. Когда пользователь щелкает по родительскому компоненту, метод processAction() объявленной реализации ActionListener выполняется автоматически.

<h:commandButton action="save" value="Сохранить">
    <f:actionListener type="com.test.CustomActionListener" />
</h:commandButton>

f:ajax

Тег определяет поведение AJAX. Этот тег обычно вкладывается в другой тег JSF типа h:commandButton. Значением атрибута execute является разделенный пробелами список идентификаторов компонентов, которые будут использоваться в качестве входных при запуске запроса AJAX. Значением атрибута render является разделенный пробелами список компонентов для повторного отображения, после того как запрос AJAX будет завершен.

<h:commandButton actionListener="#{bean.calculate}">
    <f:ajax execute="first second" render="sum" />
</h:commandButton>

f:attribute

Тег устанавливает атрибут родительского компонента с ключом, определенным атрибутом name тега и значением, определенным атрибутом value тега. Все атрибуты компонента позже могут быть получены программно, как структура данных — карта Map, вызовом метода getAttributes() соответствующего экземпляра javax.faces.component.UIComponent. Этот тег часто используется в сочетании с классом f:actionListener, чтобы передать параметру методу действия слушателя.

<h:commandButton action="save" value="Save">
    <f:actionListener type="com.test.CustomActionListener" />
    <f:attribute name="attributeName" value="someValue" />
</h:commandButton>

f:convertDateTime

Тег используется для преобразования значения родительского компонента в экземпляр java.util.Date. Этот тег позволяет присваивать правильно отформатированную строку, вводимую пользователем, полю даты в управляемом бине.

<h:inputText value="#{user.birthday}">
    <f:convertDateTime dateStyle="short" />
</h:inputText>

Пример использования конвертера convertDateTime рассмотрен на странице Валидаторы и конвертеры.

f:converter

Регистрация преобразователя пользователя, указанныго атрибутом converterId тега, в родительском теге. Преобразователь должен представлять собой класс, реализующий интерфейс javax.faces.convert.Converter, и быть или декорированным аннотацией @FacesConverter, или зарегистрированным в дескрипторе конфигурации приложения, файле faces-config.xml, с помощью тега converter.

<h:inputText value="#{user.phone}">
    <f:converter converterId="PhoneConverter" />
</h:inputText>

f:convertNumber

Преобразование значения родительского компонента в экземпляр java.lang.Number. Данный тег позволяет правильно отформатировать строку, вводимую пользователем и присваиваемую числовому полю в управляемом бине.

<h:inputText value="#{user.age}">
    <f:convertNumber />
</h:inputText>

Пример использования конвертера convertNumber рассмотрен на странице Валидаторы и конвертеры.

f:event

Тег вызова метода компонента JavaBean при возникновении конкретного события. Этот тег вкладывается в другой тег JSF. Регистрируемое событие указывается в качестве значения атрибута type тега f:event. Для тега допустимы следующие значения:

• preRenderComponent - инициируется непосредственно перед тем, как компонент будет прорисован;
• PostAddToView - инициируется после того, как компонент будет добавлен к представлению;
• preValidate - инициируется непосредственно перед тем, как значение компонента будет проверено;
• postValidate - инициируется сразу после того, как значение компонента будет проверено.

Значение атрибута listener тега f:event должно указывать на метод, который определен в управляемом бине и удовлетворяет следующим требованиям: имеет модификатор видимости public, не возвращаетни какого значения и принимает экземпляр класса javax.faces.event.ComponentSystemEvent в качестве своего единственного параметра.

<h:inputText>
    <f:event type="preRenderComponent"
             listener="#{myBean.doSomething}" />
</h:inputText>

f:facet

Регистрация фасета на родительском компоненте. Фасет (facet) - это специальный дочерний компонент, к которому можно получить доступ с помощью метода UIComponent.getFacet. Этот метод может быть переопределен для пользовательских компонентов; данное обстоятельство позволяет иначе обрабатывать компоненты в фасете. Например, у стандартного тега h:dataTable может быть фасет, называемый "header", который будет использоваться для представления всех компонентов в теге f:facet в качестве заголовка представленной HTML-таблицы.

<h:dataTable value="#{order.items}" var="item">
    <h:column>
        <f:facet name="header">
            <h:outputText value="Number" />
        </f:facet>
        <h:outputText value="#{item.itemNumber}" />
    </h:column>
    <h:column>
        <f:facet name="header">
            <h:outputText value="Description" />
        </f:facet>
        <h:outputText value="#{item.itemDescription}" />
    </h:column>
</h:dataTable>

f:loadBundle

Загрузка пакета ресурса в контекст запроса. Имя пакета ресурса определяется атрибутом basename. Переменная пакета ресурса для использования определяется атрибутом var тега.

<f:view locale="#{facesContext.externalContext.request.locale}">
    <f:loadBundle basename="com.test.Messages" var="mess" />
    <h:outputText value="#{mess.helloWorld}" />
</f:view>

f:metadata

Данный тег является родительским для тега f:viewParam, который используется для отображения параметров GET-запроса на значения управляемого бина.

<f:metadata>
    <f:viewParam name="someParam" value="bean.someProp" />
</f:metadata>

f:param

Тег используется как дочерний с тегами h:commandLink и h:outputForm. Для тега h:commandLink, он генерирует параметр запроса, определенный его атрибутами name и value. Для тега h:outputForm он определяет подстановочное значение атрибута value.

<h:outputFormat value="Hello, {0}!" >
    <f:param value="#{user.name}" />
</h:outputFormat>

f:phaseListener

Регистрация слушателя на текущей странице. Слушатель должен быть экземпляром класса, реализующего интерфейс javax.faces.event.PhaseListener.

<f:view>
    <f:phaseListener type="com.test.CustomPhaseListener" />
</f:view>

f:selectItem

Тег используется в качестве дочернего компонента для тегов h:selectManyCheckBox, h:selectManyListBox, h:selectManyMenu, h:selectOneListBox, h:selectOneMenu и h:selectOneRadio. Добавляет элемент выбора родительскому компоненту.

<h:selectManyCheckbox value="#{order.items}" >
    <f:selectItem itemValue="#{item1}" itemLabel="Keyboard" />
    <f:selectItem itemValue="#{item1}" itemLabel="Mouse" />
</h:selectManyCheckbox>

f:selectItems

Добавляет набор выбираемых элементов родительскому компоненту. Атрибут тега value должен быть значением выражения, разрешающимся в массив или список обьектов javax.faces.model.SelectItem.

<h:selectManyCheckbox value="#{order.items}" >
    <f:selectItems value="#{valueContainer.allItems}" />
</h:selectManyCheckbox>

f:setPropertyActionListener

Может быть дочерним тегов h:commandLink или h:commandButton. При возникновении события типа Click по кнопке или ссылке, тег устанавливает значение атрибута в управляемом компоненте JavaBean, определенном в target с помощью значения value.

<h:commandButton value="Save" action="#{bean.save}">
    <f:setPropertyActionListener target="#{order.ownerId}"
                                    value="#{user.userId}" />
</h:commandButton>

f:subview

Тег f:subview предназначен для использования JSP в качестве представления. Включение JSP-страницы выполняется с помощью тега jsp:include или JSTL-тега c:import

<f:view>
    <div>
        <f:subview id="form">
            <jsp:include page="menu.jsp" />
        </f:subview>
    </div>
</f:view>

f:validateBean

Подключение или отключение тонкой настройки компонента JavaBean.

<h:inputText value="#{someBean.someProperty}">
    <f:validateBean disabled="#{anotherBean.someProperty}" />
</h:inputText>

f:validateDoubleRange

Проверка выполнения условия нахождения значения экземпляра типа java.lang.Double в диапазоне, определенном атрибутами minimum и maximum.

<h:inputText value="#{item.price}">
    <f:validateDoubleRange minimum="1.0" maximum="10.0" />
</h:inputText>

f:validateLength

Проверка введеной строки, чтобы размера находился в диапазоне между значениями, определенными атрибутами minimum и maximum.

<h:inputText label="Name" value="#{orderItem.name}" required="true">
    <f:validateLength minimum="2" maximum="20" />
</h:inputText>

f:validateLongRange

Проверка выполнения условия нахождения значения экземпляра типа java.lang.Long в диапазоне, определенном атрибутами minimum и maximum.

<h:inputText value="#{orderItem.quantity}">
    <f:validateLongRange minimum="1" maximum="100" />
</h:inputText>

f:validateRegex

Проверка значения родительского компонента на соответствие регулярному выражению, указанному в его атрибуте pattern.

<h:inputText value="#{user.phoneNumber}">
    <f:validateRegex pattern="\d{3}-\d{3}-\d{4}" />
</h:inputText>

f:validateRequired

Проверка значение родительского компонента (inputText). Тег эквивалентен установке атрибута required в значение true в компоненте ввода.

<h:inputText value="#{user.login}">
    <f:validateRequired />
</h:inputText>

f:validator

Проверка значения родительского компонента с использованием компонента JavaBean верификации, реализующего интерфейс javax.faces.validator.Validator. Компонент проверки должен быть или аннотирован @FacesValidator, или обьявлен в дескрипторе конфигурации приложения - файл faces-config.xml.

<h:inputText label="Email" value="#{user.email}">
    <f:validator validatorId="emailValidator" />
</h:inputText>

f:valueChangeListener

Подключение слушателя внесения изменения в значение родительского компонента. Слушатель должен реализовать интерфейс javax.faces.event.ValueChangeListener, включающего метод processValueChange(), который выполняется, если значение родительского компонента изменяется.

<h:inputText value="#{orderItem.quantity}">
    <f:valueChangeListener type="com.test.CustomValueChangeListener" />
</h:inputText>

f:verbatim

Содержимое тега передается без изменений в отображаемую страницу. До версии JSF 1.2 не рекомендовалось помещать HTML-теги внутри JSF-тега f:view, так как они иногда неправильно отображались. Обходным решением стало помещение стандартных HTML-тегов в теги f:verbatim. Начиная с JSF 1.2, а также при использовании Facelets этот тег является избыточным, поскольку теперь можно безопасно помещать стандартные HTML-теги в JSF-теги страницы.

<f:view>
    <f:verbatim><p></f:verbatim>
        Данный текст размещен внутри HTML-тегов "<p></p>"
    <f:verbatim></p></f:verbatim>
</f:view>

f:view

Родительский тег для всех стандартных и пользовательских тегов JSF.

<f:view>
    <h:outputText
        escape="true"
        value="Все JSF компоненты размещаются 
               только внутри тега f:view" />
</f:view>

f:viewParam

Этот тег используется для установления связи параметра HTTP-запроса GET со свойством управляемого бина. Значение атрибута name должно соответствовать наименованию параметра, а значение value определяется выражением, соответствующим значению управляемого компонента JavaBean.

<f:metadata>
    <f:viewParam name="someName"
                 value="#{bean.property}" />
</f:metadata>

HTML-компоненты JSF

HTML-компоненты отвечают за рендеринг разметки результирующей WEB страницы.

h:body

Определение тела страницы. Стандартный html-тег body

<h:body bgcolor="white">
  <h3>JSF 2.0 Hello World Example</h3>
  <h4>Welcome </h4>
</h:body>

h:button

Подобен тегу h:commandButton. Нажатие на кнопку генерируют HTTP-запрос GET.

h:column

Тег h:column вкладывается в тег h:dataTable и определяет столбец в таблице.

<h:form>
    <h:inputText label="Name" value="#{user.name}" />
    <h:commandButton action="Save" value="Click and Save" />
</h:form>

h:commandButton

Отображение на странице HTML кнопки (submit).

<h:form>
    <h:inputText label="Name" value="#{user.name}" />
    <h:commandButton action="save" value="Save" />
</h:form>

h:commandLink

Отображение на странице HTML ссылки, которая отправляет серверу форму, определенную тегом h:form

<h:form>
    <h:inputText label="Name" value="#{user.name}" />
    <h:commandLink action="save" value="Save" />
</h:form>

h:dataTable

Динамическое формирование таблицы на основе коллекции данных, которая определяется атрибутом value.

<h:dataTable value="#{Order.items}" var="item">
    <h:column>
        <f:facet name="header">
            <h:outputText value="Number" />
        </f:facet>
        <h:outputText value="#{item.itemNumber}" />
    </h:column>
    <h:column>
        <f:facet name="header">
            <h:outputText value="Description" />
        </f:facet>
        <h:outputText value="#{item.itemDescription}" />
    </h:column>
</h:dataTable>

h:form

Создание HTML-формы на странице.

<h:form>
    <h:inputText value="#{helloBean.name}"</h:inputText>
    <h:commandButton value="Welcome Me" action="welcome"></h:commandButton>
</h:form>

h:graphicImage

Размещение на странице изображения.

<h:graphicImage value="http://www.java2s.com/jsf.png"/>

<!-- is rendered into the following HTML tag. -->

<img src="http://www.java2s.com/jsf.png" />

h:head

Определение стандартного HTML-тега head.

<h:head>
  <title>JSF 2.0 Hello World</title>
</h:head>

h:inputHidden

Размещение скрытого поля на странице HTML.

<h:inputHidden value="Hello World" id="hiddenField" />

<!-- is rendered into the following HTML tag. -->

<input id="jsfForm:hiddenField" type="hidden" 
	   name="jsfForm:hiddenField" 
       value="Hello World" />

h:inputSecret

Поле ввода input типа password для определения пароля.

<h:inputSecret value="password" />

<!-- is rendered into -->

<input type="password" value="password" />

h:inputText

Поле ввода текстовой строки input.

<h:inputText id="loginField" value="#{user.login}" />

h:inputTextarea

Поле ввода текста textarea.

<h:inputTextarea rows="10" cols="10" value="Hello World!" readonly="true"/>

<!-- is rendered into -->

<textarea readonly="readonly"> Hello World!</textarea>

h:link

h:link подобен тегу h:commandLink. Ссылка тега вызывает HTTP-запрос GET при переходе к целевой странице.

<h:link value="Page 1" outcome="wellcome" />

<!-- is rendered into the following HTML code -->

<a href="wellcome.xhtml">Page 1</a>

h:message

Отображение сообщения для компонента, который имеет атрибут id для определения идентификатора. Тег использует идентификатор компонента в качестве атрибута for.

<table>
  <tr><td><h:inputText id="loginField"
                       value="#{user.login}"
                       required="true" /></td>
      <td><h:message style="color:red"
                     for="loginField" /></td></tr>
</table>

h:messages

Тег h:messages выводит сообщения с использованием HTML компонента <ul>

<h:messages style="color:red;margin:8px;" />

<!-- Если пользователь введет в поле UserName больше чем 16 символов и
и в поле Password больше чем 8 символов -->

<ul style="color:red;margin:8px;">
   <li>UserName: Validation Error: 
   Length is greater than allowable maximum of '16' </li>
   <li>Password: Validation Error: 
   Length is less than allowable minimum of '6' </li>
</ul>

h:outputFormat

Представление параметризованного текста с атрибутом value. Тег напоминает использование MessageFormat. В тексте атрибута value целочисленные значения, обрамленные фигурными скобками, заменяются на значения параметров, определенное в дочернем элементе f:param.

<h:outputFormat value="Hello, {0}!">
    <f:param value="#{user.nickName}" />
</h:outputFormat>

h:outputLabel

Представление метки "label" на странице. Стиль представления можно определить при помощи атрибутов style или styleClass. Компонент метки связан с другим компонентом посредством определения тега "for".

<h:outputLabel for="username"
               value="#{messages.labelUserName} " />
<h:inputText id="username" value="#{beanUser.userName}" />

h:outputLink

Представление HTML-ссылки в виде anchor-элемента.

<h:outputLink value="http://yandex.ru">
    <h:outputText value="Поисковый сайт Yandex" />
</h:outputLink>

<!-- is rendered into the following HTML tag.  -->

<a href="http://yandex.ru">Поисковый сайт Yandex</a>

h:outputScript

Загрузка файла с JavaScript'ами. По умолчанию файл рамещается в одной из поддиректорий resources.

<!-- Загрузка файла help.js из директории resources/js/ --->

<h:outputScript library="js" name="help.js" />

h:outputStylesheet

Загрузка файла со стилями CSS. По умолчанию файл рамещается в одной из поддиректорий resources.

<!-- Загрузка файла styles.css из директории resources/css/ --->

<h:outputStylesheet library="css" name="styles.css"  />

h:outputText

Тег представляет на странице HTML элемент span со значением атрибута value, если в теге определены атрибуты style или styleClass. В противном случае значение, определенное атрибутом тега value, отображается так, чтобы можно было игнорировать символы XML/HTML. При значении атрибута escape равным false символы XML/HTML не игнорируются.

<h:outputText value="<h1>Киса Воробьянинов</h1>" escape="false"/>
<h:outputText value="#{user.login}" />

h:panelGrid

Представление информации на странице HTML в табличном виде. Число столбцов в таблице определяется значением атрибута тега columns. Стиль представления информации в колонках таблицы определяется значением атрибута columnClasses для каждой колонки.

<h:panelGrid columns="2" columnClasses="rightAlign, leftAlign">
    <h:outputText value="Пользователь" />
    <h:inputText value="#{user.name}" required="true" >
           <f:validateLength minimum="3" maximum="32" />
    </h:inputText>
    <h:outputText value="Логин" />
    <h:inputText value="#{user.login}"required="true" >
         <f:validateLength minimum="4" maximum="8" />
    </h:inputText>
</h:panelGrid>

h:panelGroup

Тег используется для группировки дочерних компонентов в единую область представления. Значением атрибута rendered можно управлять представлением компонентов тега h:panelGroup. Если значение атрибута false, то компоненты на странице не отображаются.

<h:panelGroup rendered="#{beanUser.user != null}">
    <h:inputText label="#{messages.labelUserName}" id="username"
                 value="#{beanUser.user.username}" required="true" />
    <h:message for="username" errorClass="error" />
</h:panelGroup>

h:selectOneRadio

Представление связанных переключателей типа radio. Подобно тегу selectManyCheckbox поддерживает вертикальную или горизонтальную схему представления дочерних компонентов selectItem. Для этого необходимо использовать атрибут layout, определяющий значения : lineDirection (горизонтальное) или pageDirection (вертикальное).

<h:selectOneRadio id="subscriptions" layout="pageDirection"
                  value="#{subscriptionController.subscriptions}">
    <f:selectItem id="item1" itemLabel="Новости" itemValue="1" />
    <f:selectItem id="item2" itemLabel="Спорт" itemValue="2" />
    <f:selectItem id="item3" itemLabel="Музыка" itemValue="3" />
    <f:selectItem id="item4" itemLabel="Интернет" itemValue="4" />
</h:selectOneRadio>

h:selectBooleanCheckbox

Представление поля ввода типа "checkbox". Значение атрибута value тега связывается c булевым свойством в компоненте JavaBean.

<h:selectBooleanCheckbox value="user.newsLetters" />
<h:outputText value="Регулярное получение новостей" />

h:selectManyCheckbox

Представление связанных флажков. Атрибут layout определяет горизонтальное (lineDirection) или вертикальное (pageDirection) размещение компонентов.

<h:selectManyCheckbox id="subscriptions" layout="pageDirection"
                     value="#{subscriptionController.subscriptions}">
    <f:selectItem id="item1" itemLabel="Новости" itemValue="1" />
    <f:selectItem id="item2" itemLabel="Спорт" itemValue="2" />
    <f:selectItem id="item3" itemLabel="Музыка" itemValue="3" />
</h:selectManyCheckbox>

h:selectManyListbox

Представление поля выбора "select", допускающего множественный выбор. Число элементов, одновременно выводимое на экран, устанавливается атрибутом тега size.

<h:selectManyListbox id="subscriptions" value="#{news.items}">
    <f:selectItems value="#{news.allItems}" />
</h:selectManyListbox>

h:selectManyMenu

Представление поля выбора "select", допускающего множественный выбор. Тег идентичен h:selectManyListBox за исключением того, что он всегда выводит на экран один элемент за один раз. Поэтому у него нет атрибут size.

<h:selectManyMenu id="order" value="#{order.items}">
    <f:selectItems value="#{orderBean.allItems}" />
</h:selectManyMenu>

h:selectOneListbox

Представление поля выбора "select", не допускающего множественный выбор. Значение необязательного атрибута тега "size" определяет количество элементов, отображаемое на странице одновременно. Если атрибут size не используется, то выводятся все элементы.

<h:selectOneListbox value="#{order.items}">
    <f:selectItems value="#{orderBean.allItems}" />
</h:selectOneListbox>

h:selectOneMenu

Представление "выпадающего списка меню", предназначенное для отображения поля "select", не допускающего множественного выбора. Только один элемент можно выбрать. Значения для выбора определяются в дочернем теге f:selectItem или f:selectItems.

<h:selectOneMenu id="subscriptions" value="#{subscriptionController.subscriptions}">
    <f:selectItem id="item1" itemLabel="Новости" itemValue="1" />
    <f:selectItem id="item2" itemLabel="Спорт" itemValue="2" />
    <f:selectItem id="item3" itemLabel="Музыка" itemValue="3" />
    <f:selectItem id="item4" itemLabel="Интернет" itemValue="4" />
</h:selectOneMenu>