DataTable (<b:dataTable />) since 0.8.0breaking changes in 0.9.0

The <b:dataTable > is a convenient component rendering the table mostly on the client. This, in turn, imposes certain limitations over server-side datatables. For instance, user interactions don't use AJAX to redraw the table, so you can't easily implement lazy loading. On the plus side is the speed of the data table. Only very large tables may suffer from long initial load times. Once the table is loaded, it's completely available on the client, which makes filtering and pagination very fast.

The BootsFaces data table is based on the jQuery plugin DataTables.net, which has been published under a MIT licence. Most settings BootsFaces offers translate more or less directly into JavaScript options. So chances are you find a more detailed description of the attributes of the data table at their web site. The data table object is stored in a JavaScript variable (the widgetVar). If you don't specify a widgetVar, BootsFaces generates a variable based on the id of the <b:dataTable >. Following the tradition of Angular and other popular JS frameworks, the kebab-case of the id translates to a camelCase widgetVar.

Basic usage

Getting started with the BootsFaces datatable is pretty easy. Basically, it support the same syntax as its standard JSF counterpart <h:dataTable />, but is also supports a more compact syntax. The simplest way to define a column is to simply use the value attribute. If you don't set a header, it's automatically derived from the variable name of the value.

Live preview

BrandTypeColorYearPriceEngine Power (hp)
FiatPuntowhite20076838126
RenaultMeganewhite20035436144
FiatPuntowhite20163923988
CitroenPicassoblack19973611105
FiatPuntoyellow2007715066
OpelAstrablack198311160139
FiatPuntogreen19808481135
CitroenPicassosilver201113651112
CitroenPicassowhite2007896860
VolvoV50green19931084290
SeatIbizablue198411086130
FiatPuntoblack200813704126
RenaultMeganeyellow20061072889
VWGolfgreen200810078135
VWGolfred20131501780

Buttons and row classes

There are a couple of pre-defined buttons to export the table as an Excel file, as a CSV file, as a PDF file, to copy it to the clipboard ot the print it.

You can also add CSS classes to the rows using the attribute row-style-class. This attribute may contain an EL expression. It may also contain a comma-separated list of CSS classes. In this case, the CSS classes are cyclically assigned to the rows. There's a caveat: if the client reorders the rows, the order of the `row-style-classes` is not updated. You can see the effect in the example below.

Live preview

BrandTypeColorYearPriceEngine Power (hp)
FiatPuntowhite20076838126
RenaultMeganewhite20035436144
FiatPuntowhite20163923988
CitroenPicassoblack19973611105
FiatPuntoyellow2007715066
OpelAstrablack198311160139
FiatPuntogreen19808481135
CitroenPicassosilver201113651112
CitroenPicassowhite2007896860
VolvoV50green19931084290
SeatIbizablue198411086130
FiatPuntoblack200813704126
RenaultMeganeyellow20061072889
VWGolfgreen200810078135
VWGolfred20131501780

Autocompletion: h:column vs. b:dataTableColumn

BootsFaces supports a couple of attributes lacking in standard JSF. If you want to benefit from autocompletion, or if you're using a strict IDE like NetBeans, you'll want to use <b:dataTableColumn />. We couldn't use <b:column /> because this widget is already used for the grid system. However, if you don't mind your IDE complaining, you can use <h:column /> and even <b:column /> with the extra attributes of BootsFaces.

Defining the content cells

You can either use the value attribute as seen above, or you can put arbitray JSF into the column. For instance, the example below shows how to put an input field into the column.

Live preview

  • Brand
  • Type
  • Color
  • Year
  • Price
  • Engine Power
