001// Licensed under the Apache License, Version 2.0 (the "License"); 002// you may not use this file except in compliance with the License. 003// You may obtain a copy of the License at 004// 005// http://www.apache.org/licenses/LICENSE-2.0 006// 007// Unless required by applicable law or agreed to in writing, software 008// distributed under the License is distributed on an "AS IS" BASIS, 009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 010// See the License for the specific language governing permissions and 011// limitations under the License. 012 013package org.apache.tapestry5.corelib.components; 014 015import org.apache.tapestry5.*; 016import org.apache.tapestry5.annotations.*; 017import org.apache.tapestry5.beaneditor.BeanModel; 018import org.apache.tapestry5.beaneditor.PropertyModel; 019import org.apache.tapestry5.corelib.data.GridPagerPosition; 020import org.apache.tapestry5.grid.*; 021import org.apache.tapestry5.internal.TapestryInternalUtils; 022import org.apache.tapestry5.internal.beaneditor.BeanModelUtils; 023import org.apache.tapestry5.internal.bindings.AbstractBinding; 024import org.apache.tapestry5.ioc.annotations.Inject; 025import org.apache.tapestry5.ioc.internal.util.InternalUtils; 026import org.apache.tapestry5.services.BeanModelSource; 027import org.apache.tapestry5.services.ComponentDefaultProvider; 028import org.apache.tapestry5.services.ComponentEventResultProcessor; 029import org.apache.tapestry5.services.FormSupport; 030import org.apache.tapestry5.services.javascript.JavaScriptSupport; 031 032import java.io.IOException; 033import java.util.Collections; 034import java.util.List; 035 036/** 037 * A grid presents tabular data. It is a composite component, created in terms of several sub-components. The 038 * sub-components are statically wired to the Grid, as it provides access to the data and other models that they need. 039 * 040 * A Grid may operate inside a {@link org.apache.tapestry5.corelib.components.Form}. By overriding the cell renderers of 041 * properties, the default output-only behavior can be changed to produce a complex form with individual control for 042 * editing properties of each row. There is a big caveat here: if the order of rows provided by 043 * the {@link org.apache.tapestry5.grid.GridDataSource} changes between render and form submission, then there's the 044 * possibility that data will be applied to the wrong server-side objects. 045 * 046 * For this reason, when using Grid and Form together, you should generally 047 * provide the Grid with a {@link org.apache.tapestry5.ValueEncoder} (via the 048 * encoder parameter), or use an entity type for the "row" parameter for which 049 * Tapestry can provide a ValueEncoder automatically. This will allow Tapestry 050 * to use a unique ID for each row that doesn't change when rows are reordered. 051 * 052 * @tapestrydoc 053 * @see org.apache.tapestry5.beaneditor.BeanModel 054 * @see org.apache.tapestry5.services.BeanModelSource 055 * @see org.apache.tapestry5.grid.GridDataSource 056 * @see BeanEditForm 057 * @see BeanDisplay 058 * @see Loop 059 */ 060@SupportsInformalParameters 061public class Grid implements GridModel, ClientElement 062{ 063 /** 064 * The source of data for the Grid to display. This will usually be a List or array but can also be an explicit 065 * {@link GridDataSource}. For Lists and object arrays, a GridDataSource is created automatically as a wrapper 066 * around the underlying List. 067 */ 068 @Parameter(required = true, autoconnect = true) 069 private GridDataSource source; 070 071 /** 072 * A wrapper around the provided GridDataSource that caches access to the availableRows property. This is the source 073 * provided to sub-components. 074 */ 075 private GridDataSource cachingSource; 076 077 /** 078 * The number of rows of data displayed on each page. If there are more rows than will fit, the Grid will divide up 079 * the rows into "pages" and (normally) provide a pager to allow the user to navigate within the overall result 080 * set. 081 */ 082 @Parameter(BindingConstants.SYMBOL + ":" + ComponentParameterConstants.GRID_ROWS_PER_PAGE) 083 private int rowsPerPage; 084 085 /** 086 * Defines where the pager (used to navigate within the "pages" of results) should be displayed: "top", "bottom", 087 * "both" or "none". 088 */ 089 @Parameter(value = BindingConstants.SYMBOL + ":" + ComponentParameterConstants.GRID_PAGER_POSITION, 090 defaultPrefix = BindingConstants.LITERAL) 091 private GridPagerPosition pagerPosition; 092 093 /** 094 * Used to store the current object being rendered (for the current row). This is used when parameter blocks are 095 * provided to override the default cell renderer for a particular column ... the components within the block can 096 * use the property bound to the row parameter to know what they should render. 097 */ 098 @Parameter(principal = true) 099 private Object row; 100 101 /** 102 * Optional output parameter used to identify the index of the column being rendered. 103 */ 104 @Parameter 105 private int columnIndex; 106 107 /** 108 * The model used to identify the properties to be presented and the order of presentation. The model may be 109 * omitted, in which case a default model is generated from the first object in the data source (this implies that 110 * the objects provided by the source are uniform). The model may be explicitly specified to override the default 111 * behavior, say to reorder or rename columns or add additional columns. The add, include, 112 * exclude and reorder 113 * parameters are <em>only</em> applied to a default model, not an explicitly provided one. 114 */ 115 @Parameter 116 private BeanModel model; 117 118 /** 119 * The model parameter after modification due to the add, include, exclude and reorder parameters. 120 */ 121 private BeanModel dataModel; 122 123 /** 124 * The model used to handle sorting of the Grid. This is generally not specified, and the built-in model supports 125 * only single column sorting. The sort constraints (the column that is sorted, and ascending vs. descending) is 126 * stored as persistent fields of the Grid component. 127 */ 128 @Parameter 129 private GridSortModel sortModel; 130 131 /** 132 * A comma-separated list of property names to be added to the {@link org.apache.tapestry5.beaneditor.BeanModel}. 133 * Cells for added columns will be blank unless a cell override is provided. This parameter is only used 134 * when a default model is created automatically. 135 */ 136 @Parameter(defaultPrefix = BindingConstants.LITERAL) 137 private String add; 138 139 /** 140 * A comma-separated list of property names to be retained from the 141 * {@link org.apache.tapestry5.beaneditor.BeanModel}. 142 * Only these properties will be retained, and the properties will also be reordered. The names are 143 * case-insensitive. This parameter is only used 144 * when a default model is created automatically. 145 */ 146 @SuppressWarnings("unused") 147 @Parameter(defaultPrefix = BindingConstants.LITERAL) 148 private String include; 149 150 /** 151 * A comma-separated list of property names to be removed from the {@link org.apache.tapestry5.beaneditor.BeanModel} 152 * . 153 * The names are case-insensitive. This parameter is only used 154 * when a default model is created automatically. 155 */ 156 @Parameter(defaultPrefix = BindingConstants.LITERAL) 157 private String exclude; 158 159 /** 160 * A comma-separated list of property names indicating the order in which the properties should be presented. The 161 * names are case insensitive. Any properties not indicated in the list will be appended to the end of the display 162 * order. This parameter is only used 163 * when a default model is created automatically. 164 */ 165 @Parameter(defaultPrefix = BindingConstants.LITERAL) 166 private String reorder; 167 168 /** 169 * A Block to render instead of the table (and pager, etc.) when the source is empty. The default is simply the text 170 * "There is no data to display". This parameter is used to customize that message, possibly including components to 171 * allow the user to create new objects. 172 */ 173 //@Parameter(value = BindingConstants.SYMBOL + ":" + ComponentParameterConstants.GRID_EMPTY_BLOCK, 174 @Parameter(value = "block:empty", 175 defaultPrefix = BindingConstants.LITERAL) 176 private Block empty; 177 178 /** 179 * CSS class for the <table> element. In addition, informal parameters to the Grid are rendered in the table 180 * element. 181 */ 182 @Parameter(name = "class", defaultPrefix = BindingConstants.LITERAL, 183 value = BindingConstants.SYMBOL + ":" + ComponentParameterConstants.GRID_TABLE_CSS_CLASS) 184 @Property(write = false) 185 private String tableClass; 186 187 /** 188 * If true, then the Grid will be wrapped in an element that acts like a 189 * {@link org.apache.tapestry5.corelib.components.Zone}; all the paging and sorting links will refresh the zone, 190 * repainting the entire grid within it, but leaving the rest of the page (outside the zone) unchanged. 191 */ 192 @Parameter 193 private boolean inPlace; 194 195 /** 196 * If true, then the Grid will also render a table element complete with headers if the data source is empty. 197 * If set to true, a model parameter will have to be specified. A default model for a specific class can be 198 * created using {@link BeanModelSource#createDisplayModel(Class, org.apache.tapestry5.ioc.Messages)}. 199 */ 200 @Parameter 201 private boolean renderTableIfEmpty = false; 202 203 204 /** 205 * The name of the pseudo-zone that encloses the Grid. Starting in 5.4, this is always either 206 * null or "^" and is not really used the way it was in 5.3; instead it triggers the addition 207 * of a {@code data-inplace-grid-links} attribute in a div surrounding any links related to 208 * sorting or pagination. The rest is sorted out on the client. See module {@code t5/core/zone}. 209 */ 210 @Property(write = false) 211 private String zone; 212 213 private boolean didRenderZoneDiv; 214 215 216 /** 217 * The pagination model for the Grid, which encapsulates current page, sort column id, 218 * and sort ascending/descending. If not bound, a persistent property of the Grid is used. 219 * When rendering the Grid in a loop, this should be bound in some way to keep successive instances 220 * of the Grid configured individually. 221 * 222 * @since 5.4 223 */ 224 @Parameter(value = "defaultPaginationModel") 225 private GridPaginationModel paginationModel; 226 227 @Persist 228 private GridPaginationModel defaultPaginationModel; 229 230 @Inject 231 private ComponentResources resources; 232 233 @Inject 234 private BeanModelSource modelSource; 235 236 @Environmental 237 private JavaScriptSupport javaScriptSupport; 238 239 @Component(parameters = 240 {"index=inherit:columnIndex", "lean=inherit:lean", "overrides=overrides", "zone=zone"}) 241 private GridColumns columns; 242 243 @Component(parameters = 244 {"columnIndex=inherit:columnIndex", "rowsPerPage=rowsPerPage", "currentPage=currentPage", "row=row", 245 "overrides=overrides"}, publishParameters = "rowIndex,rowClass,volatile,encoder,lean") 246 private GridRows rows; 247 248 @Component(parameters = 249 {"source=dataSource", "rowsPerPage=rowsPerPage", "currentPage=currentPage", "zone=zone"}) 250 private GridPager pager; 251 252 @Component(parameters = "to=pagerTop") 253 private Delegate pagerTop; 254 255 @Component(parameters = "to=pagerBottom") 256 private Delegate pagerBottom; 257 258 @Component(parameters = "class=tableClass", inheritInformalParameters = true) 259 private Any table; 260 261 @Environmental(false) 262 private FormSupport formSupport; 263 264 /** 265 * Defines where block and label overrides are obtained from. By default, the Grid component provides block 266 * overrides (from its block parameters). 267 */ 268 @Parameter(value = "this", allowNull = false) 269 @Property(write = false) 270 private PropertyOverrides overrides; 271 272 /** 273 * Set up via the traditional or Ajax component event request handler 274 */ 275 @Environmental 276 private ComponentEventResultProcessor componentEventResultProcessor; 277 278 @Inject 279 private ComponentDefaultProvider defaultsProvider; 280 281 ValueEncoder defaultEncoder() 282 { 283 return defaultsProvider.defaultValueEncoder("row", resources); 284 } 285 286 /** 287 * A version of GridDataSource that caches the availableRows property. This addresses TAPESTRY-2245. 288 */ 289 static class CachingDataSource implements GridDataSource 290 { 291 private final GridDataSource delegate; 292 293 private boolean availableRowsCached; 294 295 private int availableRows; 296 297 CachingDataSource(GridDataSource delegate) 298 { 299 this.delegate = delegate; 300 } 301 302 public int getAvailableRows() 303 { 304 if (!availableRowsCached) 305 { 306 availableRows = delegate.getAvailableRows(); 307 availableRowsCached = true; 308 } 309 310 return availableRows; 311 } 312 313 public void prepare(int startIndex, int endIndex, List<SortConstraint> sortConstraints) 314 { 315 delegate.prepare(startIndex, endIndex, sortConstraints); 316 } 317 318 public Object getRowValue(int index) 319 { 320 return delegate.getRowValue(index); 321 } 322 323 public Class getRowType() 324 { 325 return delegate.getRowType(); 326 } 327 } 328 329 /** 330 * Default implementation that only allows a single column to be the sort column, and stores the sort information as 331 * persistent fields of the Grid component. 332 */ 333 class DefaultGridSortModel implements GridSortModel 334 { 335 public ColumnSort getColumnSort(String columnId) 336 { 337 if (paginationModel == null || !TapestryInternalUtils.isEqual(columnId, paginationModel.getSortColumnId())) 338 { 339 return ColumnSort.UNSORTED; 340 } 341 342 return getColumnSort(); 343 } 344 345 private ColumnSort getColumnSort() 346 { 347 return getSortAscending() ? ColumnSort.ASCENDING : ColumnSort.DESCENDING; 348 } 349 350 public void updateSort(String columnId) 351 { 352 assert InternalUtils.isNonBlank(columnId); 353 354 if (columnId.equals(paginationModel.getSortColumnId())) 355 { 356 setSortAscending(!getSortAscending()); 357 return; 358 } 359 360 paginationModel.setSortColumnId(columnId); 361 setSortAscending(true); 362 } 363 364 public List<SortConstraint> getSortConstraints() 365 { 366 // In a few limited cases we may not have yet hit the SetupRender phase, and the model may be null. 367 if (paginationModel == null || paginationModel.getSortColumnId() == null) 368 { 369 return Collections.emptyList(); 370 } 371 372 PropertyModel sortModel = getDataModel().getById(paginationModel.getSortColumnId()); 373 374 SortConstraint constraint = new SortConstraint(sortModel, getColumnSort()); 375 376 return Collections.singletonList(constraint); 377 } 378 379 public void clear() 380 { 381 paginationModel.setSortColumnId(null); 382 paginationModel.setSortAscending(null); 383 } 384 } 385 386 GridSortModel defaultSortModel() 387 { 388 return new DefaultGridSortModel(); 389 } 390 391 /** 392 * Returns a {@link org.apache.tapestry5.Binding} instance that attempts to identify the model from the source 393 * parameter (via {@link org.apache.tapestry5.grid.GridDataSource#getRowType()}. Subclasses may override to provide 394 * a different mechanism. The returning binding is variant (not invariant). 395 * 396 * @see BeanModelSource#createDisplayModel(Class, org.apache.tapestry5.ioc.Messages) 397 */ 398 protected Binding defaultModel() 399 { 400 401 return new AbstractBinding() 402 { 403 public Object get() 404 { 405 // Get the default row type from the data source 406 407 GridDataSource gridDataSource = source; 408 409 Class rowType = gridDataSource.getRowType(); 410 411 if (renderTableIfEmpty || rowType == null) 412 throw new RuntimeException( 413 String.format( 414 "Unable to determine the bean type for rows from %s. You should bind the model parameter explicitly.", 415 gridDataSource)); 416 417 // Properties do not have to be read/write 418 419 return modelSource.createDisplayModel(rowType, overrides.getOverrideMessages()); 420 } 421 422 /** 423 * Returns false. This may be overkill, but it basically exists because the model is 424 * inherently mutable and therefore may contain client-specific state and needs to be 425 * discarded at the end of the request. If the model were immutable, then we could leave 426 * invariant as true. 427 */ 428 @Override 429 public boolean isInvariant() 430 { 431 return false; 432 } 433 }; 434 } 435 436 static final ComponentAction<Grid> SETUP_DATA_SOURCE = new ComponentAction<Grid>() 437 { 438 private static final long serialVersionUID = 8545187927995722789L; 439 440 public void execute(Grid component) 441 { 442 component.setupDataSource(); 443 } 444 445 @Override 446 public String toString() 447 { 448 return "Grid.SetupDataSource"; 449 } 450 }; 451 452 Object setupRender() 453 { 454 if (formSupport != null) 455 { 456 formSupport.store(this, SETUP_DATA_SOURCE); 457 } 458 459 setupDataSource(); 460 461 // If there's no rows, display the empty block placeholder. 462 463 return !renderTableIfEmpty && cachingSource.getAvailableRows() == 0 ? empty : null; 464 } 465 466 void cleanupRender() 467 { 468 // if an inPlace Grid is rendered inside a Loop, be sure to generate a new wrapper 469 // zone for each iteration (TAP5-2256) 470 zone = null; 471 472 // If grid is rendered inside a Loop. be sure to generate a new data model for 473 // each iteration (TAP5-2470) 474 dataModel = null; 475 } 476 477 public GridPaginationModel getDefaultPaginationModel() 478 { 479 if (defaultPaginationModel == null) 480 { 481 defaultPaginationModel = new GridPaginationModelImpl(); 482 } 483 484 return defaultPaginationModel; 485 } 486 487 void setupDataSource() 488 { 489 // TAP5-34: We pass the source into the CachingDataSource now; previously 490 // we were accessing source directly, but during submit the value wasn't 491 // cached, and therefore access was very inefficient, and sorting was 492 // very inconsistent during the processing of the form submission. 493 494 cachingSource = new CachingDataSource(source); 495 496 int availableRows = cachingSource.getAvailableRows(); 497 498 if (availableRows == 0) 499 return; 500 501 int maxPage = ((availableRows - 1) / rowsPerPage) + 1; 502 503 // This captures when the number of rows has decreased, typically due to deletions. 504 505 int effectiveCurrentPage = getCurrentPage(); 506 507 if (effectiveCurrentPage > maxPage) 508 effectiveCurrentPage = maxPage; 509 510 int startIndex = (effectiveCurrentPage - 1) * rowsPerPage; 511 512 int endIndex = Math.min(startIndex + rowsPerPage - 1, availableRows - 1); 513 514 cachingSource.prepare(startIndex, endIndex, sortModel.getSortConstraints()); 515 } 516 517 Object beginRender(MarkupWriter writer) 518 { 519 // Skip rendering of component (template, body, etc.) when there's nothing to display. 520 // The empty placeholder will already have rendered. 521 522 if (cachingSource.getAvailableRows() == 0) 523 return !renderTableIfEmpty ? false : null; 524 525 if (inPlace && zone == null) 526 { 527 javaScriptSupport.require("t5/core/zone"); 528 529 writer.element("div", "data-container-type", "zone"); 530 531 didRenderZoneDiv = true; 532 533 // Through Tapestry 5.3, we had a specific id for the zone that had to be passed down to the 534 // GridPager and etc. That's no longer necessary, so zone will always be null or "^". We don't 535 // even need any special ids to be allocated! 536 zone = "^"; 537 } 538 539 return null; 540 } 541 542 void afterRender(MarkupWriter writer) 543 { 544 if (didRenderZoneDiv) 545 { 546 writer.end(); // div 547 didRenderZoneDiv = false; 548 } 549 } 550 551 public BeanModel getDataModel() 552 { 553 if (dataModel == null) 554 { 555 dataModel = model; 556 557 BeanModelUtils.modify(dataModel, add, include, exclude, reorder); 558 } 559 560 return dataModel; 561 } 562 563 public int getNumberOfProperties() 564 { 565 return getDataModel().getPropertyNames().size(); 566 } 567 568 public GridDataSource getDataSource() 569 { 570 return cachingSource; 571 } 572 573 public GridSortModel getSortModel() 574 { 575 return sortModel; 576 } 577 578 public Object getPagerTop() 579 { 580 return pagerPosition.isMatchTop() ? pager : null; 581 } 582 583 public Object getPagerBottom() 584 { 585 return pagerPosition.isMatchBottom() ? pager : null; 586 } 587 588 public int getCurrentPage() 589 { 590 Integer currentPage = paginationModel.getCurrentPage(); 591 592 return currentPage == null ? 1 : currentPage; 593 } 594 595 public void setCurrentPage(int currentPage) 596 { 597 paginationModel.setCurrentPage(currentPage); 598 } 599 600 private boolean getSortAscending() 601 { 602 Boolean sortAscending = paginationModel.getSortAscending(); 603 604 return sortAscending != null && sortAscending.booleanValue(); 605 } 606 607 private void setSortAscending(boolean sortAscending) 608 { 609 paginationModel.setSortAscending(sortAscending); 610 } 611 612 public int getRowsPerPage() 613 { 614 return rowsPerPage; 615 } 616 617 public Object getRow() 618 { 619 return row; 620 } 621 622 public void setRow(Object row) 623 { 624 this.row = row; 625 } 626 627 /** 628 * Resets the Grid to inital settings; this sets the current page to one, and 629 * {@linkplain org.apache.tapestry5.grid.GridSortModel#clear() clears the sort model}. 630 */ 631 public void reset() 632 { 633 sortModel.clear(); 634 setCurrentPage(1); 635 } 636 637 /** 638 * Event handler for inplaceupdate event triggered from nested components when an Ajax update occurs. The event 639 * context will carry the zone, which is recorded here, to allow the Grid and its sub-components to properly 640 * re-render themselves. Invokes 641 * {@link org.apache.tapestry5.services.ComponentEventResultProcessor#processResultValue(Object)} passing this (the 642 * Grid component) as the content provider for the update. 643 */ 644 void onInPlaceUpdate() throws IOException 645 { 646 this.zone = "^"; 647 648 componentEventResultProcessor.processResultValue(this); 649 } 650 651 public String getClientId() 652 { 653 return table.getClientId(); 654 } 655}