Tapestry in Action Licensed to Scott Douglass [email protected] Tapestry in Action HOWARD M. LEWIS SHIP MANNING Greenwich (74° w. long.) Licensed to Scott Douglass <[email protected]> For online information and ordering of this and other Manning books, go to www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact: Special Sales Department Manning Publications Co. 209 Bruce Park Avenue Fax: (203) 661-9018 Greenwich, CT 06830 email: [email protected] ©2004 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books they publish printed on acid-free paper, and we exert our best efforts to that end. Manning Publications Co. Copyeditor: Liz Welch 209 Bruce Park Avenue Typesetter: Denis Dalinnik Greenwich, CT 06830 Cover designer: Leslie Haimes ISBN 1-932394-11-7 Printed in the United States of America 12345678910–VHG–08 07 06 05 04 Licensed to Scott Douglass <[email protected]> To my parents, who bought me my first computer when I was 13 and had no idea what they had started Licensed to Scott Douglass <[email protected]> Licensed to Scott Douglass <[email protected]> brief contents PART 1USING BASIC TAPESTRY COMPONENTS ...........................1 1 ■ Introducing Tapestry 3 2 ■ Getting started with Tapestry 38 3 ■ Tapestry and HTML forms 92 4 ■ Advanced form components 133 5 ■ Form input validation 169 PART 2CREATING TAPESTRY COMPONENTS............................213 6 ■ Creating reusable components 215 7 ■ Tapestry under the hood 269 8 ■ Advanced techniques 322 PART 3BUILDING COMPLETE TAPESTRY APPLICATIONS........381 9 ■ Putting it all together 383 10 ■ Implementing a Tapestry application 403 vii Licensed to Scott Douglass <[email protected]> viii BRIEF CONTENTS APPENDIXES A ■ Getting involved with Tapestry 479 B ■ Building the examples with Ant 485 C ■ Tapestry component reference 493 D ■ Tapestry specifications 516 Licensed to Scott Douglass <[email protected]> contents foreword xvii preface xix acknowledgments xxi about this book xxiii about the title xxvii about the cover illustration xxviii PART 1 USING BASIC TAPESTRY COMPONENTS ...................... 1 Introducing Tapestry 3 1 1.1 What are web applications? 5 1.2 What are Java servlets? 7 Understanding servlet multithreading 9 ■ Managing server-side state 10 ■ Using Struts with servlets 12 ■ Understanding the limitations of servlets 12 1.3 Why do we need Tapestry? 16 What is a framework? 16 ■ What is a component? 17 What is Tapestry? 18 ■ Comparing Tapestry to Swing 21 1.4 Understanding Tapestry’s goals 22 Simplicity 22 ■ Consistency 22 ■ Efficiency 23 Feedback 23 ix Licensed to Scott Douglass <[email protected]> x CONTENTS 1.5 How does Tapestry work? 25 What’s in a Tapestry application? 27 ■ Tapestry’s Model- View-Controller (MVC) pattern 29 ■ Tapestry classes 33 1.6 Using Spindle 35 1.7 Summary 37 Getting started with Tapestry 38 2 2.1 Introducing the Hangman application 39 Determining the application flow 41 ■ Creating page mockups 42 ■ Defining the domain objects 44 Defining the pages 49 2.2 Developing the Home page 51 Understanding the Home page specification 52 ■ Rendering the Home page 54 ■ Defining the Home page class 57 Examining the Visit object 60 2.3 Implementing the Home page using standard servlets 62 2.4 Developing the Guess page 65 Displaying the remaining guesses 73 ■ Generating the guessed word display 79 ■ Selecting guesses 83 2.5 Developing the Win and Lose pages 89 2.6 Configuring the web.xml deployment descriptor 89 2.7 Summary 91 Tapestry and HTML forms 92 3 3.1 Understanding HTML forms 93 3.2 Creating a simple login form 96 Implementing the Login page class 99 ■ Using specified properties 101 3.3 Understanding the Form component 103 Developing forms without Tapestry 103 ■ Developing forms with Tapestry 105 ■ Handling form submissions 108 3.4 Using basic form control components 109 Understanding the essentials 110 ■ The Checkbox component 111 ■ Radio and RadioGroup components 111 Licensed to Scott Douglass <[email protected]> CONTENTS xi Select and Option components 113 ■ Submit and ImageSubmit components 118 3.5 Creating a to-do list 120 Defining the data object 121 ■ Creating the ToDo HTML template 122 ■ Specifying properties in the page specification 125 ■ Initializing the toDoList property 126 Handling reordering 127 ■ Deleting completed items 128 Triggering stale links 129 3.6 Summary 132 Advanced form components 133 4 4.1 Introducing the advanced form components 134 4.2 Creating drop-down lists with PropertySelection 134 Adding priority levels to the ToDo application 136 ■ Updating the HTML template 138 ■ Implementing the page class 139 Implementing the model 140 ■ Using enums instead of integers 144 4.3 Recording data in the form with Hidden 148 4.4 Looping within a form using ListEdit 151 Using the ListEditMap 153 ■ Using ListEdit in the ToDo application 154 4.5 Handling file uploads 160 4.6 Creating pop-up date selections using DatePicker 165 4.7 Summary 168 Form input validation 169 5 5.1 Validating user input 170 Using FieldLabels in conjunction with ValidFields 173 Using validators 173 ■ Using validation delegates 174 Using helper beans 178 5.2 Building the Register page 179 Creating the Register HTML template 181 ■ Creating the Register page specification 189 5.3 Validating input based on regular expressions 195 5.4 Customizing label and field decorations 199 5.5 Enabling client-side validation 202 Licensed to Scott Douglass <[email protected]> xii CONTENTS 5.6 Handling form-level validations 205 5.7 Using validation without ValidField 208 5.8 Summary 211 PART 2 CREATING TAPESTRY COMPONENTS ..................... 213 Creating reusable components 215 6 6.1 Creating simple template components 216 6.2 Creating the component specification 219 Specifying the component’s Java class 219 ■ Discarding the component’s body 220 ■ Forbidding informal parameters 221 Declaring parameters 222 ■ Reserving names 230 6.3 Creating the Digit and Scaffold components 230 Specifying the digit parameter 232 ■ Using the digit parameter 232 ■ Creating the template 233 ■ Using the Digit component 233 ■ Using the Scaffold component 234 6.4 Creating the Letter component 234 Specifying the Letter component 235 ■ Implementing the Letter component 236 ■ Using the Letter component 237 6.5 Building the Spell component 238 Implementing the Spell component 239 ■ Using the Spell component 240 6.6 Building the Border component 242 Creating the Border template 243 ■ Creating the Border specification 244 ■ Using the Border component 244 6.7 Creating interactive, reusable components 246 Introducing the Pet Store image map 246 ■ Specifying the DirectArea component 247 ■ Implementing the DirectArea component 248 ■ Using the DirectArea component 252 6.8 Using component libraries 254 Declaring libraries 254 ■ Referencing library components 256 6.9 Packaging components into libraries 261 Creating the library specification 262 ■ Creating the library specification 264 ■ Creating the FormError component 264 Using the FormError component 267 6.10 Summary 268 Licensed to Scott Douglass <[email protected]> CONTENTS xiii Tapestry under the hood 269 7 7.1 Processing requests 270 7.2 Understanding the application servlet 271 Servlet request processing 271 ■ Understanding server-side state 272 ■ Managing server-side state in a cluster 274 7.3 Understanding the Tapestry engine 277 7.4 Understanding engine services 279 What’s the problem with application URLs? 279 ■ How does Tapestry handle application operations? 280 ■ Using the home service 281 ■ Rendering pages with the page service 283 Linking to listener methods with the direct service 284 Creating bookmarkable links using the external service 290 7.5 Page rendering in detail 291 Using markup writers 292 ■ Going beyond HTML 295 Understanding the page-rendering sequence 297 Using page-rendering events 297 7.6 Loading and pooling pages 299 Retrieving pages from the pool 300 ■ Creating new page instances 302 ■ Returning pages to the pool 304 7.7 Using persistent page properties 306 7.8 Using specified properties 308 7.9 Localizing Tapestry applications 309 Using Java localization 310 ■ Using Tapestry’s localization features 311 7.10 Summary 321 Advanced techniques 322 8 8.1 Creating new engine services 323 Defining a banner ad system 324 ■ Defining the data model 326 ■ Accessing the data model as an application extension 328 ■ Implementing the BannerAd component 329 Implementing the banner service 332 ■ Creating the library specification 336 ■ Building a banner ad application 337 8.2 Client-side scripting 339 Defining the CreditCardField component 341 ■ Working with the Body component 344 ■ Creating the Tapestry script Licensed to Scott Douglass <[email protected]> xiv CONTENTS specification 345 ■ Creating the CreditCardField specification 355 ■ Creating the CreditCardField component 356 ■ Using the component 368 8.3 Integrating