111
PrimeFaces User Guide
Name
Default
Description
value
null
Object
Value of the component than can be either an EL
expression of a literal text.
converter
null
Converter
/String
An el expression or a literal text that defines a
converter for the component. When it’s an EL
expression, it’s resolved to a converter instance. In
case it’s a static text, it must refer to a converter id.
immediate
false
Boolean
When set true, process validations logic is executed
at apply request values phase for this component.
required
false
Boolean
Marks component as required.
validator
null
MethodExpr
A method expression that refers to a method
validationg the input.
valueChangeListener null
MethodExpr
A method expression that refers to a method for
handling a valuchangeevent.
requiredMessage
null
String
Message to be displayed when required field
validation fails.
converterMessage
null
String
Message to be displayed when conversion fails.
validatorMessage
null
String
Message to be displayed when validation fails.
widgetVar
null
String
Name of the client side widget.
update
null
String
Component(s) to update after fileupload completes.
process
null
String
Component(s) to process in fileupload request.
fileUploadListener
null
MethodExpr
Method to invoke when a file is uploaded.
multiple
false
Boolean
Allows choosing of multi file uploads from native
file browse dialog
auto
false
Boolean
When set to true, selecting a file starts the upload
process implicitly.
label
Choose
String
Label of the browse button.
allowTypes
null
String
Regular expression for accepted file types,
e.g. /(\.|\/)(gif|jpe?g|png)$/
sizeLimit
null
Integer
Individual file size limit in bytes.
fileLimit
null
Integer
Maximum number of files allowed to upload.
style
null
String
Inline style of the component.
styleClass
null
String
Style class of the component.
mode
advanced String
Mode of the fileupload, can be simple or advanced.
uploadLabel
Upload
String
Label of the upload button.
cancelLabel
Cancel
String
Label of the cancel button.
211
73
PrimeFaces User Guide
Name
Default
Description
invalidSizeMessage
null
String
Message to display when size limit exceeds.
invalidFileMessage
null
String
Message to display when file is not accepted.
fileLimitMessage
null
String
Message to display when file limit exceeds.
dragDropSupport
true
Boolean
Specifies dragdrop based file selection from
filesystem, default is true and works only on
supported browsers.
onstart
null
String
Client side callback to execute when upload begins.
onerror
null
String
Callback to execute if fileupload request fails.
oncomplete
null
String
Client side callback to execute when upload ends.
disabled
false
Boolean
Disables component when set true.
messageTemplate
{name}
{size}
String
Message template to use when displaying file
validation errors.
previewWidth
80
Integer
Width for image previews in pixels.
skinSimple
false
Boolean
Applies theming to simple uploader.
accept
null
String
Filters files in native file browser dialog.
Getting started with FileUpload
FileUpload engine on the server side can either be servlet 3.0 or commons fileupload. PrimeFaces
selects the most appropriate uploader engine by detection and it is possible to force one or the other
usign an optional configuration param.
<context-param>
<param-name>primefaces.UPLOADER</param-name>
<param-value>auto|native|commons</param-value>
</context-param>
auto: This is the default mode and PrimeFaces tries to detect the best method by checking the
runtime environment, if JSF runtime is at least 2.2 native uploader is selected, otherwise commons.
native: Native mode uses servlet 3.x Part API to upload the files and if JSF runtime is less than 2.2
and exception is being thrown.
commons: This option chooses commons fileupload regardless of the environment, advantage of
this option is that it works even on a Servlet 2.5 environment.
If you have decided to choose commons fileupload, it requires the following filter configration in
your web deployment descriptior.
212
38
PrimeFaces User Guide
<filter>
<filter-name>PrimeFaces FileUpload Filter</filter-name>
<filter-class>
org.primefaces.webapp.filter.FileUploadFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>PrimeFaces FileUpload Filter</filter-name>
<servlet-name>Faces Servlet</servlet-name>
</filter-mapping>
Note that the servlet-name should match the configured name of the JSF servlet which is Faces
Servlet in this case. Alternatively you can do a configuration based on url-pattern as well.
Simple File Upload
Simple file upload mode works in legacy mode with a file input whose value should be an
UploadedFile instance. Ajax uploads are not supported in simple upload.
<h:form enctype="multipart/form-data">
<p:fileUpload value="#{fileBean.file}" mode="simple" />
<p:commandButton value="Submit" ajax="false"/>
</h:form>
import org.primefaces.model.UploadedFile;
public class FileBean {
private UploadedFile file;
//getter-setter
}
Enable skinSimple option to style the simple uploader to have a themed look that works the same
across different environments.
Advanced File Upload
FileUploadListener is the way to access the uploaded files in this mode, when a file is uploaded
defined fileUploadListener is processed with a FileUploadEvent as the parameter.
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}" />
public class FileBean {
public void handleFileUpload(FileUploadEvent event) {
UploadedFile file = event.getFile();
//application code
}
}
213
32
PrimeFaces User Guide
Multiple Uploads
Multiple uploads can be enabled using the multiple attribute so that multiple files can be selected
from browser dialog. Multiple uploads are not supported in legacy browsers. Note that multiple
mode is for selection only, it does not send all files in one request. FileUpload component always
uses a new request for each file.
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}" multiple="true" />
Auto Upload
Default behavior requires users to trigger the upload process, you can change this way by setting
auto to true. Auto uploads are triggered as soon as files are selected from the dialog.
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}" auto="true" />
Partial Page Update
After the fileUpload process completes you can use the PrimeFaces PPR to update any component
on the page. FileUpload is equipped with the update attribute for this purpose. Following example
displays a "File Uploaded" message using the growl component after file upload.
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}" update="msg" />
<p:growl id="msg" />
public class FileBean {
public void handleFileUpload(FileUploadEvent event) {
//add facesmessage to display with growl
//application code
}
}
File Filters
Users can be restricted to only select the file types you’ve configured, example below demonstrates
how to accept images only.
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}"
allowTypes="/(\.|\/)(gif|jpe?g|png)$/"/>
Size Limit
Most of the time you might need to restrict the file upload size for a file, this is as simple as setting
the sizeLimit configuration. Following fileUpload limits the size to 1000 bytes for each file.
214
43
PrimeFaces User Guide
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}" sizeLimit="1000" />
File Limit
FileLimit restricts the number of maximum files that can be uploaded.
<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}" fileLimit="3" />
Validation Messages
invalidFileMessage, invalidSizeMessage and fileLimitMessage options are provided to display
validation messages to the users. Similar to the FacesMessage message API, these message define
the summary part, the detail part is retrieved from the messageTemplate option where default value
is “{name} {size}”.
Skinning
FileUpload resides in a container element which style and styleClass options apply. As skinning
style classes are global, see the main theming section for more information. Following is the list of
structural style classes
Class
Applies
.ui-fileupload
Main container element
.fileupload-buttonbar
Button bar.
.fileinput-button
Browse button.
.ui-fileupload start
Upload button.
.ui-fileupload cancel
Cancel button.
fileupload-content
Content container.
Browser Compatibility
Advanced uploader is implemented with HTML5 and provides far more features compared to single
version. For legacy browsers that do not support HMTL5 features like canvas or file api, fileupload
uses graceful degradation so that iframe is used for transport, detailed file information is not shown
and a gif animation is displayed instead of progress bar. It is suggested to offer simple uploader as a
fallback.
Filter Configuration
Filter configuration is required if you are using commons uploader only. Two configuration options
exist, threshold size and temporary file upload location.
Parameter Name
Description
thresholdSize
Maximum file size in bytes to keep uploaded files in memory. If a file
exceeds this limit, it’ll be temporarily written to disk.
215
25
PrimeFaces User Guide
Parameter Name
Description
uploadDirectory
Disk repository path to keep temporary files that exceeds the threshold size.
By default it is System.getProperty("java.io.tmpdir")
An example configuration below defined thresholdSize to be 50kb and uploads to users temporary
folder.
<filter>
<filter-name>PrimeFaces FileUpload Filter</filter-name>
<filter-class>
org.primefaces.webapp.filter.FileUploadFilter
</filter-class>
<init-param>
<param-name>thresholdSize</param-name>
<param-value>51200</param-value>
</init-param>
<init-param>
<param-name>uploadDirectory</param-name>
<param-value>/Users/primefaces/temp</param-value>
</init-param>
</filter>
Note that uploadDirectory is used internally, you always need to implement the logic to save the file
contents yourself in your backing bean.
216
58
PrimeFaces User Guide
3.45 Focus
Focus is a utility component that makes it easy to manage the element focus on a JSF page.
Info
Tag
focus
Component Class
org.primefaces.component.focus.Focus
Component Type
org.primefaces.component.Focus.FocusTag
Component Family
org.primefaces.component
Renderer Type
org.primefaces.component.FocusRenderer
Renderer Class
org.primefaces.component.focus.FocusRenderer
Attributes
Name
Default
Type
Description
id
null
String
Unique identifier of the component
rendered
true
boolean
Boolean value to specify the rendering of the
component, when set to false component will not
be rendered.
binding
null
Object
An el expression that maps to a server side
UIComponent instance in a backing bean
for
null
String
Specifies the exact component to set focus
context
null
String
The root component to start first input search.
minSeverity
error
String
Minimum severity level to be used when finding
the first invalid component
Getting started with Focus
By default focus will find the first enabled and visible input component on page and apply focus.
Input component can be any element such as input, textarea and select.
<p:focus />
<p:inputText ... />
<h:inputText ... />
<h:selectOneMenu ... />
Following is a simple example;
217
32
PrimeFaces User Guide
<h:form>
<p:panel id="panel" header="Register">
<p:focus />
<p:messages />
<h:panelGrid columns="3">
<h:outputLabel for="firstname" value="Firstname: *" />
<h:inputText id="firstname" value="#{pprBean.firstname}"
required="true" label="Firstname" />
<p:message for="firstname" />
<h:outputLabel for="surname" value="Surname: *" />
<h:inputText id="surname" value="#{pprBean.surname}"
required="true" label="Surname"/>
<p:message for="surname" />
</h:panelGrid>
<p:commandButton value="Submit" update="panel"
actionListener="#{pprBean.savePerson}" />
</p:panel>
</h:form>
When this page initially opens up, input text with id "firstname" will receive focus as it is the first
input component.
Validation Aware
Another useful feature of focus is that when validations fail, first invalid component will receive a
focus. So in previous example if firstname field is valid but surname field has no input, a validation
error will be raised for surname, in this case focus will be set on surname field implicitly. Note that
for this feature to work on ajax requests, you need to update p:focus component as well.
Explicit Focus
Additionally, using for attribute focus can be set explicitly on an input component which is useful
when using a dialog.
<p:focus for="text"/>
<h:inputText id="text" value="{bean.value}" />
218
46
PrimeFaces User Guide
3.46 Fragment
Fragment component is used to define automatically partially process and update sections whenever
ajax request is triggered by a descendant component.
Info
Tag
fragment
Component Class
org.primefaces.component.fragment.Fragment
Component Type
org.primefaces.component.Fragment
Component Family
org.primefaces.component
Renderer Type
org.primefaces.component.FragmentRenderer
Renderer Class
org.primefaces.component.fragment.FragmentRenderer
Attributes
Name
Default
Type
Description
id
null
String
Unique identifier of the component
rendered
true
Boolean
Boolean value to specify the rendering of the component, when
set to false component will not be rendered.
binding
null
Object
An el expression that maps to a server side UIComponent instance
in a backing bean
autoUpdate
false
Boolean
Updates the fragment automatically.
Getting started with Fragment
In the following case, required input field outside the fragment is ignored and only the contents of
the fragment are processed-updated automatically on button click since button is inside the
fragment. Fragment makes it easy to define partial ajax process and update without explicitly
defining component identifiers.
219
20
PrimeFaces User Guide
<h:form>
<h:panelGrid columns="2">
<p:outputLabel for="ign" value="Required:" />
<p:inputText id="ign" required="true" />
</h:panelGrid>
<p:fragment autoUpdate="true">
<h:panelGrid columns="4" cellpadding="5">
<h:outputLabel for="name" value="Name:" />
<p:inputText id="name" value="#{pprBean.firstname}" />
<p:commandButton value="Submit"/>
<h:outputText value="#{pprBean.firstname}" />
</h:panelGrid>
</p:fragment>
</h:form>
AutoUpdate has different notion compared to autoUpdate of message, growl and outputPanel. The
fragment is updated automatically after an ajax request if the source is a descendant. In other
mentioned components, there is no such restriction as they are updated for every ajax request
regardless of the source.
220
Documents you may be interested
Documents you may be interested