Fiat
Punto
white
2007
€ 6838
93 KW (126 hp)
Renault
Megane
white
2003
€ 5436
106 KW (144 hp)
Fiat
Punto
white
2016
€ 39239
65 KW (88 hp)
Citroen
Picasso
black
1997
€ 3611
77 KW (105 hp)
Fiat
Punto
yellow
2007
€ 7150
49 KW (66 hp)
Opel
Astra
black
1983
€ 11160
102 KW (139 hp)
Fiat
Punto
green
1980
€ 8481
99 KW (135 hp)
Citroen
Picasso
silver
2011
€ 13651
82 KW (112 hp)
Citroen
Picasso
white
2007
€ 8968
44 KW (60 hp)
Volvo
V50
green
1993
€ 10842
66 KW (90 hp)
Seat
Ibiza
blue
1984
€ 11086
96 KW (130 hp)
Fiat
Punto
black
2008
€ 13704
93 KW (126 hp)
Renault
Megane
yellow
2006
€ 10728
65 KW (89 hp)
VW
Golf
green
2008
€ 10078
99 KW (135 hp)
VW
Golf
red
2013
€ 15017
59 KW (80 hp)

Defining the header

You can use either the attribute label of the column, or you can define a facet named "header" inside the column. The latter option gives you more flexibility, because you can put arbitrary JSF code in a header. The example above shows how it's done.

Note that the header is always embedded in a table header tag (i.e. in a <tr><th>code> tag). So you can not use attributes like colspan or rowspan. If you need that, you can define a header for the entire table. In this case, the column headers are not rendered. You have to make sure that the number of header columns matches the number of the columns of the data table. The example below shows how do to it:

Live preview

Car Appearance Technical Data
Color Year Price Power
Fiat Punto white20076838126
Renault Megane white20035436144
Fiat Punto white20163923988
Citroen Picasso black19973611105
Fiat Punto yellow2007715066
Opel Astra black198311160139
Fiat Punto green19808481135
Citroen Picasso silver201113651112
Citroen Picasso white2007896860
Volvo V50 green19931084290
Seat Ibiza blue198411086130
Fiat Punto black200813704126
Renault Megane yellow20061072889
VW Golf green200810078135
VW Golf red20131501780

Customizing the table

The datatable has a couple of options to configure it. Some of them are shown in the example below.

Live preview

BrandTypeColorAge
Fiatwhite125 months
Renaultwhite173 months
Fiatwhite17 months
Citroenblack245 months
Fiatyellow125 months
Opelblack413 months
Fiatgreen449 months
Citroensilver77 months
Citroenwhite125 months
Volvogreen293 months
Seatblue401 months
Fiatblack113 months
Renaultyellow137 months
VWgreen113 months
VWred53 months


Note that the search has an interesting twist: it's a full-text search allowing to search for the construction year, also this column isn't shown.

Sorting input fields

By default, the data table only sorts plain text. If you want to sort input field, checkboxes or comboboxes, you have to tell the column which the data type of the input field is:

You can see the effect in the example above.

Fine-tuning search and sort order

Sometimes specifying the data type isn't enough. For instance, in the table above, the age is a string, consisting of a numeric value and a fixed string. Another example is the time shown in the commit history of GitHub: it displays not the real date, but user-friendly texts like "just now", "5 minutes ago" or "last month". In such as case, you can specify a second, hidden, field indicating the order of the rows. In the table above, that's the year when the car was constructed. In the GitHub commit history, this would be the commit date. You specify this hint in a /lt;b:dataTableColumn /> using the attribute data-order:

A similar challenge sometimes occurs with search. The table above allows you to search both for the visible age in months and for the (invisible) construction date. Another interesting use case might be to allow search for both American and your local date format. In both cases, you provide a data-search attribute and populate it with both texts:

Setting the initial search filter

You can set an initial search filter by adding the attribute search-value to the <dataTableColumn />.

Note that the example above maps an empty filter to a null value. We chose to do so in order to be able to demonstrate the effect of save-state:

Updating a datatable with AJAX

