Prepared exclusively for Maxim Filatov Important Information About Rails Versions This book is written for Rails 2. As this printing of the book is going to press, the current generally available Gem version of Rails is 2.2.2. The code in this book has been tested against this version. This book started life with the same text as the Second Edition, which cov- ered Rails 1.2.6. Pages containing this original text have a gray heading and footer. As we migrate content to Rails 2, you’ll find the header color changes to red. The Rails core team is continuing to work on Rails 2. From time to time, new releases may introduce incompatibilities for applications written for prior versions of Rails. In order to experiment with these changes, the Rails devel- opers are making the changes available via Edge Rails (discussed starting on page 268). These changes won’t affect you unless you explicitly install this experimental code—you won’t find yourself running it unless you over- ride Gem defaults or deliberately choose to use Edge Rails. However, if you do decide to run this experimental Rails code, you’ll find that some stuff in this book (and some stuff in you r existing Rails applications) may no longer run. To determine the version of Rails that you are running, you can issue rails -v at a command prompt. Sam, Dave, and David Prepared exclusively for Maxim Filatov Agile Web De velopment with Rails Third Edition Sam Ruby Dave Thomas David Heinemeier Hansson with Leon Breedt Mike Clark James Duncan Davidson Justin Gehtland Andr eas Schwarz The Pragmatic Bookshelf Raleigh, North Carolina Dallas, Texas Prepared exclusively for Maxim Filatov Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and The Pragmatic Program- mers, LLC was aware of a trademark claim, the designations have been printed in initial capital letters or in all capitals. The Pragmatic Starter Kit, The Pragmatic Programmer, Pragmatic Program- ming, Pragmatic Bookshelf and the linking g device are trademarks of The Pragmatic Programmers, LLC. Every precaution was taken in the preparation of this book. However, the publisher assumes no responsibility for errors or o missions, or for damages that may result from the use of information (including program listings) contained herein. Our Pragmat ic courses, workshops, and other products can help you and your team create better software and have more fun. For more informatio n, as well as the latest Pragmatic titles, please visit us at http://www.pragprog.com Copyright © 2009 The Pragmatic Programmers LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form, or by any m eans, electronic, mechanical, photocopying, recording, or ot herwise, without the prior consent of the publisher. Printed in the Unit ed States of America. ISBN-10: 1-934356-16-6 ISBN-13: 978-1-9343561-6-6 Printed on acid-free paper. B1.9 printing, January 7, 2009 Version: 2009-1-7 Prepared exclusively for Maxim Filatov Con t ents Preface to the Second Edition 12 Preface to the Third Edition 14 1 Introduction 15 1.1 Rails Is Agile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.2 Finding Your Way Around . . . . . . . . . . . . . . . . . . . . . 18 1.3 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Part I—Ge tting Started 22 2 The Architecture of Rails Applications 23 2.1 Models, Views, and Controllers . . . . . . . . . . . . . . . . . . 23 2.2 Active Record: Rails Model Support . . . . . . . . . . . . . . . . 26 2.3 Action Pack: The View and Controller . . . . . . . . . . . . . . . 30 3 Installing Rails 32 3.1 Your Shopping List . . . . . . . . . . . . . . . . . . . . . . . . . . 32 3.2 Installing on Windows . . . . . . . . . . . . . . . . . . . . . . . . 32 3.3 Installing on Mac OS X . . . . . . . . . . . . . . . . . . . . . . . 34 3.4 Installing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.5 Choosing a Rails Version . . . . . . . . . . . . . . . . . . . . . . 36 3.6 Development Environments . . . . . . . . . . . . . . . . . . . . 37 3.7 Rails and Databases . . . . . . . . . . . . . . . . . . . . . . . . . 41 3.8 Keeping Up-to-Date . . . . . . . . . . . . . . . . . . . . . . . . . 43 3.9 Rails and ISPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4 Instant Gratification 44 4.1 Creating a New Application . . . . . . . . . . . . . . . . . . . . . 44 4.2 Hello, Rails! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 4.3 Linking Pages Together . . . . . . . . . . . . . . . . . . . . . . . 57 4.4 What We Just Did . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Prepared exclusively for Maxim Filatov CONTENTS 6 Part II—Building an Application 62 5 The Depot Application 63 5.1 Incremental Development . . . . . . . . . . . . . . . . . . . . . . 63 5.2 What Depot Does . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 5.3 Let’s Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 6 Task A: Product Maintenan ce 69 6.1 Iteration A1: Get Something Running . . . . . . . . . . . . . . . 69 6.2 Create the Products Model and Maintenance Application . . . 75 6.3 Iteration A2: Add a Missing Column . . . . . . . . . . . . . . . 79 6.4 Iteration A3: Validate! . . . . . . . . . . . . . . . . . . . . . . . . 84 6.5 Iteration A4: Prettier Listings . . . . . . . . . . . . . . . . . . . . 89 7 Task B: Catalog Display 96 7.1 Iteration B1: Create the Catalog Listing . . . . . . . . . . . . . 96 7.2 Iteration B2: Add a Page Layout . . . . . . . . . . . . . . . . . . 100 7.3 Iteration B3: Use a Helper to Format the Pri ce . . . . . . . . . 102 7.4 Iteration B4: Linking to the Cart . . . . . . . . . . . . . . . . . . 103 8 Task C: Cart Creation 107 8.1 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 8.2 Iteration C1: Creating a Cart . . . . . . . . . . . . . . . . . . . . 111 8.3 Iteration C2: A Smarter Cart . . . . . . . . . . . . . . . . . . . . 114 8.4 Iteration C3: Handling Errors . . . . . . . . . . . . . . . . . . . 117 8.5 Iteration C4: Finishing the Cart . . . . . . . . . . . . . . . . . . 122 9 Task D: Add a Dash of A JAX 127 9.1 Iteration D1: Moving the Cart . . . . . . . . . . . . . . . . . . . 128 9.2 Iteration D2: An AJAX-Based Cart . . . . . . . . . . . . . . . . 133 9.3 Iteration D3: Highlighting Changes . . . . . . . . . . . . . . . . 136 9.4 Iteration D4: Hide an Empty Cart . . . . . . . . . . . . . . . . . 139 9.5 Iteration D5: Degrading If Javascript Is Disabled . . . . . . . . 142 9.6 What We Just Did . . . . . . . . . . . . . . . . . . . . . . . . . . 143 10 Task E: Check Out! 145 10.1 Iteration E1: Capturing an Order . . . . . . . . . . . . . . . . . 145 11 Task F: Administration 161 11.1 Iteration F1: Adding Users . . . . . . . . . . . . . . . . . . . . . 161 11.2 Iteration F2: Logging In . . . . . . . . . . . . . . . . . . . . . . . 171 11.3 Iteration F3: Limiting Access . . . . . . . . . . . . . . . . . . . . 174 11.4 Iteration F4: A Sidebar, More Administration . . . . . . . . . . 177 Report erratum this copy is (B1.9 printing, January 7, 2009) Prepared exclusively for Maxim Filatov CONTENTS 7 12 Task G: One Last Wafer-Thin Change 184 12.1 Generating the XML Feed . . . . . . . . . . . . . . . . . . . . . . 184 12.2 Finishing Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 13 Task I: Intern ationalization 196 13.1 Iteration I1: Enabling Translation . . . . . . . . . . . . . . . . . 196 13.2 Iteration I2: Strategies for content . . . . . . . . . . . . . . . . . 211 14 Task T: Testing 214 14.1 Tests Baked Right In . . . . . . . . . . . . . . . . . . . . . . . . 214 14.2 Unit Testing of Models . . . . . . . . . . . . . . . . . . . . . . . . 215 14.3 Functional Testing of Controllers . . . . . . . . . . . . . . . . . 227 14.4 Integration Testing of Applications . . . . . . . . . . . . . . . . 244 14.5 Performance Testing . . . . . . . . . . . . . . . . . . . . . . . . . 253 14.6 Using Mock Objects . . . . . . . . . . . . . . . . . . . . . . . . . 257 Part III —The Rails Framework 260 15 Rails in Depth 261 15.1 So, Where’s Rails? . . . . . . . . . . . . . . . . . . . . . . . . . . 261 15.2 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . 261 15.3 Rails Configuration . . . . . . . . . . . . . . . . . . . . . . . . . 268 15.4 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 272 15.5 Logging in Rails . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 15.6 Debugging Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 15.7 What’s Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 16 Active Support 280 16.1 Generally Available Extensions . . . . . . . . . . . . . . . . . . 280 16.2 Enumerations and Arrays . . . . . . . . . . . . . . . . . . . . . 281 16.3 Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 16.4 String Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 283 16.5 Extensions to Numbers . . . . . . . . . . . . . . . . . . . . . . . 286 16.6 Time and Date Extensions . . . . . . . . . . . . . . . . . . . . . 287 16.7 An Extension to Ruby Symbols . . . . . . . . . . . . . . . . . . 289 16.8 with_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 16.9 Unicode Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 17 Migrations 296 17.1 Creating and Running Migrations . . . . . . . . . . . . . . . . . 298 17.2 Anatomy of a Migration . . . . . . . . . . . . . . . . . . . . . . . 300 17.3 Managing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 17.4 Data Migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Report erratum this copy is (B1.9 printing, January 7, 2009) Prepared exclusively for Maxim Filatov CONTENTS 8 17.5 Advanced Migrations . . . . . . . . . . . . . . . . . . . . . . . . 312 17.6 When Migrations Go Bad . . . . . . . . . . . . . . . . . . . . . . 315 17.7 Schema Manipulation Outside Migrations . . . . . . . . . . . . 316 17.8 Managing Migrations . . . . . . . . . . . . . . . . . . . . . . . . 317 18 Active Record: The B asics 319 18.1 Tables and Classes . . . . . . . . . . . . . . . . . . . . . . . . . 320 18.2 Columns and Attributes . . . . . . . . . . . . . . . . . . . . . . 320 18.3 Primary Keys and IDs . . . . . . . . . . . . . . . . . . . . . . . . 324 18.4 Connecting to the Database . . . . . . . . . . . . . . . . . . . . 326 18.5 CRUD—Create, Read, Update, Delete . . . . . . . . . . . . . . . 331 18.6 Aggregation and Structured Data . . . . . . . . . . . . . . . . . 350 18.7 Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 19 Active Record: Relationships between Tables 361 19.1 Creating Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . 362 19.2 Specifying Relationships in Models . . . . . . . . . . . . . . . . 364 19.3 belongs_to and has_xxx Declarations . . . . . . . . . . . . . . . 366 19.4 Joining to Multiple Tables . . . . . . . . . . . . . . . . . . . . . 381 19.5 Self-referential Joins . . . . . . . . . . . . . . . . . . . . . . . . . 391 19.6 Acts As . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 19.7 When Things Get Saved . . . . . . . . . . . . . . . . . . . . . . . 396 19.8 Preloading Child Rows . . . . . . . . . . . . . . . . . . . . . . . 398 19.9 Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 20 Active Record: Object Life Cycle 401 20.1 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 20.2 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 20.3 Advanced Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 419 20.4 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 21 Action Controller: Routing and URLs 431 21.1 The Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 21.2 Routing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 432 21.3 Resource-Based Routing . . . . . . . . . . . . . . . . . . . . . . 448 21.4 Testing Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 22 Action Controller and Rails 467 22.1 Action Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 22.2 Cookies and Sessions . . . . . . . . . . . . . . . . . . . . . . . . 479 22.3 Flash—Communicating between Actions . . . . . . . . . . . . . 489 22.4 Filters and Verification . . . . . . . . . . . . . . . . . . . . . . . 491 22.5 Caching, Part One . . . . . . . . . . . . . . . . . . . . . . . . . . 499 Report erratum this copy is (B1.9 printing, January 7, 2009) Prepared exclusively for Maxim Filatov CONTENTS 9 22.6 The Problem with GET Requests . . . . . . . . . . . . . . . . . . 508 23 Action View 512 23.1 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 23.2 Using Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 23.3 Helpers for Formatting, Linking, and Pagination . . . . . . . . 520 23.4 How Forms Work . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 23.5 Forms That Wrap Model Objects . . . . . . . . . . . . . . . . . . 529 23.6 Custom Form Builders . . . . . . . . . . . . . . . . . . . . . . . 541 23.7 Working with Nonmodel Fields . . . . . . . . . . . . . . . . . . . 546 23.8 Uploading Files to Rails Applications . . . . . . . . . . . . . . . 549 23.9 Layouts and Components . . . . . . . . . . . . . . . . . . . . . . 553 23.10 Caching, Part Two . . . . . . . . . . . . . . . . . . . . . . . . . . 560 23.11 Adding New Templating Systems . . . . . . . . . . . . . . . . . 565 24 The Web, V2.0 568 24.1 Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 24.2 Script.aculo.us . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 24.3 RJS Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 24.4 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 25 Action Mailer 614 25.1 Sending E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 25.2 Receiving E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 25.3 Testing E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 26 Active Resources 630 26.1 Alternatives to ActiveResource . . . . . . . . . . . . . . . . . . . 630 26.2 Show me the Code! . . . . . . . . . . . . . . . . . . . . . . . . . 633 26.3 Relationships and Collections . . . . . . . . . . . . . . . . . . . 636 26.4 Pulling it all together . . . . . . . . . . . . . . . . . . . . . . . . 638 Part IV—Secure and Deploy Your Appl ic ation 641 27 Securing Your Rails Application 642 27.1 SQL Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 27.2 Creating Records Directly from Form Parameters . . . . . . . 644 27.3 Don’t Trust ID Parameters . . . . . . . . . . . . . . . . . . . . . 646 27.4 Don’t Expose Controller Methods . . . . . . . . . . . . . . . . . 647 27.5 Cross-Site Scripting (CSS/XSS) . . . . . . . . . . . . . . . . . . 648 27.6 Avoid Session Fixation Attacks . . . . . . . . . . . . . . . . . . 650 27.7 File Uploads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 27.8 Don’t Store Sensitive Information in the Clear . . . . . . . . . 652 Report erratum this copy is (B1.9 printing, January 7, 2009) Prepared exclusively for Maxim Filatov CONTENTS 10 27.9 Use SSL to Transmit Sensitive Information . . . . . . . . . . . 653 27.10 Don’t Cache Authenticated Pages . . . . . . . . . . . . . . . . . 654 27.11 Knowing That It Works . . . . . . . . . . . . . . . . . . . . . . . 654 28 Deployment and Production 656 28.1 Starting Early . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 28.2 How a Production Server Works . . . . . . . . . . . . . . . . . . 657 28.3 Installing Passenger . . . . . . . . . . . . . . . . . . . . . . . . . 660 28.4 Worry free Deployment with Capistrano . . . . . . . . . . . . . 662 28.5 Checking Up on a Deployed Application . . . . . . . . . . . . . 666 28.6 Production Application Chores . . . . . . . . . . . . . . . . . . . 667 28.7 Moving On to Launch and Beyond . . . . . . . . . . . . . . . . 669 Part V—Appendices 671 A Introduction to Ruby 672 A.1 Ruby Is an Object-Oriented Language . . . . . . . . . . . . . . 672 A.2 Ruby Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 A.3 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674 A.4 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 A.5 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 A.6 Arrays and Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . 679 A.7 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 680 A.8 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 681 A.9 Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . 681 A.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682 A.11 Marshaling Objects . . . . . . . . . . . . . . . . . . . . . . . . . 683 A.12 Interactive Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 A.13 Ruby Idioms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 A.14 RDoc Documentation . . . . . . . . . . . . . . . . . . . . . . . . 685 B Configuration Parameters 686 B.1 Top-Level Configuration . . . . . . . . . . . . . . . . . . . . . . . 686 B.2 Active Record Configuration . . . . . . . . . . . . . . . . . . . . 688 B.3 Action Controller Configuration . . . . . . . . . . . . . . . . . . 691 B.4 Action View Configuration . . . . . . . . . . . . . . . . . . . . . 692 B.5 Action Mailer Configuration . . . . . . . . . . . . . . . . . . . . 693 B.6 Test Case Configuration . . . . . . . . . . . . . . . . . . . . . . . 694 Report erratum this copy is (B1.9 printing, January 7, 2009) Prepared exclusively for Maxim Filatov [...]... incompatibilities with 2.2.2, and it is more than likely that future versions will, too 1.3 Acknowledgments You’d think that producing a third edition of a book would be easy After all, you already have all the text It’s just a tweak to some code here and a minor wording change there, and you’re done You’d think It’s difficult to tell exactly, but our impression is that creating each edition of Agile Web Development. .. second edition basically a new book It seems strange to be releasing a second edition at a time when the first edition is still among the best-selling programming books in the world But Rails has changed, and we need to change this book with it Enjoy! Dave Thomas October 2006 Prepared exclusively for Maxim Filatov Report erratum this copy is (B1.9 printing, January 7, 2009) 13 Preface to the Third Edition. .. starting with half of a really good application already in place But there’s something else to Rails—something that’s hard to describe Somehow, it just feels right Of course you’ll have to take our word for that until you write some Rails applications for yourself (which should be in the next 45 minutes or so ) That’s what this book is all about 1.1 Rails Is Agile The title of this book is Agile Web Development. .. The title of this book is Agile Web Development with Rails You may be surprised to discover that we don’t have explicit sections on applying agile practices X, Y, and Z to Rails coding The reason is both simple and subtle Agility is part of the fabric of Rails Let’s look at the values expressed in the Agile Manifesto as a set of four preferences.1 Agile development favors the following • Individuals... Hansson, the creator of Rails, was named Hacker of the Year at OSCON Rails won a Jolt Award as best web development tool, and the first edition of this book received a Jolt Award as best technical book But the Rails core team didn’t just sit still, soaking up the praise Instead, they’ve been heads-down adding new features and facilities Rails 1.0, which came out some months after the first edition hit the streets,... terms of working with a different publisher, operating system, and toolset) But I can’t begin to express how much I like the beta books program — the readers that this book has attracted so far have been great and their comments, questions, and feedback have been most appreciated Dave Thomas November 2006 dave@pragprog.com Sam Ruby January 2009 rubys@intertwingly.net Agile Web Development with Rails I... developers who were frustrated with the technologies they were using to create web applications It didn’t seem to matter whether they were using Java, PHP, or NET—there was a growing sense that their job was just too damn hard And then, suddenly, along came Rails, and Rails is easier But easy on its own doesn’t cut it We’re talking about professional developers writing real-world web sites They wanted to... along with support for test fixtures and stubs during testing, gives developers the safety net they need when making those changes With a good set of tests in place, changes are less nerve-wracking Rather than constantly trying to tie Rails processes to the agile principles, we’ve decided to let the framework speak for itself As you read through the tutorial chapters, try to imagine yourself developing web. .. understands the new Web Rails isn’t playing catchup with the new de facto web standards: it’s helping define them And Rails Prepared exclusively for Maxim Filatov Report erratum this copy is (B1.9 printing, January 7, 2009) 16 R AILS I S A GILE makes it easy for developers to integrate features such as AJAX and RESTful interfaces into their code: support is built in (And if you’re not familar with AJAX and... as a co-author of the third edition of this book, I was thrilled After all, it was from the first printing of the first edition of this book that I had learned Rails Dave and I also have much in common While he prefers Emacs and Mac OS X and my preferences tend towards VIM and Ubuntu, we both share a love for the command line and getting our fingers dirty with code; starting with tangible examples before . exclusively for Maxim Filatov Agile Web De velopment with Rails Third Edition Sam Ruby Dave Thomas David Heinemeier Hansson with Leon Breedt Mike Clark James. That’s what this book is all about. 1.1 Rails Is Agile The title of this book is Agile Web Development with Rails. You ma y be sur- prised to discover that