Introduction

jXLS allows you to use predefined XML tags in your template to control XLS transformation behaviour.

jx:forEach Tag

Typical usage of <jx:forEach> tag is as follows

                <jx:forEach items="${departments}" var="department">
                    ${department.name} | ${department.chief}
                </jx:forEach>
            

jx tags can be nested into each other without any problems.

If you place opening and closing jx:forEach tags onto the same row jXLS will duplicate corresponding excel cells in this row by columns.

Currently if you need to duplicate excel rows with jx:forEach tag you have to place jx:forEach opening and closing tag into separate excel rows. All other cells in these rows are ignored.

See also Basic Tags sample

Grouping data with jx:forEach tag

jx:forEach tag allows you to perform grouping of collection data by one of the underlying bean properties. This can be done with groupBy and groupOrder attributes which specify which property should be used for grouping data and how groups should be ordered. For example

                    <jx:forEach items="${employees}" groupBy="age">
                    Age: ${group.item.age}
                    <jx:forEach items="${group.items}" var="employee">
                    ${employee.name} | ${employee.payment} | ${employee.bonus}
                    </jx:forEach>
                    </jx:forEach>
                

In this example we group employees by age. When encountered groupBy attribute jXLS performs grouping internally and places new bean named group into the context. This bean is rather simple - it contains two properties. The item property which is a bean from current processed group and the items property which represents the collection of all the beans from this group.

As you can see in this example we first displaying some information about current group age using

                    Age: ${group.item.age}
                

And after that we use inner <jx:forEach> tag to iterate and display all the group items

                    <jx:forEach items="${group.items}" var="employee">
                    ${employee.name} | ${employee.payment} | ${employee.bonus}
                    </jx:forEach>
                

By default if there is no groupOrder attribute group order will be preserved "as is" so that groups will be in the same order as they were found in the original items collection. If you need to sort groups in ascending or descending order you can set groupOrder attribute to asc or desc value accordingly.

In case of using groupBy attribute the var attribute of jx:forEach tag is ignored.

Filtering collection items

You can use 'select' attribute of jx:forEach tag to control which items get included in the loop. For example if we want to include only employees with payments more than 2000 we can use next syntax

                    <jx:forEach items="${employees}" var="employee" select="${employee.payment > 2000}">
                    ${employee.name} | ${employee.payment} | ${employee.bonus}
                    </jx:forEach>
                

varStatus attribute

jx:forEach tag support varStatus attribute which defines a name of loop status object which will be passed into bean context for each iteration. The loop status object is an instance of LoopStatus class which has single 'index' property identifying the index of the current item in the collection being iterated

                    <jx:forEach items="${employees}" var="employee" varStatus="status">
                    | ${status.index} | ${employee.name} | ${employee.payment} | ${employee.bonus}
                    </jx:forEach>
                

jx:if Tag

Typical usage of <jx:if> tag is as follows

                    <jx:if test="${department.chief.payment > 2000.0}">
                        Chief Name: ${department.chief.name}
                    </jx:if>
            

jx:if tag can be used to exclude some columns from export based on some condition. If you place opening and closing jx:if tag into the same row jXLS will process or remove columns contained in tag body depending on test condition.

jx:outline Tag

<jx:outline> tag allows you to group particular set of rows. For example having

                    <jx:outline>
                        //any rows can go here
                    </jx:outline>
            

All excel rows from the body of jx:group tag will be grouped.

<jx:outline> tag has one optional boolean attribute detail indicating initial state of grouped rows - should they be displayed expanded or collapsed. Default value is false meaning grouped rows will be collapsed (or hidden).

jx:out Tag

jx:out tag looks like this

                <jx:out expr="expression" />
            

This tag can be used anywhere that an expression would be used normally and simply takes a JEXL expression as an attribute value.

Getting more information

A big source of samples of jx tags usage can be found in jxls-core module unit tests. Take a look at various templates to see how they are built. If you are stuck do not hesitate to write on jXLS forum or send a message to jXLS mailing list.