If you want to update a datatable by an AJAX request, you must destroy the datatable before sending the AJAX request. You can do this using the widget variable. Currently (BootsFaces 1.0), there's no attribute widgetVar yet, so you best find out the name of the widget var using the developer tools of the browser. Basically, the name of the widget variable is the id of the datatable without the colons, plus the suffix Widget. For instance, the id of the datatable below is i18n:bcarPool2, so the code to call an AJAX request looks like so:

Internationalization

This example below shows how to use the i18n support of <b:dataTable >. For i18n there are three ways:

Custom options

The JavaScript dataTable widgets has quite a few options. It's almost impossible to cover them all by a JSF component (see https://datatables.net/reference/option/). Therefore, you can pass custom-options to both the dataTable and to each column. These options are added to the Json object used to initialize the datatable.

Note that this feature may lead to incompatibilities in future versions of BoofsFaces. In particular, if your custom option is added to the <b:dataTable /> component, it may be added twice.

Live preview


BrandTypeColorYearBrandTypeColorYear
FiatPuntowhite2007FiatPuntowhite2007
RenaultMeganewhite2003RenaultMeganewhite2003
FiatPuntowhite2016FiatPuntowhite2016
CitroenPicassoblack1997CitroenPicassoblack1997
FiatPuntoyellow2007FiatPuntoyellow2007
OpelAstrablack1983OpelAstrablack1983
FiatPuntogreen1980FiatPuntogreen1980
CitroenPicassosilver2011CitroenPicassosilver2011
CitroenPicassowhite2007CitroenPicassowhite2007
VolvoV50green1993VolvoV50green1993
SeatIbizablue1984SeatIbizablue1984
FiatPuntoblack2008FiatPuntoblack2008
RenaultMeganeyellow2006RenaultMeganeyellow2006
VWGolfgreen2008VWGolfgreen2008
VWGolfred2013VWGolfred2013

Unified AJAX and JavaScript API

