org.apache.tapestry5.corelib.components.Grid.xdoc Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of tapestry-core Show documentation
Central module for Tapestry, containing interfaces to the Java Servlet API and all core services and components.
There is a newer version: 5.8.6

    
        
            
                
                    BeanEditForm
                
                
                    BeanDisplay
                
                
                    
                
            
        

        

            
                The Grid component is closely related to the BeanEditor component; they are both based on the same
                underlying concept and share quite a bit of code.
            

            In this example, we'll display a list of users. We'll also show some basic customization, to convert a
                column
                from just text, to a clickable link.
            

            
                
            

            This example shows much of the default behavior, using a collection of randomly generated users.
                The column order is determined by the order of the getter methods in the User class. The columns are
                sortable, and
                because there are more results than will fit on a single page, page navigation is included (the
                navigation
                disappears for small result sets).
            

            
                

                The @NonVisual annotation prevents the id property from being displayed.

            

            

                
                    We want to make the user's last name a clickable link to a detail page for the user.
                


                
    
        List Users

        
            
                ${user.lastname}
            
            
              There are no users to display; you can add some.
            
        
    

]]>

The block parameter name
propertycell

is used to override the rendering of cells for one property. As usual, case is ignored. Here we
use a PageLink component to link to a ViewUser page, passing the id of the user as
activation context for the target page.


The Grid component takes care of the <td> element, and the provided block parameter
provides the content
inside
the <td>.


For the block to know what is being rendered, we bind the row parameter of the Grid
to the user property of the page. The Grid will keep updating this property
just before it renders each row (using its own internal renderers, or the ones
provided as parameters).


The header for a column may be overridden in the same way, using a parameter name
of
propertyheader

. The parameter block will provide the content
inside the <th> element. The provided block is responsible for
providing any links or icons related to sorting.


Binding the Grid's empty parameter overrides the default message displayed when there
is no data to display. As demonstrated above, it doesn't have to be simple text, the
block can be a snippet of markup and components.



 getUsers() { return userDAO.findAll(); }
}]]>


The UserList class exists to provide access to the UserDAO service, and to act as a holder
for the user property, needed when the Grid is rendering. We need it here because we've
overridden the rendering of the lastName property.




Commonly, you may want to add a column to the Grid to support a computed property, or as a placeholder
for an action. We'll do the latter, adding a column for deleting a user.







List Users


${user.lastname}


Delete


There are no users to display; you can add some.




]]>

We now explicitly provide a column for the "delete" property, which doesn't exist. In addition, a
block
for the "delete" property has been added that includes an ActionLink
used to delete the user for the current row. This property is a
virtual
property because it doesn't correspond to a property
of the data object, User.



 getUsers() { return userDAO.findAll(); }
void onActionFromDelete(long userId)
{
userDAO.remove(userId);
}
}]]>

The only addition here is an event handler method for when the delete link is clicked.





The normal column title for the "delete" property would be "Delete". Using the
page's message catalog we can override that.





Tapestry does a lot of work to help you with the source parameter. The parameter type
is GridDataSource, but Tapestry has built-in coercions from
Object[] and List. In more complicated cases, such as very large
queries against a database, you will want to provide your own implementation
of GridDataSource, to minimimze the sizes of queries and result sets.


The Grid component is designed to be customized via CSS. As it renders <th>, <tr> and
<td> elements,
it generates CSS class attributes for each element. You can then add customized CSS rules, even
overriding the Tapestry defaults,
to present the Grid as desired. This is often used to set the width of a column to a fixed value.



propertyId

Added to <th> elements to allow customization of a particular column's header,
and added to <td> elements to allow customization of a particular column's data cells.

t-first
Added to the first <th> and the first <tr> of the <tbody> (the data portion of
the table).

t-last
Added to the last <th> and the last <tr>.
t-sort-column-ascending
Added to the <th> and all corresponding <td> elements for the column that is the
current sort column (if any,
for ascending sort).

t-sort-column-descending
As with t-soft-column-ascending, but for a descending sort.


The added CSS classes can get quite verbose; the Grid's lean parameter allows the propertyId CSS
class attribute value to be omitted. Even in lean mode, the other
CSS class attribute values are rendered.