The datatable offers a couple of JavaScript and jQuery events you can use to call your own JavaScript or even your own bean method on the backend. Currently, the BootsFaces datatable offers only a subset of the events of the underlying JavaScript widget (see https://datatables.net/reference/event).

Note that the standard JavaScript callbacks like onclick and ondblclick are also there, but they don't distinguish between the rows and columns. To know which row and/or column has been clicked, either use the jQuery callbacks onselect and ondeselect or add onclick listeners to the individual columns.

Live preview

BrandTypeColorYearPriceEngine Power (hp)
FiatPuntowhite20076838126
RenaultMeganewhite20035436144
FiatPuntowhite20163923988
CitroenPicassoblack19973611105
FiatPuntoyellow2007715066
OpelAstrablack198311160139
FiatPuntogreen19808481135
CitroenPicassosilver201113651112
CitroenPicassowhite2007896860
VolvoV50green19931084290
SeatIbizablue198411086130
FiatPuntoblack200813704126
RenaultMeganeyellow20061072889
VWGolfgreen200810078135
VWGolfred20131501780

As the example above shows, onselect usually tells you which rows have been added. However, if the users selects an entire range using SHIFT+click, the parameter indexes also contains rows that were already selected. Hence, you have to be careful not to add rows twice. In our example, we added an if statement to make the problem explicit. In general, you could replace the ArrayList by a Set.

If the user adds a single row, the parameter matching the loop variable (i.e. car in our example) contains the selected object.

If the user adds multiple rows in a single AJAX request, the parameter matching the loop variable is null. In this case the parameter indexes tells you which rows have been selected. indexes is a comma-separated list of integers, each indicating the index of the selected row. The index always corresponds to the array index of the array in the Java bean. If the users filters or re-orders the table, the row number may be different from the array index. However, the API has been designed in such a way that you won't notice this.

Each of the three parameters of the Java bean method is optional. You can omit one or several of them in the onclick listener. For instance, onclick="ajax:onSelect(car)" calls the Java method onSelect(Car car), and onclick="ajax:onSelect(indexes)" calles the Java method onSelect(String indexes).

Responsiveness

Like most BootsFaces components, the datatable supports the responsive attributes like col-*, visible and hidden. If you want to update the datatable by an AJAX request, you should wrap it in a b:column nonetheless. For technical reasons, the id does not belong to the div bearing the CSS style classes for responsiveness. Instead, it belong to the table. So updating the table by its id means it's wrapped into another div each time it's updated by an AJAX request.

If there's not enough screen estate to display the table, the last couple of columns are hidden, as you can see in this example:

Live preview

BrandTypeColorYearPrice
FiatPuntowhite20076838
RenaultMeganewhite20035436
FiatPuntowhite201639239
CitroenPicassoblack19973611
FiatPuntoyellow20077150
OpelAstrablack198311160
FiatPuntogreen19808481
CitroenPicassosilver201113651
CitroenPicassowhite20078968
VolvoV50green199310842
SeatIbizablue198411086
FiatPuntoblack200813704
RenaultMeganeyellow200610728
VWGolfgreen200810078
VWGolfred201315017

Empty data table:

Live preview

BrandTypeColorYear

Inputfields, command buttons and AJAX since 1.0

The BootsFaces datatable also supports input fields, buttons and AJAX calls.

The next demo shows how to switch a cell between text-only and editable mode on a button click. Some users observed that this feature may modify the sort order (i.e. the editable row becomes the first row of the table, although it shouldn't be there according to the sort order). For instance, this happens if every cell in a row is made editable. In this case you can enforce the correct sort order by adding the attribute data-order, as described above.

Live preview

BrandTypeColorYearPriceColumn #5Column #6
FiatPuntowhite20076838
RenaultMeganewhite20035436
FiatPuntowhite201639239
CitroenPicassoblack19973611
FiatPuntoyellow20077150
OpelAstrablack198311160
FiatPuntogreen19808481
CitroenPicassosilver201113651
CitroenPicassowhite20078968
VolvoV50green199310842
SeatIbizablue198411086
FiatPuntoblack200813704
RenaultMeganeyellow200610728
VWGolfgreen200810078
VWGolfred201315017

Reference section

Attribute Default value Description
ajax false Activates AJAX. The default value is false (no AJAX).
border true If set, this will surround the table by a border. Defaults to true.
col-lg
colLg (alternative writing)
-1 Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-md
colMd (alternative writing)
-1 Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-sm
colSm (alternative writing)
-1 Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-xs
colXs (alternative writing)
-1 Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
columnVisibility false Adds a button allowing the user to show and hide of the columns.
content-disabled
contentDisabled (alternative writing)
false Enables or disables every child element of this container. By default, child elements are enabled.
copy false Adds a 'copy to clipboard' button.
csv false Adds a 'export CSV file' button.
custom-lang-url
customLangUrl (alternative writing)
(none) Defines a custom lang file url for languages BootsFaces doesn't support out-of-the-box.
custom-options
customOptions (alternative writing)
(none) Allows you to pass an arbitrary option to the datatable widget. Separate the options by a comma if you pass more than one. Note that this may cause incompatibilities when the next version of BootsFaces is released. Use at own risk.
disabled false Boolean value to specify if the button is disabled.
display block If you use the "visible" attribute, the value of this attribute is added. Legal values: block, inline, inline-block. Default: block.
excel false Adds a 'export Excel file' button.
fixed-header
fixedHeader (alternative writing)
false Activates the fixed header plugin of the dataTable.
hidden (none) This column is hidden on a certain screen size and below. Legal values: lg, md, sm, xs.
id (none) Unique identifier of the component in a namingContainer.
immediate false Flag indicating that, if this component is activated by the user, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase. Default is false.
info true If set, this will enable the information about record count. Defaults to true.
lang (none) Configured lang for the dataTable. If no default language is configured, the language configured in the browser is used.
large-screen
largeScreen (alternative writing)
-1 Alternative spelling to col-lg. Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
medium-screen
mediumScreen (alternative writing)
-1 Alternative spelling to col-md. Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
multi-column-search
multiColumnSearch (alternative writing)
false If true, <b:inputText /> fields will be generated at the bottom of each column which allow you to perform per-column filtering.
multi-column-search-position
multiColumnSearchPosition (alternative writing)
bottom Should the multi-column-search attributes be at the bottom or the top of the table? Legal values: 'top','botton', and 'both'. Default to 'bottom'.
offset (none) Integer value to specify how many columns to offset.
offset-lg
offsetLg (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-md
offsetMd (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-sm
offsetSm (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-xs
offsetXs (alternative writing)
(none) Integer value to specify how many columns to offset.
onclick (none) The onclick attribute.
oncomplete (none) JavaScript to be executed when ajax completes with success.
ondblclick (none) Client side callback to execute when input element is double clicked.
ondeselect (none) Client side and/or AJAX callback to execute when a row is deselected.
onmousedown (none) Client side callback to execute when a pointer input element is pressed down over input element.
onmousemove (none) Client side callback to execute when a pointer input element is moved within input element.
onmouseout (none) Client side callback to execute when a pointer input element is moved away from input element.
onmouseover (none) Client side callback to execute when a pointer input element is moved onto input element.
onmouseup (none) Client side callback to execute when a pointer input element is released over input element.
onorder (none) Client side and/or AJAX callback to execute when the table is sorted.
onpage (none) Client side and/or AJAX callback to execute when the current table page changes.
onsearch (none) Client side and/or AJAX callback to execute when the user starts a search.
onselect (none) Client side and/or AJAX callback to execute when a row is selected.
page-length
pageLength (alternative writing)
10 Sets the default page length for paginated dataTable. The default value is 10.
page-length-menu
pageLengthMenu (alternative writing)
[ 10, 25, 50, 100 ] Sets the default page length for paginated dataTable. The default value is [10, 25, 50, 100]. The brackets are optional. Read https://www.datatables.net/examples/advanced_init/length_menu.html for details.
paginated true Activates the pagination of the dataTable. Default value is 'true'.
pdf false Adds a 'export PDF file' button.
print false Adds a 'print' button.
process (none) Comma or space separated list of ids or search expressions denoting which values are to be sent to the server.
rendered false Boolean value to specify the rendering of the component, when set to false the component will not be rendered.
responsive false Activates the responsive plugin of the dataTable
row-highlight
rowHighlight (alternative writing)
true Enable the row highlight css. Default: true.
row-style-class
rowStyleClass (alternative writing)
(none) Optional CSS class for each row. If it's an EL expression, it's evaluated for each row. You can also provide a comma-separated list. In this case, the CSS classes are assigned cyclically to the row.
save-state
saveState (alternative writing)
true Stores the state of the datatable on the client, so that after a page reload the same filters are active, the same page is shown etc.
scroll-collapse
scrollCollapse (alternative writing)
true If set, this will have the container match the height of the rows shown in the table if that height is smaller than that given height by the scroll-size. Default: true.
scroll-horizontally
scrollHorizontally (alternative writing)
false Adds a horizontal scroll bar on small screens. Similar to scroll-x, but wraps the entire table within the scroll area. Defaults to false.
scroll-size
scrollSize (alternative writing)
(none) If set, force the height of table to the size specified. You can optionally to add the unit (e.g. scroll-size="200px"). By default, it's px.
scroll-x
scrollX (alternative writing)
false If set, the table can scroll horizontally. Similar to scroll-x, but uses a different approach, so the page selector, the search are not scrolled with the table. Defaults to false.
searching true If set to false, this feature completely disables the search functionality of the datatable (i.e. both the UI and the JavaScript API).
select false Allows the user to select rows. Defaults to false.
selectionMode multiple Set this property to "single" if you want to prevent multiple selections. Default is "multiple".
small-screen
smallScreen (alternative writing)
-1 Alternative spelling to col-sm. Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
span (none) Integer value to specify how many columns to span on medium screens (≥992 pixels). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
striped true If set, this will show the row in alternating background colors (typically shades of gray). Defaults to true.
style (none) Inline style of the input element.
style-class
styleClass (alternative writing)
(none) Style class of this element.
tiny-screen
tinyScreen (alternative writing)
-1 Alternative spelling to col-xs. Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
tooltip (none) The text of the tooltip.
tooltip-container
tooltipContainer (alternative writing)
body Where is the tooltip div generated? That's primarily a technical value that can be used to fix rendering errors in special cases. Also see data-container in the documentation of Bootstrap. The default value is body.
tooltip-delay
tooltipDelay (alternative writing)
0 The tooltip is shown and hidden with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-delay-hide
tooltipDelayHide (alternative writing)
0 The tooltip is hidden with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-delay-show
tooltipDelayShow (alternative writing)
0 The tooltip is shown with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-position
tooltipPosition (alternative writing)
(none) Where is the tooltip to be displayed? Possible values: "top", "bottom", "right", "left", "auto", "auto top", "auto bottom", "auto right" and "auto left". Default to "bottom".
update (none) Component(s) to be updated with ajax.
value (none) EL expression referring to the back-end bean attribute providing the value of the field.
var (none) The var attribute sets the name of a request-scope attribute exposing the data for each iteration over the rows in the underlying data model for this table.
visible (none) This column is shown on a certain screen size and above. Legal values: lg, md, sm, xs.
widgetVar (none) optional widget variable to access the datatable widget in JavaScript code.
Attribute Default value Description
content-style
contentStyle (alternative writing)
(none) Inline style of the cells in the content area.
content-style-class
contentStyleClass (alternative writing)
(none) Style class of cells in the content area..
custom-options
customOptions (alternative writing)
(none) Allows you to pass an arbitrary option to the datatable widget. Separate the options by a comma if you pass more than one. Note that this may cause incompatibilities when the next version of BootsFaces is released. Use at own risk.
data-order
dataOrder (alternative writing)
(none) Allows you to specify a value for ordering. Useful i.E. for ordering formatted values.
data-search
dataSearch (alternative writing)
(none) Allows you to specify a value for searching. The search doesn't consider the real content of this column. Instead, it considers the value of the data-search attribute. Useful i.E. for searching formatted values.
data-type
dataType (alternative writing)
(none) Specifies order-by more precisely. Is also used by the filtering methods. Legal values are 'string', 'date', 'numeric'.
footer-style
footerStyle (alternative writing)
(none) Inline style of the footer cell.
footer-style-class
footerStyleClass (alternative writing)
(none) Style class of this footer cell.
header-style
headerStyle (alternative writing)
(none) Inline style of the header cell.
header-style-class
headerStyleClass (alternative writing)
(none) Style class of this header cell.
label (none) Label in the header of the colum.
label-style
labelStyle (alternative writing)
(none) The CSS inline style of the label.
label-style-class
labelStyleClass (alternative writing)
(none) The CSS class of the label.
order (none) Is the table to be sorted by this column? Legal values are 'asc' and 'desc'.
order-by
orderBy (alternative writing)
(none) Allows you to sort input field. Legal values are dom-text, dom-text-numeric, dom-select and dom-checkbox.
orderable true Disables or enables the sort button for this column.
search-value
searchValue (alternative writing)
(none) Initial content of the search filter field.
searchable true If set to false, this column is excluded from the multi-column-search feature of b:dataTable. Defaults to true. Note that this feature is active only if both searching='true' and multi-column-search='true' are set on the datatable.
style (none) Inline style of the input element.
style-class
styleClass (alternative writing)
(none) Style class of this element.
value (none) EL expression referring to the back-end bean attribute providing the value of the field.