Agile web development with rails fourth edition

Notes:	Hide Notes

Slide 1: Prepared exclusively for Jared Rosoff Slide 2: Beta Book Agile publishing for agile developers Under Construction The book you’re reading is still under development. As part of our Beta book program, we’re releasing this copy well before a normal book would be released. That way you’re able to get this content a couple of months before it’s available in ﬁnished form, and we’ll get feedback to make the book even better. The idea is that everyone wins! Be warned. The book has not had a full technical edit, so it will contain errors. It has not been copyedited, so it will be full of typos and other weirdness. And there’s been no effort spent doing layout, so you’ll ﬁnd bad page breaks, over-long lines with little black rectangles, incorrect hyphenations, and all the other ugly things that you wouldn’t expect to see in a ﬁnished book. We can’t be held liable if you use this book to try to create a spiffy application and you somehow end up with a strangely shaped farm implement instead. Despite all this, we think you’ll enjoy it! Download Updates Throughout this process you’ll be able to download updated ebooks from your account on http://pragprog.com. When the book is ﬁnally ready, you’ll get the ﬁnal version (and subsequent updates) from the same address. Send us your feedback In the meantime, we’d appreciate you sending us your feedback on this book at http://pragprog.com/titles/rails4/errata, or by using the links at the bottom of each page. Thank you for being part of the Pragmatic community! Andy & Dave Prepared exclusively for Jared Rosoff Slide 3: Agile Web Development with Rails Fourth Edition Sam Ruby Dave Thomas David Heinemeier Hansson Leon Breedt Mike Clark James Duncan Davidson Justin Gehtland Andreas Schwarz with The Pragmatic Bookshelf Raleigh, North Carolina Dallas, Texas Prepared exclusively for Jared Rosoff Slide 4: 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 Programmers, 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 Programming, 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 omissions, or for damages that may result from the use of information (including program listings) contained herein. Our Pragmatic courses, workshops, and other products can help you and your team create better software and have more fun. For more information, as well as the latest Pragmatic titles, please visit us at http://www.pragprog.com. Copyright © 2010 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 means, electronic, mechanical, photocopying, recording, or otherwise, without the prior consent of the publisher. Printed in the United States of America. ISBN-10: 1-934356-54-9 ISBN-13: 978-1-934356-54-8 Printed on acid-free paper. B8.0 printing, September 9, 2010 Version: 2010-9-9 Prepared exclusively for Jared Rosoff Slide 5: Contents Changes in the Beta Releases Beta 8—September 9 . . . . Beta 7—August 25 . . . . . . Beta 6—July 27 . . . . . . . Beta 5—June 28 . . . . . . . Beta 4—May 26 . . . . . . . . Beta 3—May 11 . . . . . . . . Beta 2—May 3 . . . . . . . . Preface to the Fourth Edition Acknowledgements Introduction Rails Simply Feels Right Rails Is Agile . . . . . . . Who This Book Is For . . How To Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 11 11 12 12 12 13 13 15 17 19 19 21 22 22 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part I—Getting Started 1 Installing Rails 1.1 Installing on Windows . . . . . . . . . . . . . 1.2 Installing on Mac OS X . . . . . . . . . . . . 1.3 Installing on Linux . . . . . . . . . . . . . . . 1.4 Choosing a Rails Version . . . . . . . . . . . 1.5 Setting Up Your Development Environment 1.6 Rails and Databases . . . . . . . . . . . . . . 1.7 What We Just Did . . . . . . . . . . . . . . . 27 29 29 31 32 33 34 38 39 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prepared exclusively for Jared Rosoff Slide 6: CONTENTS 6 2 Instant Gratiﬁcation 2.1 Creating a New Application . 2.2 Hello, Rails! . . . . . . . . . . 2.3 Linking Pages Together . . . 2.4 What We Just Did . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 41 43 50 53 55 55 58 60 63 63 65 68 71 74 74 75 3 The Architecture of Rails Applications 3.1 Models, Views, and Controllers . . . . . . . . . . . . . . . . . . 3.2 Rails Model Support . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Action Pack: The View and Controller . . . . . . . . . . . . . . Introduction to Ruby 4.1 Ruby Is an Object-Oriented Language 4.2 Data Types . . . . . . . . . . . . . . . . 4.3 Logic . . . . . . . . . . . . . . . . . . . . 4.4 Organizing Structures . . . . . . . . . . 4.5 Marshaling Objects . . . . . . . . . . . 4.6 Pulling It All Together . . . . . . . . . . 4.7 Ruby Idioms . . . . . . . . . . . . . . . 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part II—Building an Application 5 The Depot Application 5.1 Incremental Development . . . . . . . . . . . . . . . . . . . . . 5.2 What Depot Does . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Let’s Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Task A: Creating the Application 6.1 Iteration A1: Creating the Products Maintenance Application 6.2 Iteration A2: Making Prettier Listings . . . . . . . . . . . . . . . 79 81 81 82 86 89 89 96 6 7 Task B: Validation and Unit Testing 103 7.1 Iteration B1: Validating! . . . . . . . . . . . . . . . . . . . . . . . 103 7.2 Iteration B2: Unit Testing of Models . . . . . . . . . . . . . . . 108 Task 8.1 8.2 8.3 8.4 C: Catalog Display Iteration C1: Creating the Catalog Listing . . . . Iteration C2: Adding a Page Layout . . . . . . . . Iteration C3: Using a Helper to Format the Price Iteration C4: Functional Testing of Controllers . 117 117 120 124 124 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 7: CONTENTS 7 9 Task 9.1 9.2 9.3 D: Cart Creation 129 Iteration D1: Finding a Cart . . . . . . . . . . . . . . . . . . . . 129 Iteration D2: Connecting Products to Carts . . . . . . . . . . . 130 Iteration D3: Adding a Button . . . . . . . . . . . . . . . . . . . 132 E: A Smarter Cart 139 Iteration E1: Creating a Smarter Cart . . . . . . . . . . . . . . 139 Iteration E2: Handling Errors . . . . . . . . . . . . . . . . . . . 144 Iteration E3: Finishing the Cart . . . . . . . . . . . . . . . . . . 146 F: Add a Dash of Ajax Iteration F1: Moving the Cart . . . . Iteration F2: Creating an Ajax-Based Iteration F3: Highlighting Changes . Iteration F4: Hiding an Empty Cart . Testing Ajax changes . . . . . . . . . 153 154 159 162 164 167 173 173 187 191 10 Task 10.1 10.2 10.3 11 Task 11.1 11.2 11.3 11.4 11.5 12 Task 12.1 12.2 12.3 ... Cart ... ... ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G: Check Out! Iteration G1: Capturing an Order . . . . . . . . . . . . . . . . . Iteration G2: Atom Feeds . . . . . . . . . . . . . . . . . . . . . . Iteration G3: Pagination . . . . . . . . . . . . . . . . . . . . . . 13 Task H: Sending Mail 197 13.1 Iteration H1: Sending Conﬁrmation E-mails . . . . . . . . . . 197 13.2 Iteration H2: Integration Testing of Applications . . . . . . . . 204 14 Task 14.1 14.2 14.3 14.4 15 Task 15.1 15.2 15.3 15.4 16 Task 16.1 16.2 16.3 I: Logging In Iteration I1: Adding Users . . . . . . . . . . . . . . . Iteration I2: Authenticating Users . . . . . . . . . . . Iteration I3: Limiting Access . . . . . . . . . . . . . . Iteration I4: Adding a Sidebar, More Administration J: Internationalization Iteration J1: Selecting the locale . . . . . Iteration J2: Translating the Store Front . Iteration J3: Translating Checkout . . . . Iteration J4: Add a Locale Switcher . . . . 211 211 220 225 228 233 234 236 243 249 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . K: Deployment and Production 253 Iteration K1: Deploying with Phusion Passenger and MySQL . 255 Iteration K2: Deploying Remotely with Capistrano . . . . . . . 260 Iteration K3: Checking Up on a Deployed Application . . . . . 266 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 8: CONTENTS 8 17 Depot Retrospective 271 17.1 Rails Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 17.2 Documenting What We Have Done . . . . . . . . . . . . . . . . 274 Part III—Rails In Depth 277 18 Finding Your Way Around Rails 279 18.1 Where things go . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 18.2 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . 287 19 Active Record 19.1 Deﬁning your Data . . . . . . . . . . . . . . . . . . . 19.2 Locating and Traversing Records . . . . . . . . . . . 19.3 Creating, Reading, Updating, and Deleting (CRUD) 19.4 Participating in the Monitoring Process . . . . . . . 19.5 Transactions . . . . . . . . . . . . . . . . . . . . . . . 293 293 298 301 317 324 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Action Dispatch and Action Controller 329 20.1 Dispatching Requests to Controllers . . . . . . . . . . . . . . . 329 20.2 Processing of Requests . . . . . . . . . . . . . . . . . . . . . . . 340 20.3 Objects and operations that span requests . . . . . . . . . . . 351 21 Action View 21.1 Using Templates . . . . . . . . . . . . . . . . . . . . 21.2 Form Helpers . . . . . . . . . . . . . . . . . . . . . . 21.3 Processing Forms . . . . . . . . . . . . . . . . . . . 21.4 Uploading Files to Rails Applications . . . . . . . . 21.5 Creating Your Own Helpers . . . . . . . . . . . . . 21.6 Reducing Maintenance with Layouts and Partials 361 361 366 369 371 374 381 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Caching 391 22.1 Page Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 22.2 Expiring Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 22.3 Fragment Caching . . . . . . . . . . . . . . . . . . . . . . . . . . 400 23 Migrations 23.1 Creating and Running Migrations . . . . . 23.2 Anatomy of a Migration . . . . . . . . . . . 23.3 Managing Tables . . . . . . . . . . . . . . . 23.4 Advanced Migrations . . . . . . . . . . . . 23.5 When Migrations Go Bad . . . . . . . . . . 23.6 Schema Manipulation Outside Migrations 407 407 410 414 418 423 424 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 9: CONTENTS 9 24 Non-Browser Applications 24.1 A Standalone Application Using Active Record . . . . . . . . . 24.2 A Library Function Using Active Support . . . . . . . . . . . . 24.3 A Remote Application Using Active Resource . . . . . . . . . . 427 427 428 433 25 Rails Dependencies 439 25.1 Rails Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . 439 26 Popular plugins 27 Replacement parts A B Links Bibliography Index 441 443 445 446 447 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 10: CONTENTS 10 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 11: Changes in the Beta Releases Beta 8—September 9 Rails 3.0 ﬁnal has shipped! Even better news: no API changes that affect the book were introduced in the process. In one case, namely in the use of an Action View helper from a standalone library, you will want to be using the ﬁnal release instead of any previous beta or release candidate, so please do upgrade now if you haven’t already. New with this beta are three new chapters completing the coverage of the externals of Rails. Caching covers how to effectively optimize your application by eliminating the overhead of re-computing results that rarely change. Migrations covers how to maintain your schemas. And ﬁnally, Non-Browser Applications shows you how to access some or all of Rails functions either locally or remotely. As we enter into the home stretch, your feedback becomes all the more important. There is an Report Erratum link at the bottom right of every page. Use it when you spot something, even if you aren’t sure! If you would like to start a discussion, the forum is a better place for that. Beta 7—August 25 We have a new release candidate of Rails, as well as an ofﬁcial release of Ruby 1.9.2. I’m pleased to report that once again, no changes were made to any Rails API that affect the book. Furthermore, the regression that in the ﬁrst release candidate which broke the ability to build the guides has been addressed. New with this beta is a chapter on Action View, which covers templates, helpers, layouts, and partials. At this point, all three parts of the Model/View/Controller architecture are covered. Next up will be a chapter on accessing Rails applications from outside of a web server, either directly via APIs or as a web service. As always, thanks for all of the wonderful feedback via the errata, forums, and other venues. At this time I would like to speciﬁcally thank Kim Shrier, Don Smith, mltsy, and Jason Catena. Prepared exclusively for Jared Rosoff Slide 12: BETA 6—JULY 27 12 Beta 6—July 27 The big news is that the release candidate for Rails has ofﬁcially shipped. The better news is that no API changes were made to Rails that affect the book. Hopefully at this point releases of Rails will be made more quickly, and the API will remain stable. New with this beta is a chapter on Action Dispatch and Action Controller, which covers both dispatching of requests to controllers, as well as controllers themselves. At this point, two of the three parts on the Model/View/Controller architecture are complete. Next up will be a chapter on Views. Once again, thanks for all of the wonderful feedback via the errata, forums, and other venues – keep it coming! Beta 5—June 28 As I write this, the release candidate which was originally due on June 8th has still not shipped, and we have decided to release a beta anyway. At the current time, the contents of the book work with beta 4 and with the latest version of Rails from github, but things could change between now and when the release candidate ships. The changes to Rails that affected this book in beta 4 were the requirement to specify the keyword ’new’ when creating a new application with the ’rails’ command, and the fact that Rails 3.0 no longer works on Ruby 1.9.1. Ruby 1.9.2 preview 3, however, has come out and Rails 3.0 works just ﬁne on it. This beta has been updated to reﬂect these changes. This beta also adds a chapter dedicated to Active Record, a topic which covered three chapters in edition 3. The content has been updated to reﬂect Rails 3 APIs, and in particular ARel functionality. The content has been streamlined to focus only on APIs that everybody needs to know, as well as content that was adequately covered in Part II. It also reads less like a reference manual, and more like a guide. Feedback welcome. In particular, please let me know if something you feel is essential was not covered. Again, thanks for all of the excellent errata. At this point, we are up to over 300 errata comments from over 80 individuals. I’d like to speciﬁcally thank Seth Arnold, David Hadley, Will Bowlin, Victor Marius Costan, Kristian Riiber Mandrup, Joe Straitiff, and Andy Brice. Beta 4—May 26 This beta adds two chapters. The ﬁrst recaps what was learned in part 2: model, view, controller, conﬁguration, testing, and deployment. It then contin- Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 13: BETA 3—MAY 11 13 ues with an explanation on how to generate documentation for your application. Chapter 18 is also new with this beta: it goes directory by directory through your Rails application, describing what goes into each. You will see how to generate documentation for Rails itself, how to build a Rake task, more information on conﬁguration options and naming conventions. This all sets the stage for the chapters that follow. The Rails team is in the process of deprecating conﬁg.log_path, but at the present time has not settled on its replacement. Furthermore this property is broken in Rails 3 beta 3. What you see in Section 16.3, Dealing with Log Files, on page 267 reﬂects what currently works, which may not necessarily be what will be supported in the ﬁnal release. Beta 3—May 11 This beta adds a deployment chapter which takes you through the installation, conﬁguration, and usage of a number of tools: Apache, Capistrano, MySQL, and Passenger; as well as (mildly) deeper usage of Git and Bundler. There’s not been another beta of Rails yet, so this is just a FYI at this point, but usage of {{name}} syntax in i18n strings will be deprecated; the preferred syntax is now %{name}. As always thanks for all of the wonderful feedback via the errata, forums, and other venues – keep it coming! Beta 2—May 3 Thanks for all of the excellent feedback. To date we’ve gotten over 100 comments from over 30 individuals. Special thanks go out to Trung LE, David Hadley, Manuel E Vidaurre Arenas, Wayne Conrad, and Steve Nicholson. A lot of the changes you’ll see in this second beta are the result of this input. Please keep it up, as every comment helps us make this book better! This new release adds coverage of sending mail and integration testing in the new chapter “Task H: Sending Mail.” You’ll learn how to send mail, how to function test mail, and how to integration test an end-to-end scenario spanning adding a product to a cart to the sending of a conﬁrmation email. Only one change to Rails affects the book this go around: Rails will be changing the way that I18N and HTML safe strings interact. The text in the book has been partially updated to reﬂect the new direction, but will continue to work with Beta 3. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 14: BETA 2—MAY 3 14 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 15: Preface to the Fourth Edition When Dave asked me to join as a coauthor of the third edition of this book, I was thrilled. After all, it was from the ﬁrst printing of the ﬁrst edition of this book that I had learned Rails. Dave and I also have much in common. Although he prefers Emacs and Mac OS X and my preferences tend toward Vim and Ubuntu, we both share a love for the command line and getting our ﬁngers dirty with code—starting with tangible examples before diving into heavy theory. Since the time the third edition was published (and, in fact, since the ﬁrst, second and third editions), much has changed. Rails is in the process of being signiﬁcantly refactored, mostly internally. A number of features that were used in previous examples have been initially deprecated and subsequently removed. New features have been added, and much experience has been obtained as to what the best practices are for using Rails. Rails also works on Ruby 1.9, though some of the examples had to be modiﬁed in order for this to work. Additionally, Rails has exploded from being a popular framework to an active and vibrant ecosystem, complete with many popular plugins and deep integration into third party tools. In the process, Rails has become mainstream, attracting a more diverse set of developers to the framework. This has led to a reorganization of the book. Many newcomers to Rails have not had the pleasure of being introduced to Ruby, so this section has been promoted from an appendix to a chapter in the ﬁrst section. We follow this section with a step-by-step walk through of building a real application, which has been updated and streamlined to focus on current best practices. But the biggest change is in the ﬁnal section: as it is no longer practical to cover the entire ecosystem of Rails given both its breadth and rate of change, what this section is now focused on is to provide an overall perspective of the landscape, enabling you, the reader, to know what to look for and where to ﬁnd plugins and related tools to address common needs that go far beyond what the framework itself contains. Prepared exclusively for Jared Rosoff Slide 16: PREFACE TO THE FOUR TH EDITION 16 In short, this book needed to adapt. Once again. Sam Ruby April 2010 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 17: Acknowledgements You’d think that producing a new 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 difﬁcult to tell exactly, but our impression is that creating each edition of Agile Web Development with Rails took about as much effort as the ﬁrst edition. Rails is constantly evolving and, as it does, so has this book. Parts of the Depot application were rewritten several times, and all of the narrative was updated. The emphasis on REST and the avoidance of features as they become deprecated have repeatedly changed the structure of the book as what was once hot became just lukewarm. So, this book would not exist without a massive amount of help from the Ruby and Rails communities. Each edition of this book has been released as a beta book: early versions were posted as PDFs, and people made comments online. And comment they did: more than 1,200 suggestions and bug reports were posted. The vast majority ended up being incorporated, making this book immeasurably more useful than it would have been. Thank you all, both for supporting the beta book program and for contributing so much valuable feedback. The Rails core team has been incredibly helpful, answering questions, checking out code fragments, and ﬁxing bugs. A big thank you to the following: Scott Barron (htonl), Jamis Buck (minam), Thomas Fuchs (madrobby), Jeremy Kemper (bitsweat), Yehuda Katz (wycats), Michael Koziarski (nzkoz), Marcel Molina Jr, (noradio), Rick Olson (technoweenie), Nicholas Seckar (Ulysses), Sam Stephenson (sam), Tobias Lütke (xal), José Valim (josevalim), and Florian Weber (csshsh) We’d like to thank the folks who contributed the specialized chapters to the book: Leon Breedt, Mike Clark, James Duncan Davidson, Justin Gehtland, and Andreas Schwarz. Prepared exclusively for Jared Rosoff Slide 18: ACKNOWLEDGEMENTS 18 From Sam Ruby This effort has turned out to be both harder and more rewarding than I would have ever anticipated. It’s been harder in that Rails has changed so much and there has been so much to learn (in terms of Rails 2.0, in terms of SQLite 3, and also in terms of working with a different publisher, operating system, and toolset). But I can’t begin to express how much I like the beta book program— the readers who this book has attracted so far have been great, and their comments, questions, and feedback have been most appreciated. Sam Ruby April 2010 rubys@intertwingly.net From Dave Thomas I keep promising myself that each book will be the last, if for no other reason than each takes me away from my family for months at a time. Once again: Juliet, Zachary, and Henry—thank you for everything. Dave Thomas November 2006 dave@pragprog.com Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 19: In this chapter, we’ll see • • • • What rails is, agile practices, who the book is for, and how to read the book. Introduction Ruby on Rails is a framework that makes it easier to develop, deploy, and maintain web applications. During the months that followed its initial release, Rails went from being an unknown toy to being a worldwide phenomenon and, more important, it has become the framework of choice for the implementation of a wide range of so-called Web 2.0 applications. Why is that? Rails Simply Feels Right First, a large number of developers 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 was easier. But easy on its own doesn’t cut it. We’re talking about professional developers writing real-world websites. They wanted to feel that the applications they were developing would stand the test of time—that they were designed and implemented using modern, professional techniques. So, these developers dug into Rails and discovered it wasn’t just a tool for hacking out sites. For example, all Rails applications are implemented using the Model-ViewController (MVC) architecture. Java developers are used to frameworks such as Tapestry and Struts, which are based on MVC. But Rails takes MVC further: when you develop in Rails, you start with a working application, there’s a place for each piece of code, and all the pieces of your application interact in a standard way. Professional programmers write tests. And again, Rails delivers. All Rails applications have testing support baked right in. As you add functionality to the code, Rails automatically creates test stubs for that functionality. The framework makes it easy to test applications, and as a result, Rails applications tend to get tested. Prepared exclusively for Jared Rosoff Slide 20: RAILS SIMPLY FEELS RIGHT 20 Rails applications are written in Ruby, a modern, object-oriented scripting language. Ruby is concise without being unintelligibly terse—you can express ideas naturally and cleanly in Ruby code. This leads to programs that are easy to write and (just as important) are easy to read months later. Rails takes Ruby to the limit, extending it in novel ways that make a programmer’s life easier. This makes our programs shorter and more readable. It also allows us to perform tasks that would normally be done in external conﬁguration ﬁles inside the codebase instead. This makes it far easier to see what’s happening. The following code deﬁnes the model class for a project. Don’t worry about the details for now. Instead, just think about how much information is being expressed in a few lines of code. class Project < ActiveRecord::Base belongs_to :portfolio has_one :project_manager has_many :milestones has_many :deliverables, :through => :milestones validates validates validates end :name, :description, :presence => true :non_disclosure_agreement, :acceptance => true :short_name, :uniqueness => true Two other philosophical underpinnings keep Rails code short and readable: DRY and convention over conﬁguration. DRY stands for don’t repeat yourself : every piece of knowledge in a system should be expressed in just one place. Rails uses the power of Ruby to bring that to life. You’ll ﬁnd very little duplication in a Rails application; you say what you need to say in one place—a place often suggested by the conventions of the MVC architecture—and then move on. For programmers used to other web frameworks, where a simple change to the schema could involve them in half a dozen or more code changes, this was a revelation. Convention over conﬁguration is crucial, too. It means that Rails has sensible defaults for just about every aspect of knitting together your application. Follow the conventions, and you can write a Rails application using less code than a typical Java web application uses in XML conﬁguration. If you need to override the conventions, Rails makes that easy, too. Developers coming to Rails found something else, too. Rails isn’t playing catchup with the new de facto web standards; it’s helping deﬁne them. And Rails makes it easy for developers to integrate features such as Ajax and RESTful interfaces into their code, because support is built in. (And if you’re not familiar with Ajax and REST interfaces, never fear—we’ll explain them later in the book.) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 21: RAILS IS AGILE 21 Developers are worried about deployment, too. They found that with Rails you can deploy successive releases of your application to any number of servers with a single command (and roll them back equally easily should the release prove to be somewhat less than perfect). Rails was extracted from a real-world, commercial application. It turns out that the best way to create a framework is to ﬁnd the central themes in a speciﬁc application and then bottle them up in a generic foundation of code. When you’re developing your Rails application, you’re 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. Rails Is Agile 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 • Individuals and interactions over processes and tools • Working software over comprehensive documentation • Customer collaboration over contract negotiation • Responding to change over following a plan Rails is all about individuals and interactions. There are no heavy toolsets, no complex conﬁgurations, and no elaborate processes. There are just small groups of developers, their favorite editors, and chunks of Ruby code. This leads to transparency; what the developers do is reﬂected immediately in what the customer sees. It’s an intrinsically interactive process. Rails doesn’t denounce documentation. Rails makes it trivially easy to create HTML documentation for your entire codebase. But the Rails development process isn’t driven by documents. You won’t ﬁnd 500-page speciﬁcations at the heart of a Rails project. Instead, you’ll ﬁnd a group of users and developers jointly exploring their need and the possible ways of answering that need. You’ll ﬁnd solutions that change as both the developers and the users become more experienced with the problems they’re trying to solve. You’ll ﬁnd 1. http://agilemanifesto.org/. Dave Thomas was one of the seventeen authors of this document. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 22: WHO THIS BOOK IS FOR 22 a framework that delivers working software early in the development cycle. This software may be rough around the edges, but it lets the users start to get a glimpse of what you’ll be delivering. In this way, Rails encourages customer collaboration. When customers see just how quickly a Rails project can respond to change, they start to trust that the team can deliver what’s required, not just what has been requested. Confrontations are replaced by “What if?” sessions. That’s all tied to the idea of being able to respond to change. The strong, almost obsessive, way that Rails honors the DRY principle means that changes to Rails applications impact a lot less code than the same changes would in other frameworks. And since Rails applications are written in Ruby, where concepts can be expressed accurately and concisely, changes tend to be localized and easy to write. The deep emphasis on both unit and functional testing, along with support for test ﬁxtures 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-racking. 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 applications this way: working alongside your customers and jointly determining priorities and solutions to problems. Then, as you read the deeper reference material that follows in Section III, see how the underlying structure of Rails can enable you to meet your customers’ needs faster and with less ceremony. One last point about agility and Rails: although it’s probably unprofessional to mention this, think how much fun the coding will be. Who This Book Is For Programmers looking to build and deploy web-based applications. This includes application programmers who are new to Rails (and perhaps even new to Ruby) and ones who are familiar with the basics but want a more in-depth understanding of Rails. Some familiarity with HTML, Cascading Style Sheets (CSS), and JavaScript – in other words, the ability to view-source on web pages – is presumed. A detailed knowledge of these subjects is not required. How To Read This Book The ﬁrst part of this book makes sure that you are ready: by the time you are done with it, you will have been introduced to Ruby (the language), have been Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 23: HOW TO READ THIS BOOK 23 exposed to an overview of Rails itself, have both Ruby and Rails installed, and have veriﬁed this installation with a simple example. The next part takes you through the concepts behind Rails via an extended example—we build a simple online store. It doesn’t take you one by one through each component of Rails, here is a chapter on models, here is a chapter on views, and so forth. These components are designed to work together, and each of the chapters in this section tackle a speciﬁc set of related tasks that involve a number of these components working together. Most folks seem to enjoy building the application along with the book. If you don’t want to do all that typing, you can cheat and download the source code (a compressed tar archive or a zip ﬁle).2 The third part of the book, starting on page 278, surveys entire Rails ecosystem. This starts with the functions and facilities of Rails that you will now be familiar with. It then covers a number of key dependencies that the Rails framework makes use of that contribute directly to the overall functionality that the Rails framework delivers. Then there is a survey of a number of popular plugins that augment the Rails framework and make Rails a platform rather than merely a framework. Finally, there is a list of components that can be used as replacements for components of the framework that either are core or defaults that have been selected for you. This makes Rails an open ecosystem rather than merely a platform. Along the way, you’ll see various conventions we’ve adopted. Live Code Most of the code snippets we show come from full-length, running examples that you can download. To help you ﬁnd your way, if a code listing can be found in the download, there’ll be a bar above the snippet (just like the one here). Download work/demo1/app/controllers/say_controller.rb class SayController < ApplicationController def hello end def goodbye end end This contains the path to the code within the download. If you’re reading the ebook version of this book and your ebook viewer supports hyperlinks, you can click the bar, and the code should appear in a browser window. Some browsers (such as Safari) will mistakenly try to interpret 2. http://pragprog.com/titles/rails4/source_code has the links for the downloads. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 24: HOW TO READ THIS BOOK 24 some of the templates as HTML. If this happens, view the source of the page to see the real source code. And in some cases involving the modiﬁcation of an existing ﬁle where the lines to be changed may not be immediately obvious, you will also see some helpful little triangles on the left of the lines that you will need to change. Two such lines are indicated in the previous code. Ruby Tips Although you need to know Ruby to write Rails applications, we realize that many folks reading this book will be learning both Ruby and Rails at the same time. Chapter 4, Introduction to Ruby, on page 63, is a (very) brief introduction to the Ruby language. When we use a Ruby-speciﬁc construct for the ﬁrst time, we’ll cross-reference it to that chapter. For example, this paragraph contains a gratuitous use of :name, a Ruby symbol. In the margin, you’ll see an indication that symbols are explained on page 64. David Says... Every now and then you’ll come across a David Says... sidebar. Here’s where David Heinemeier Hansson gives you the real scoop on some particular aspect of Rails—rationales, tricks, recommendations, and more. Because he’s the fellow who invented Rails, these are the sections to read if you want to become a Rails pro. Joe Asks... Joe, the mythical developer, sometimes pops up to ask questions about stuff we talk about in the text. We answer these questions as we go along. This book isn’t meant to be a reference manual for Rails. Our experience is that reference manuals are not the way most people learn. Instead, we show most of the modules and many of their methods, either by example or narratively in the text, in the context of how these components are used and how they ﬁt together. Nor do we have hundreds of pages of API listings. There’s a good reason for this—you get that documentation whenever you install Rails, and it’s guaranteed to be more up-to-date than the material in this book. If you install Rails using RubyGems (which we recommend), simply start the gem documentation server (using the command gem server), and you can access all the Rails APIs by pointing your browser at http://localhost:8808. You will ﬁnd out on page 281 how to build even more documentation and guides. Let’s get started! The ﬁrst steps are to install Ruby and Rails and to verify the installation with a simple demonstration. :name ֒ page 64 → Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 25: HOW TO READ THIS BOOK 25 “Agile Web Development with Rails...I found it in our local bookstore, and it seemed great!” —Dave’s mum Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 26: HOW TO READ THIS BOOK 26 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 27: Part I Getting Started Prepared exclusively for Jared Rosoff Slide 28: HOW TO READ THIS BOOK 28 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 29: In this chapter, we’ll see • installing Ruby, RubyGems, SQLite3, and Rails, • development environments and tools. Chapter 1 Installing Rails In Part I of this book, we will get an introduction to both the Ruby language and the Rails framework. But we can’t get anywhere until we have installed both and veriﬁed that both are operating correctly. To get Rails running on your system, you’ll need the following: • A Ruby interpreter. Rails is written in Ruby, and you’ll be writing your applications in Ruby too. Rails 3.0 requires Ruby version 1.8.7 or Ruby 1.9.2. It is known not to work on Ruby versions 1.8.6 and Ruby 1.9.1. • The Ruby packaging system, namely RubyGems. This edition is based on RubyGems version 1.3.6. • Ruby on Rails. This beta book was written using Rails version 3 (speciﬁcally Rails 3.0.0 at the current time). • Some libraries, depending on the operating system. • A database. We’re using SQLite 3 in this book. For a development machine, that’s about all you’ll need (apart from an editor, and we’ll talk about editors separately). However, if you are going to deploy your application, you will also need to install a production web server (as a minimum) along with some support code to let Rails run efﬁciently. We have a whole chapter devoted to this, starting on page 253, so we won’t talk about it more here. So, how do you get all this installed? It depends on your operating system.... 1.1 Installing on Windows On Windows, start by installing Ruby. The easiest way to do this on Windows is via the RubyInstaller1 package. Be sure to download a version of Ruby that 1. http://rubyinstaller.org/ Prepared exclusively for Jared Rosoff Slide 30: INSTALLING ON WINDOWS 30 is 1.8.7 or later. The examples in this book have been tested with Ruby 1.8.7 (2010-01-10 patchlevel 249). Base installation is a snap. After you download, select Run → Next, click “I accept the License” (after reading it carefully of course), click Next, check “Add Ruby executables to your PATH”, then Install → Finish. Now open a command prompt by selecting the Windows Start → Run..., enter cmd, and click OK. RubyInstaller includes RubyGems, but it is important to verify that you are running with version 1.3.6 or later. You can verify the version of RubyGems with the following command: gem -v Should this return 1.3.5 or earlier, you can upgrade to the latest version of RubyGems with the following commands: gem update --system gem uninstall rubygems-update Next, install SQLite32 . Download and unzip two precompiled binaries for Windows: • command-line program for accessing and modifying SQLite databases • DLL of the SQLite library without the TCL bindings Copy the ﬁles inside these zips to your C:\Ruby\bin directory. The results should look something like this: Directory of C:\Ruby\bin 01/05/2010 01/05/2010 01/05/2010 06:30 PM 06:30 PM 06:31 PM 3 File(s) 3,744 sqlite3.def 511,383 sqlite3.dll 530,762 sqlite3.exe 1,045,889 bytes Now install the ruby bindings to SQLite3, and the Rails beta itself: gem install sqlite3-ruby gem install rails --pre At this point, you’re up and running. But, before continuing on, you should know one important fact: the example sessions in this book are based on execution on a Mac. Although the ruby and rails commands are exactly the same, the Unix commands are different. This book uses only two Unix commands. The ﬁrst is ls -a, for which the Windows equivalent is dir/w. The second is rm, for which the Windows equivalent is erase. 2. http://www.sqlite.org/download.html Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 31: INSTALLING ON MAC OS X 31 We also will be optionally making use of the curl command on page 190. You can download this from curl.haxx.se3 . OK, you Windows users are done. You can skip forward to Section 1.4, Choosing a Rails Version, on page 33. See you there. 1.2 Installing on Mac OS X While versions of OS X since 10.4.6 (Tiger) have included a version of Ruby, and starting with of OS X 10.5 (Leopard) have included Rails itself, the versions that are included generally are older versions of these components, and you have some upgrading to do. Tiger users will also need to upgrade SQLite 3. This can be done via compiling from source (which sounds scarier than it is). You can ﬁnd the instructions to do so at http://www.sqlite.org/download.html. An alternate way to install SQLite 3 is via the popular MacPorts package4 . Although the instructions also look a bit daunting, the individual steps are pretty straightforward: run an installer, run another installer, add two lines to a ﬁle, run yet another installer, and then issue a single command. This may not turn out to be easier than compiling from source for yourself, but many ﬁnd the investment to be worth it because it makes installing further packages as easy as a single command. So if you have MacPorts installed, let’s use it to upgrade the version of SQLite 3 on your machine: sudo port upgrade sqlite3 Next, users of OS X prior to Snow Leopard will need to upgrade their version of Ruby to 1.8.7. Again, this can be done with MacPorts: sudo port install ruby All OS X users can use the following commands to update their system the rest of the way. If you just installed MacPorts, be sure to take heed of the important note to open a new shell and verify via the env command that your path and variable changes are in effect. If you haven’t already done so, install Apple’s Xcode Developer Tools (version 3.2 or later for Leopard, 2.4.1 or later for Tiger), found at the Apple Developer Connection site or on your Mac OS X installation CDs/DVD. sudo sudo sudo sudo gem gem gem gem update --system uninstall rubygems-update install rails --pre install sqlite3-ruby 3. http://curl.haxx.se/download.html 4. http://www.macports.org/install.php Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 32: INSTALLING ON LINUX 32 At this point, you are likely to have two versions of Ruby on your system, and it is important to verify that you are running the correct version of related tools. You can do that using the following command: for cmd in ruby irb gem rake; do which $cmd; done All you need to do here is verify that each command is found in the same path, typically /opt/local/bin. If you are ﬁnding different tools at different paths, verify that your PATH environment variable is correct and/or reinstall the tool that doesn’t match the desired version of Ruby. You can reinstall RubyGems using sudo port install rb-rubygems, or by following the instructions on the RubyGems site5 (steps 1-3 at the bottom of the page; You will likely need to preﬁx the ruby setup.rb command with sudo). You can reinstall rake with the following command: sudo gem install rake The following step is rarely necessary, but it can be helpful if things go wrong. You can verify which version of SQLite 3 your sqlite3-ruby interface is bound to by running the following as a stand-alone program: require 'rubygems' require 'sqlite3' tempname = "test.sqlite#{3+rand}" db = SQLite3::Database.new(tempname) puts db.execute('select sqlite_version()' ) db.close File.unlink(tempname) OK, you OS X users are done. You can skip forward to join the Windows users in Section 1.4, Choosing a Rails Version, on the following page. See you there. 1.3 Installing on Linux Start with your platform’s native package management system, be it aptitude, dpkg, portage, rpm, rug, synaptic, up2date, or yum. The ﬁrst step is to install the necessary dependencies. The following instructions are for Ubuntu 10.04, Lucid Lynx; you can adapt them as necessary for your installation: sudo aptitude install build-essential libopenssl-ruby libfcgi-dev sudo aptitude install ruby irb rubygems ruby1.8-dev sudo aptitude install sqlite3 libsqlite3-dev Before proceeding, it is important to verify that the version of RubyGems is at least 1.3.6. You can ﬁnd out the version by issuing gem -v. How to upgrade your version of RubyGems is described in the sidebar on the next page. 5. http://rubygems.org/pages/download Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 33: CHOOSING A RAILS VERSION 33 Upgrading RubyGems on Linux There are many different ways to upgrade RubyGems. Unfortunately, depending on which version of RubyGems you have installed and what distribution you are running, not all of the ways work. Be persistent. Try each of the following until you ﬁnd one that works for you. • Using the gem update system: sudo gem update --system • Using the gem designed to update troublesome systems: sudo gem install rubygems-update sudo update_rubygems • Using setup.rb, which is provided with rubygems-update: sudo gem install rubygems-update cd /var/lib/gems/1.8/gems/rubygems-update-* sudo ruby setup.rb • Finally, installing from source: wget http://rubyforge.org/frs/download.php/69365/rubygems-1.3.6.tgz tar xzf rubygems-1.3.6.tgz cd rubygems-1.3.6 sudo ruby setup.rb Next we will install the Rails framework and the SQLite3 database. sudo gem install rails --pre sudo gem install sqlite3-ruby On the last command, you will be prompted to select which gem to install for your platform. Simply select the latest (topmost) gem that contains the word ruby in parentheses, and a native extension will be built for you. At this time, try the command rails -v. If it can’t ﬁnd the rails command, you may need to add /var/lib/gems/1.8/bin to your PATH environment variable. You can do this by adding a line to your .bashrc ﬁle: export PATH=/var/lib/gems/1.8/bin:$PATH At this point, we’ve covered Windows, Mac OS X, and Linux. Instructions after this point are common to all three operating systems. 1.4 Choosing a Rails Version The previous instructions helped you install the latest version of Rails. But occasionally you might not want to run with the latest version. For example, Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 34: SETTING UP YOUR DEVELOPMENT ENVIRONMENT 34 you might want to run the version of Rails that matches this version used to develop this book so that you can be absolutely conﬁdent that the output and examples exactly match. Or perhaps you are developing on one machine but intending to deploy on another machine that contains a version of Rails that you don’t have any control over. If either of these situations applies to you, you need to be aware of a few things. For starters, you can ﬁnd out all the versions of Rails you have installed using the gem command: gem list --local rails You can also verify what version of Rails you are running as the default by using the rails --version command. It should return 3.0.0 or later. Installing another version of Rails is also done via the gem command. Depending on your operating system, you might need to preface the command with sudo. gem install rails --version 3.0.0 Now, having multiple versions of Rails wouldn’t do anybody any good unless there were a way to pick one. As luck would have it, there is. On any rails command, you can control which version of Rails is used by inserting the full version number surrounded by underscores before the ﬁrst parameter of the command: rails _3.0.0_ --version This is particularly handy when you create a new application, because once you create an application with a speciﬁc version of Rails, it will continue to use that version of Rails—even if newer versions are installed on the system— until you decide it is time to upgrade. To upgrade, simply update the version number in the Gemﬁle that is in the root directory of your application, and run bundle install. We will cover the bundler on page 439. 1.5 Setting Up Your Development Environment The day-to-day business of writing Rails programs is pretty straightforward. Everyone works differently; here’s how we work. The Command Line We do a lot of work at the command line. Although there are an increasing number of GUI tools that help generate and manage a Rails application, we ﬁnd the command line is still the most powerful place to be. It’s worth spending a little while getting familiar with the command line on your operating system. Find out how to use it to edit commands that you’re typing, how to search Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 35: SETTING UP YOUR DEVELOPMENT ENVIRONMENT 35 Where’s My IDE? If you’re coming to Ruby and Rails from languages such as C# and Java, you may be wondering about IDEs. After all, we all know that it’s impossible to code modern applications without at least 100MB of IDE supporting our every keystroke. For you enlightened ones, here’s the point in the book where we recommend you sit down—ideally propped up on each side by a pile of framework references and 1,000-page Made Easy books. There are no fully-ﬂedged IDEs for Ruby or Rails (although some environments come close). Instead, most Rails developers use plain old editors. And it turns out that this isn’t as much of a problem as you might think. With other, less expressive languages, programmers rely on IDEs to do much of the grunt work for them: IDEs do code generation, assist with navigation, and compile incrementally to give early warning of errors. With Ruby, however, much of this support just isn’t necessary. Editors such as TextMate give you 90 percent of what you’d get from an IDE but are far lighter weight. Just about the only useful IDE facility that’s missing is refactoring support. for and edit previous commands, and how to complete the names of ﬁles and commands as you type. So-called tab completion is standard on Unix shells such as Bash and zsh. It allows you to type the ﬁrst few characters of a ﬁlename, hit Tab , and have the shell look for and complete the name based on matching ﬁles. Version Control We keep all our work in a version control system (currently Git). We make a point of checking a new Rails project into Git when we create it and committing changes once we have passing tests. We normally commit to the repository many times an hour. If you’re working on a Rails project with other people, consider setting up a continuous integration (CI) system. When anyone checks in changes, the CI system will check out a fresh copy of the application and run all the tests. It’s a simple way to ensure that accidental breakages get immediate attention. You can also set up your CI system so that your customers can use it to play with the bleeding-edge version of your application. This kind of transparency is a great way of ensuring that your project isn’t going off the tracks. See Chapter 27, Replacement parts, on page 443 for suggestions. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 36: SETTING UP YOUR DEVELOPMENT ENVIRONMENT 36 Editors We write our Rails programs using a programmer’s editor. We’ve found over the years that different editors work best with different languages and environments. For example, Dave originally wrote this chapter using Emacs, because he thinks that its Filladapt mode is unsurpassed when it comes to neatly formatting XML as he types. Sam updated the chapter using Vim. But many think that neither Emacs nor Vim is ideal for Rails development and prefer to use TextMate. Although the choice of editor is a personal one, here are some suggestions of features to look for in a Rails editor: • Support for syntax highlighting of Ruby and HTML. Ideally support for .erb ﬁles (a Rails ﬁle format that embeds Ruby snippets within HTML). • Support of automatic indentation and reindentation of Ruby source. This is more than an aesthetic feature: having an editor indent your program as you type is the best way of spotting bad nesting in your code. Being able to reindent is important when you refactor your code and move stuff. (TextMate’s ability to reindent when it pastes code from the clipboard is very convenient.) • Support for insertion of common Ruby and Rails constructs. You’ll be writing lots of short methods, and if the IDE creates method skeletons with a keystroke or two, you can concentrate on the interesting stuff inside. • Good ﬁle navigation. As you’ll see, Rails applications are spread across many ﬁles: a newly created Rails application enters the world containing forty-six ﬁles spread across thirty-four directories. That’s before you’ve written a thing.... You need an environment that helps you navigate quickly between these. You’ll add a line to a controller to load up a value, switch to the view to add a line to display it, and then switch to the test to verify you did it all right. Something like Notepad, where you traverse a File Open dialog box to select each ﬁle to edit, just won’t cut it. We prefer a combination of a tree view of ﬁles in a sidebar, a small set of keystrokes that help us ﬁnd a ﬁle (or ﬁles) in a directory tree by name, and some built-in smarts that know how to navigate (say) between a controller action and the corresponding view. • Name completion. Names in Rails tend to be long. A nice editor will let you type the ﬁrst few characters and then suggest possible completions to you at the touch of a key. We hesitate to recommend speciﬁc editors because we’ve used only a few in earnest and we’ll undoubtedly leave someone’s favorite editor off the list. Nevertheless, to help you get started with something other than Notepad, here are some suggestions: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 37: SETTING UP YOUR DEVELOPMENT ENVIRONMENT 37 • The Ruby and Rails editor of choice on Mac OS X is TextMate (http:// macromates.com/). • Xcode 3.0 on Mac OS X has an Organizer that provides much of what you might need. A tutorial that will get you started with Rails on Leopard is available at http://developer.apple.com/tools/developonrailsleopard.html. • For those who would otherwise like to use TextMate but happen to be using Windows, E-TextEditor (http://e-texteditor.com/) provides “The Power of TextMate on Windows.” • Aptana RadRails (http://www.aptana.com/rails/) is an integrated Rails development environment that runs in Aptana Studio and Eclipse. It runs on Windows, Mac OS X, and Linux. It won an award for being the best open source developer tool based on Eclipse in 2006, and Aptana became the home for the project in 2007. • NetBeans IDE 6.5 (http://www.netbeans.org/features/ruby/index.html) sup-ports Windows, Mac OS X, Solaris, and Linux. It’s available in a download bundle with Ruby support or as a Ruby pack that can be downloaded later. In addition to speciﬁc support for Rails 2.0, Rake targets, and database migrations, it supports a Rails code generator graphical wizard and quick navigation from a Rails action to its corresponding view. • jEdit (http://www.jedit.org/) is a fully featured editor with support for Ruby. It has extensive plug-in support. • Komodo (http://www.activestate.com/Products/Komodo/) is ActiveState’s IDE for dynamic languages, including Ruby. • RubyMine (http://www.jetbrains.com/ruby/features/index.html) is a commercial IDE for Ruby, and is available for free to qualiﬁed educational and open source projects. Runs on Windows, Mac OSX, and Linux. Ask experienced developers who use your kind of operating system which editor they use. Spend a week or so trying alternatives before settling in. The Desktop We’re not going to tell you how to organize your desktop while working with Rails, but we will describe what we do. Most of the time, we’re writing code, running tests, and poking at an application in a browser. So, our main development desktop has an editor window and a browser window permanently open. We also want to keep an eye on the logging that’s generated by the application, so we keep a terminal window open. In it, we use tail -f to scroll the contents of the log ﬁle as it’s updated. We Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 38: RAILS AND DATABASES 38 Creating Your Own Rails API Documentation You can create your own local version of the consolidated Rails API documentation. Just type the following commands at a command prompt: rails_apps> rails new dummy_app rails_apps> cd dummy_app dummy_app> rake doc:rails The last step takes a while. When it ﬁnishes, you’ll have the Rails API documentation in a directory tree starting at doc/api. We suggest moving this folder to your desktop and then deleting the dummy_app tree. To view the Rails API documentation, open the location doc/api/index.html with your browser. normally run this window with a very small font so it takes up less space—if we see something interesting ﬂash by, we zoom it up to investigate. We also need access to the Rails API documentation, which we view in a browser. In the introduction, we talked about using the gem server command to run a local web server containing the Rails documentation. This is convenient, but it unfortunately splits the Rails documentation across a number of separate documentation trees. If you’re online, you can use http://api.rubyonrails.org to see a consolidated view of all the Rails documentation in one place. 1.6 Rails and Databases The examples in this book were written using SQLite 3 (version 3.6.16 or thereabouts). If you want to follow along with our code, it’s probably simplest if you use SQLite 3 too. If you decide to use something else, it won’t be a major problem. You may have to make minor adjustments to any explicit SQL in our code, but Rails pretty much eliminates database-speciﬁc SQL from applications. If you want to connect to a database other than SQLite 3, Rails also works with DB2, MySQL, Oracle, Postgres, Firebird, and SQL Server. For all but SQLite 3, you’ll need to install a database driver, a library that Rails can use to connect to and use your database engine. This section contains links to instructions to get that done. The database drivers are all written in C and are primarily distributed in source form. If you don’t want to bother building a driver from source, take a careful look at the driver’s website. Many times you’ll ﬁnd that the author also distributes binary versions. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 39: WHAT WE JUST DID 39 If you can’t ﬁnd a binary version or if you’d rather build from source anyway, you’ll need a development environment on your machine to build the library. Under Windows, this means having a copy of Visual C++. Under Linux, you’ll need gcc and friends (but these will likely already be installed). Under OS X, you’ll need to install the developer tools (they come with the operating system but aren’t installed by default). You’ll also need to install your database driver into the correct version of Ruby. If you installed your own copy of Ruby, bypassing the built-in one, it is important to remember to have this version of Ruby ﬁrst in your path when building and installing the database driver. You can use the command which ruby to make sure you’re not running Ruby from /usr/bin. The following are the available database adapters and the links to their respective home pages: DB2 Firebird MySQL Oracle Postgres SQL Server SQLite http://raa.ruby-lang.org/project/ruby-db2 or http://rubyforge.org/projects/rubyibm http://rubyforge.org/projects/ﬁreruby/ http://www.tmtm.org/en/mysql/ruby http://rubyforge.org/projects/ruby-oci8 http://rubyforge.org/projects/ruby-pg http://github.com/rails-sqlserver http://rubyforge.org/projects/sqlite-ruby A pure-Ruby version of the Postgres adapter is available. Download postgres-pr from the Ruby-DBI page at http://rubyforge.org/projects/postgres-pr. MySQL and SQLite adapters are also available for download as RubyGems (mysql and sqlite3-ruby, respectively). 1.7 What We Just Did • We installed (or upgraded) the Ruby language. • We installed (or upgraded) the Rails framework. • We installed (or upgraded) the SQLite3 database. • We selected an editor. • We (optionally) selected a version control system. Now that we have Rails installed, let’s use it. On to the next chapter where we create our ﬁrst application. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 40: WHAT WE JUST DID 40 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 41: In this chapter, we’ll see • • • • • • creating a new application, starting the server, accessing the server from a browser, producing dynamic content, adding hypertext links, and passing data from the controller to the view Chapter 2 Instant Gratiﬁcation Let’s write a simple application to verify we’ve got Rails snugly installed on our machines. Along the way, we’ll get a peek at the way Rails applications work. 2.1 Creating a New Application When you install the Rails framework, you also get a new command-line tool, rails, which is used to construct each new Rails application that you write. Why do we need a tool to do this? Why can’t we just hack away in our favorite editor and create the source for our application from scratch? Well, we could just hack. After all, a Rails application is just Ruby source code. But Rails also does a lot of magic behind the curtain to get our applications to work with a minimum of explicit conﬁguration. To get this magic to work, Rails needs to ﬁnd all the various components of your application. As we’ll see later (in Section 18.1, Where things go, on page 279), this means that we need to create a speciﬁc directory structure, slotting the code we write into the appropriate places. The rails command simply creates this directory structure for us and populates it with some standard Rails code. To create your ﬁrst Rails application, pop open a shell window, and navigate to a place in your ﬁlesystem where you want to create your application’s directory structure. In our example, we’ll be creating our projects in a directory called work. In that directory, use the rails command to create an application called demo. Be slightly careful here—if you have an existing directory called demo, you will be asked whether you want to overwrite any existing ﬁles. (Note: if you want to specify which Rails version to use (as described in Section 1.4, Choosing a Rails Version, on page 33), now would be the time to do so.) rubys> cd work work> rails new demo create create README create .gitignore Prepared exclusively for Jared Rosoff Slide 42: CREATING A NEW APPLICATION 42 create : create create create work> Rakefile : : tmp/pids vendor/plugins vendor/plugins/.gitkeep The command has created a directory named demo. Pop down into that directory, and list its contents (using ls on a Unix box or dir under Windows). You should see a bunch of ﬁles and subdirectories: work> cd demo demo> ls -p app/ config.ru config/ db/ doc/ Gemfile lib/ log/ public/ Rakefile README script/ test/ tmp/ vendor/ All these directories (and the ﬁles they contain) can be intimidating to start with, but we can ignore most of them for now. In this chapter, we’ll use only one of them directly: the app directory, where we’ll write our application. Included in these ﬁles is everything you need to start a stand-alone web server that can run our newly created Rails application. So, without further ado, let’s start our demo application: demo> rails server => Booting WEBrick => Rails 3.0.0 application starting on http://0.0.0.0:3000} => Call with -d to detach => Ctrl-C to shutdown server [2009-09-29 10:53:35] INFO WEBrick 1.3.1 [2009-09-29 10:53:35] INFO ruby 1.8.7 (2008-08-11) [x86_64-linux] [2009-09-29 10:53:40] INFO WEBrick::HTTPServer#start: pid=6044 port=3000 Which web server is run depends on what servers you have installed. WEBrick is a pure-Ruby web server that is distributed with Ruby 1.8.1 and later, and therefore is guaranteed to be available. However, if another web server is installed on your system (and Rails can ﬁnd it), the rails server command may use it in preference to WEBrick. You can force Rails to use WEBrick by providing an option to the following command: demo> rails server webrick As the last line of the startup tracing indicates, we just started a web server on port 3000. The 0.0.0.0 part of the address means that WEBrick will accept connections on all interfaces. On Dave’s OS X system, that means both local interfaces (127.0.0.1 and ::1) and his LAN connection. We can access the application by pointing a browser at the URL http://localhost:3000. The result is shown in Figure 2.1. If you look at the window where you started the server, you’ll see tracing showing you started the application. We’re going to leave the server running in this Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 43: HELLO, RAILS! 43 Figure 2.1: Newly created Rails application console window. Later, as we write application code and run it via our browser, we’ll be able to use this console window to trace the incoming requests. When the time comes to shut down your application, you can press Ctrl-C in this window to stop WEBrick. (Don’t do that yet—we’ll be using this particular application in a minute.) At this point, we have a new application running, but it has none of our code in it. Let’s rectify this situation. 2.2 Hello, Rails! We can’t help it—we just have to write a “Hello, World!” program to try a new system. Let’s start by creating a simple application that sends our cheery greeting to a browser. After we get that working, we will embellish it with the current time and links. As we’ll explore further in Chapter 3, The Architecture of Rails Applications, on page 55, Rails is a Model-View-Controller framework. Rails accepts incoming Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 44: HELLO, RAILS! 44 requests from a browser, decodes the request to ﬁnd a controller, and calls an action method in that controller. The controller then invokes a particular view to display the results to the user. The good news is that Rails takes care of most of the internal plumbing that links all these actions. To write our simple “Hello, World!” application, we need code for a controller and a view, and we need a route to connect the two. We don’t need code for a model, because we’re not dealing with any data. Let’s start with the controller. In the same way that we used the rails command to create a new Rails application, we can also use a generator script to create a new controller for our project. This command is called rails generate. So, to create a controller called say, we make sure we’re in the demo directory and run the command, passing in the name of the controller we want to create, and the names of the actions we intend for this controller to support: demo> rails generate controller Say hello goodbye create app/controllers/say_controller.rb route get "say/goodbye" route get "say/hello" invoke erb create app/views/say create app/views/say/hello.html.erb create app/views/say/goodbye.html.erb invoke test_unit create test/functional/say_controller_test.rb invoke helper create app/helpers/say_helper.rb invoke test_unit create test/unit/helpers/say_helper_test.rb The rails generate command logs the ﬁles and directories it examines, noting when it adds new Ruby scripts or directories to your application. For now, we’re interested in one of these scripts and (in a minute) the html.erb ﬁle. The ﬁrst source ﬁle we’ll be looking at is the controller. You’ll ﬁnd it in the ﬁle app/controllers/say_controller.rb. Let’s take a look at it: Download work/demo1/app/controllers/say_controller.rb deﬁning classes ֒ page 71 → class SayController < ApplicationController def hello end def goodbye end end Pretty minimal, eh? SayController is a class that inherits from ApplicationController, so it automatically gets all the default controller behavior. What does this code have to do? For now, it does nothing—we simply have an empty Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 45: HELLO, RAILS! 45 Figure 2.2: Template ready for us to ﬁll in. action method named hello. To understand why this method is named this way, we need to look at the way Rails handles requests. Rails and Request URLs Like any other web application, a Rails application appears to its users to be associated with a URL. When you point your browser at that URL, you are talking to the application code, which generates a response to you. Let’s try it now. Navigate to the URL http://localhost:3000/say/hello in a browser window. (Note that in the development environment we don’t have any application string at the front of the path—we route directly to the controller.) You’ll see something that looks like Figure 2.2. Our First Action At this point, we can see that not only have we connected the URL to our controller, but also that Rails is pointing the way to our next step, namely to tell Rails what to display. That’s where views come in. Remember when we ran the script to create the new controller? That command added six ﬁles and a new directory to our application. That directory contains the template ﬁles for the controller’s views. In our case, we created a controller named say, so the views will be in the directory app/views/say. By default, Rails looks for templates in a ﬁle with the same name as the action it’s handling. In our case, that means we need to replace a ﬁle called hello.html.erb in the directory app/views/say. (Why .html.erb? We’ll explain in a minute.) For now, let’s just put some basic HTML in there: Download work/demo1/app/views/say/hello.html.erb <h1>Hello from Rails!</h1> Save the ﬁle hello.html.erb, and refresh your browser window. You should see it display our friendly greeting. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 46: HELLO, RAILS! 46 demo/ app/ controllers/ say_controller.rb models/ views/ say/ hello.html.erb class SayController < ApplicationController def hello end end <html> <head> <title>Hello, Rails!</title> </head> <body> <h1>Hello from Rails!</h1> </body> </html> Figure 2.3: Standard locations for controllers and views In total, we’ve looked at two ﬁles in our Rails application tree. We looked at the controller and we modiﬁed a template to display a page in the browser. These ﬁles live in standard locations in the Rails hierarchy: controllers go into app/controllers, and views go into subdirectories of app/views. See Figure 2.3. Making It Dynamic So far, our Rails application is pretty boring—it just displays a static page. To make it more dynamic, let’s have it show the current time each time it displays the page. To do this, we need to make a change to the template ﬁle in the view—it now needs to include the time as a string. That raises two questions. First, how do we add dynamic content to a template? Second, where do we get the time from? Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 47: HELLO, RAILS! 47 Dynamic Content There are many ways of creating dynamic templates in Rails. We will discuss Builder on page 363, and RJS, which is useful for adding Ajax magic to already-displayed pages in Section 11.2, Iteration F2: Creating an Ajax-Based Cart, on page 159. A third way, which we’ll use here, is to embed Ruby code in the template itself. That’s why we named our template ﬁle hello.html.erb; the .html.erb sufﬁx tells Rails to expand the content in the ﬁle using a system called ERb. ERb is a ﬁlter that is installed as a part of the Rails installation that takes an .erb ﬁle and outputs a transformed version. The output ﬁle is often HTML in Rails, but it can be anything. Normal content is passed through without being changed. However, content between <%= and %> is interpreted as Ruby code and executed. The result of that execution is converted into a string, and that value is substituted in the ﬁle in place of the <%=...%> sequence. For example, change hello.html.erb to display the current time: Download work/demo2/app/views/say/hello.html.erb <h1>Hello from Rails!</h1> <p> It is now <%= Time.now %> </p> When we refresh our browser window, we see the time displayed using Ruby’s standard format:1 Notice that if you hit Refresh in your browser, the time updates each time the page is displayed. It looks as if we’re really generating dynamic content. 1. With Ruby 1.9, the standard format has changed, and times now look more like the following: 2010-02-23 14:33:14 -0500. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 48: HELLO, RAILS! 48 Making Development Easier You might have noticed something about the development we’ve been doing so far. As we’ve been adding code to our application, we haven’t had to restart the running application. It has been happily chugging away in the background. And yet each change we make is available whenever we access the application through a browser. What gives? It turns out that the Rails dispatcher is pretty clever. In development mode (as opposed to testing or production), it automatically reloads application source ﬁles when a new request comes along. That way, when we edit our application, the dispatcher makes sure it’s running the most recent changes. This is great for development. However, this ﬂexibility comes at a cost—it causes a short pause after you enter a URL before the application responds. That’s caused by the dispatcher reloading stuff. For development it’s a price worth paying, but in production it would be unacceptable. Because of this, this feature is disabled for production deployment (see Chapter 16, Task K: Deployment and Production, on page 253). Adding the Time Our original problem was to display the time to users of our application. We now know how to make our application display dynamic data. The second issue we have to address is working out where to get the time from. We’ve shown that the approach of embedding a call to Ruby’s Time.now method in our hello.html.erb template works. Each time we access this page, the user will see the current time substituted into the body of the response. And for our trivial application, that might be good enough. In general, though, we probably want to do something slightly different. We’ll move the determination of the time to be displayed into the controller and leave the view with the simple job of displaying it. We’ll change our action method in the controller to set the time value into an instance variable called @time: Download work/demo3/app/controllers/say_controller.rb instance variable ֒ page 71 → class SayController < ApplicationController def hello @time = Time.now end def goodbye end end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 49: HELLO, RAILS! 49 In the .html.erb template we’ll use this instance variable to substitute the time into the output: Download work/demo3/app/views/say/hello.html.erb <h1>Hello from Rails!</h1> <p> It is now <%= @time %> </p> When we refresh our browser window, we will again see the current time, showing that the communication between the controller and the view was successful. Why did we go to the extra trouble of setting the time to be displayed in the controller and then using it in the view? Good question. In this application, it doesn’t make much difference, but by putting the logic in the controller instead, we buy ourselves some beneﬁts. For example, we may want to extend our application in the future to support users in many countries. In that case, we’d want to localize the display of the time, choosing a time appropriate to their time zone. That would be a fair amount of application-level code, and it would probably not be appropriate to embed it at the view level. By setting the time to display in the controller, we make our application more ﬂexible—we can change the time zone in the controller without having to update any view that uses that time object. The time is data, and it should be supplied to the view by the controller. We’ll see a lot more of this when we introduce models into the equation. The Story So Far Let’s brieﬂy review how our current application works: 1. The user navigates to our application. In our case, we do that using a local URL such as http://localhost:3000/say/hello. 2. Rails then matches the route pattern, which it previously split into two parts and analyzed. The say part is taken to be the name of a controller, so Rails creates a new instance of the Ruby class SayController (which it ﬁnds in app/controllers/say_controller.rb). 3. The next part of the pattern, hello, identiﬁes an action. Rails invokes a method of that name in the controller. This action method creates a new Time object holding the current time and tucks it away in the @time instance variable. 4. Rails looks for a template to display the result. It searches the directory app/views for a subdirectory with the same name as the controller (say) and in that subdirectory for a ﬁle named after the action (hello.html.erb). Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 50: LINKING PAGES TOGETHER 50 5. Rails processes this ﬁle through the ERb templating system, executing any embedded Ruby and substituting in values set up by the controller. 6. The result is returned to the browser, and Rails ﬁnishes processing this request. This isn’t the whole story—Rails gives you lots of opportunities to override this basic workﬂow (and we’ll be taking advantage of them shortly). As it stands, our story illustrates convention over conﬁguration, one of the fundamental parts of the philosophy of Rails. By providing convenient defaults and by applying certain conventions on how a URL is constructed or in what ﬁle a controller deﬁnition is placed and what class name and method names are used, Rails applications are typically written using little or no external conﬁguration—things just knit themselves together in a natural way. 2.3 Linking Pages Together It’s a rare web application that has just one page. Let’s see how we can add another stunning example of web design to our “Hello, World!” application. Normally, each page in your application will correspond to a separate view. In our case, we’ll also use a new action method to handle the page (although that isn’t always the case, as we’ll see later in the book). We’ll use the same controller for both actions. Again, this needn’t be the case, but we have no compelling reason to use a new controller right now. We already deﬁned a goodbye action for this controller, so all that remains is to create a new template in the directory app/views/say. This time it’s called goodbye.html.erb, because by default templates are named after their associated actions. Download work/demo4/app/views/say/goodbye.html.erb <h1>Goodbye!</h1> <p> It was nice having you here. </p> Fire up our trusty browser again, but this time point to our new view using the URL http://localhost:3000/say/goodbye. You should see something like this: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 51: LINKING PAGES TOGETHER 51 Now we need to link the two screens. We’ll put a link on the hello screen that takes us to the goodbye screen, and vice versa. In a real application, we might want to make these proper buttons, but for now we’ll just use hyperlinks. We already know that Rails uses a convention to parse the URL into a target controller and an action within that controller. So, a simple approach would be to adopt this URL convention for our links. The ﬁle hello.html.erb would contain the following: <html> ... <p> Say <a href="/say/goodbye">Goodbye</a>! </p> ... And the ﬁle goodbye.html.erb would point the other way: <html> ... <p> Say <a href="/say/hello">Hello</a>! </p> ... This approach would certainly work, but it’s a bit fragile. If we were to move our application to a different place on the web server, the URLs would no longer be valid. It also encodes assumptions about the Rails URL format into our code; it’s possible a future version of Rails might change this. Fortunately, these aren’t risks we have to take. Rails comes with a bunch of helper methods that can be used in view templates. Here, we’ll use the helper method link_to, which creates a hyperlink to an action. (The link_to method can do a lot more than this, but let’s take it gently for now...) Using link_to, hello.html.erb becomes the following: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 52: LINKING PAGES TOGETHER 52 Download work/demo5/app/views/say/hello.html.erb <h1>Hello from Rails!</h1> <p> It is now <%= @time %> </p> <p> Time to say <%= link_to "Goodbye!" , say_goodbye_path %> </p> There’s a link_to call within an ERb <%=...%> sequence. This creates a link to a URL that will invoke the goodbye action. The ﬁrst parameter in the call to link_to is the text to be displayed in the hyperlink, and the next parameter tells Rails to generate the link to the goodbye action. Let’s stop for a minute to consider how we generated the link. We wrote this: link_to "Goodbye!" , say_goodbye_path First, link_to is a method call. (In Rails, we call methods that make it easier to write templates helpers.) If you come from a language such as Java, you might be surprised that Ruby doesn’t insist on parentheses around method parameters. You can always add them if you like. The say_goodbye_path is a precomputed value that Rails makes available to application views. It evaluates to the /say/goodbye path. Over time you will see that Rails provides the ability to name all of the routes that you will be using in your application. OK, back to the application. If we point our browser at our hello page, it will now contain the link to the goodbye page, as shown here: We can make the corresponding change in goodbye.html.erb, linking it back to the initial hello page: Download work/demo5/app/views/say/goodbye.html.erb <h1>Goodbye!</h1> <p> It was nice having you here. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 53: WHAT WE JUST DID </p> <p> Say <%= link_to "Hello" , say_hello_path %> again. </p> 53 At this point, we’ve completed our toy application, and in the process veriﬁed that our installation of Rails is functioning properly. After a brief recap, it is now time to move on to building a real application. 2.4 What We Just Did Constructed a toy application which showed us the following: • How to create a new Rails application and how to create a new controller in that application • How to create dynamic content in the controller and display it via the view template • How to link pages together This is a great foundation, and it didn’t really take much time or effort. This experience will continue as we move on to the next chapter and build a much bigger application. Playtime Here’s some stuff to try on your own: • Experiment with the following expressions: – Addition: <%= 1+2 %> – Concatenation: <%= "cow" + "boy" %> – Time in one hour: <%= 1.hour.from_now %> • A call to the following Ruby method returns a list of all the ﬁles in the current directory: @files = Dir.glob('' ) Use it to set an instance variable in a controller action, and then write the corresponding template that displays the ﬁlenames in a list on the browser. Hint: you can iterate over a collection using something like this: <% for file in @files %> file name is: <%= file %> <% end %> You might want to use a <ul> for the list. (You’ll ﬁnd hints at http://www.pragprog.com/wikis/wiki/RailsPlayTime.) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 54: WHAT WE JUST DID 54 Cleaning Up Maybe you’ve been following along and writing the code in this chapter. If so, chances are that the application is still running on your computer. When we start coding our next application in ten pages or so, we’ll get a conﬂict the ﬁrst time we run it, because it will also try to use the computer’s port 3000 to talk with the browser. Now would be a good time to stop the current application by pressing Ctrl-C in the window you used to start it. Now lets move on to an overview of Rails itself. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 55: In this chapter, we’ll see • models, • views, and • controllers. Chapter 3 The Architecture of Rails Applications One of the interesting features of Rails is that it imposes some fairly serious constraints on how you structure your web applications. Surprisingly, these constraints make it easier to create applications—a lot easier. Let’s see why. 3.1 Models, Views, and Controllers Back in 1979, Trygve Reenskaug came up with a new architecture for developing interactive applications. In his design, applications were broken into three types of components: models, views, and controllers. The model is responsible for maintaining the state of the application. Sometimes this state is transient, lasting for just a couple of interactions with the user. Sometimes the state is permanent and will be stored outside the application, often in a database. A model is more than just data; it enforces all the business rules that apply to that data. For example, if a discount shouldn’t be applied to orders of less than $20, the model will enforce the constraint. This makes sense; by putting the implementation of these business rules in the model, we make sure that nothing else in the application can make our data invalid. The model acts as both a gatekeeper and a data store. The view is responsible for generating a user interface, normally based on data in the model. For example, an online store will have a list of products to be displayed on a catalog screen. This list will be accessible via the model, but it will be a view that accesses the list from the model and formats it for the end user. Although the view may present the user with various ways of inputting data, the view itself never handles incoming data. The view’s work is done once the data is displayed. There may well be many views that access the same model data, often for different purposes. In the online store, there’ll Prepared exclusively for Jared Rosoff Slide 56: MODELS, VIEWS, AND CONTROLLERS 56 Controller Browser sends request Controller interacts with model Controller invokes view View renders next browser screen View Model Database Figure 3.1: The Model-View-Controller architecture be a view that displays product information on a catalog page and another set of views used by administrators to add and edit products. Controllers orchestrate the application. Controllers receive events from the outside world (normally user input), interact with the model, and display an appropriate view to the user. This triumvirate—the model, view, and controller—together form an architecture known as MVC. See Figure 3.1 to see how the three concepts ﬁt together. The MVC architecture was originally intended for conventional GUI applications, where developers found the separation of concerns led to far less coupling, which in turn made the code easier to write and maintain. Each concept or action was expressed in just one well-known place. Using MVC was like constructing a skyscraper with the girders already in place—it was a lot easier to hang the rest of the pieces with a structure already there. During the development of our application we will be making heavy use of Rails’ ability to generate scaffolding for our application. Ruby on Rails is an MVC framework, too. Rails enforces a structure for your application—you develop models, views, and controllers as separate chunks of functionality, and it knits them all together as your program executes. One of the joys of Rails is that this knitting process is based on the use of intelligent defaults so that you typically don’t need to write any external conﬁguration Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 57: MODELS, VIEWS, AND CONTROLLERS 57 Routing Line Items Controller http://my.url/line_items?product_id=2 Routing ﬁnds LineItems controller Controller interacts with model Controller invokes view View renders next browser screen Line Items View Active Record Model Database Figure 3.2: Rails and MVC metadata to make it all work. This is an example of the Rails philosophy of favoring convention over conﬁguration. In a Rails application, an incoming request is ﬁrst sent to a router, which works out where in the application the request should be sent and how the request itself should be parsed. Ultimately, this phase identiﬁes a particular method (called an action in Rails parlance) somewhere in the controller code. The action might look at data in the request, it might interact with the model, and it might cause other actions to be invoked. Eventually the action prepares information for the view, which renders something to the user. Rails handles an incoming request as shown in Figure 3.2. In this example, the application has previously displayed a product catalog page, and the user has just clicked the Add to Cart button next to one of the products. This button posts to http://my.url/line_items?product_id=2, where line_items is a resource in our application and 2 is our internal id for the selected product. The routing component receives the incoming request and immediately picks it apart. The request contains a path (/line_items?product_id=2) and a method (this button does a POST operation, other common methods are GET, PUT, and DELETE). In this simple case, Rails takes the ﬁrst part of the path, line_items, as the name of the controller and the product_id as the id of a product. By convention POST methods are associated with create actions. As a result of all this Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 58: RAILS MODEL SUPPOR T 58 analysis, the router knows it has to invoke the create method in the controller class LineItemsController (we’ll talk about naming conventions on page 287). The create method handles user requests. In this case, it ﬁnds the current user’s shopping cart (which is an object managed by the model). It also asks the model to ﬁnd the information for product 2. It then tells the shopping cart to add that product to itself. (See how the model is being used to keep track of all the business data? The controller tells it what to do, and the model knows how to do it.) Now that the cart includes the new product, we can show it to the user. The controller invokes the view code, but before it does, it arranges things so that the view has access to the cart object from the model. In Rails, this invocation is often implicit; again, conventions help link a particular view with a given action. That’s all there is to an MVC web application. By following a set of conventions and partitioning your functionality appropriately, you’ll discover that your code becomes easier to work with and your application becomes easier to extend and maintain. Seems like a good trade. If MVC is simply a question of partitioning your code a particular way, you might be wondering why you need a framework such as Ruby on Rails. The answer is straightforward: Rails handles all of the low-level housekeeping for you—all those messy details that take so long to handle by yourself—and lets you concentrate on your application’s core functionality. Let’s see how.... 3.2 Rails Model Support In general, we’ll want our web applications to keep their information in a relational database. Order-entry systems will store orders, line items, and customer details in database tables. Even applications that normally use unstructured text, such as weblogs and news sites, often use databases as their backend data store. Although it might not be immediately apparent from the SQL1 you use to access them, relational databases are actually designed around mathematical set theory. Although this is good from a conceptual point of view, it makes it difﬁcult to combine relational databases with object-oriented (OO) programming languages. Objects are all about data and operations, and databases are all about sets of values. Operations that are easy to express in relational terms are sometimes difﬁcult to code in an OO system. The reverse is also true. 1. SQL, referred to by some as Structured Query Language, is the language used to query and update relational databases. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 59: RAILS MODEL SUPPOR T 59 Over time, folks have worked out ways of reconciling the relational and OO views of their corporate data. Let’s look at the way that Rails chooses to map relational data onto objects. Object-Relational Mapping ORM libraries map database tables to classes. If a database has a table called orders, our program will have a class named Order. Rows in this table correspond to objects of the class—a particular order is represented as an object of class Order. Within that object, attributes are used to get and set the individual columns. Our Order object has methods to get and set the amount, the sales tax, and so on. In addition, the Rails classes that wrap our database tables provide a set of class-level methods that perform table-level operations. For example, we might need to ﬁnd the order with a particular id. This is implemented as a class method that returns the corresponding Order object. In Ruby code, this might look like this: order = Order.find(1) puts "Customer #{order.customer_id}, amount=$#{order.amount}" class method ֒ page 71 → puts ֒ page 65 → Sometimes these class-level methods return collections of objects: Order.where(:name => 'dave' ).each do \|order\| puts order.amount end iterating ֒ page 69 → Finally, the objects corresponding to individual rows in a table have methods that operate on that row. Probably the most widely used is save, the operation that saves the row to the database: Order.where(:name => 'dave' ).each do \|order\| order.discount = 0.5 order.save end So, an ORM layer maps tables to classes, rows to objects, and columns to attributes of those objects. Class methods are used to perform table-level operations, and instance methods perform operations on the individual rows. In a typical ORM library, you supply conﬁguration data to specify the mappings between entities in the database and entities in the program. Programmers using these ORM tools often ﬁnd themselves creating and maintaining a boatload of XML conﬁguration ﬁles. Active Record Active Record is the ORM layer supplied with Rails. It closely follows the standard ORM model: tables map to classes, rows to objects, and columns to object attributes. It differs from most other ORM libraries in the way it is conﬁgured. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 60: ACTION PACK: THE VIEW AND CONTROLLER 60 By relying on convention and starting with sensible defaults, Active Record minimizes the amount of conﬁguration that developers perform. To illustrate this, here’s a program that uses Active Record to wrap our orders table: require 'active_record' class Order < ActiveRecord::Base end order = Order.find(1) order.discount = 0.5 order.save This code uses the new Order class to fetch the order with an id of 1 and modify the discount. (We’ve omitted the code that creates a database connection for now.) Active Record relieves us of the hassles of dealing with the underlying database, leaving us free to work on business logic. But Active Record does more than that. As you’ll see when we develop our shopping cart application, starting on page 81, Active Record integrates seamlessly with the rest of the Rails framework. If a web form sends the application data related to a business object, Active Record can extract it into our model. Active Record supports sophisticated validation of model data, and if the form data fails validations, the Rails views can extract and format errors. Active Record is the solid model foundation of the Rails MVC architecture. 3.3 Action Pack: The View and Controller When you think about it, the view and controller parts of MVC are pretty intimate. The controller supplies data to the view, and the controller receives events from the pages generated by the views. Because of these interactions, support for views and controllers in Rails is bundled into a single component, Action Pack. Don’t be fooled into thinking that your application’s view code and controller code will be jumbled up just because Action Pack is a single component. Quite the contrary; Rails gives you the separation you need to write web applications with clearly demarcated code for control and presentation logic. View Support In Rails, the view is responsible for creating either all or part of a response to be displayed in a browser, processed by an application or sent as an email. At its simplest, a view is a chunk of HTML code that displays some ﬁxed text. More typically you’ll want to include dynamic content created by the action method in the controller. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 61: ACTION PACK: THE VIEW AND CONTROLLER 61 In Rails, dynamic content is generated by templates, which come in three ﬂavors. The most common templating scheme, called Embedded Ruby (ERb), embeds snippets of Ruby code within a view document, in many ways similar to the way it is done in other web frameworks, such as PHP or JSP. While this approach is very ﬂexible, some are concerned that it violates the spirit of MVC. By embedding code in the view, we risk adding logic that should be in the model or the controller. As with everything, while judicious use in moderation is healthy, overuse can become a problem. Maintaining a clean separation of concerns is part of the job of the developer. (We look at HTML templates in Section 21.1, ERb Templates, on page 364.) XML Builder can also be used to construct XML documents using Ruby code— the structure of the generated XML will automatically follow the structure of the code. We discuss xml.builder templates starting on page 363. Rails also provides RJS views. These allow you to create JavaScript fragments on the server that are then executed on the browser. This is great for creating dynamic Ajax interfaces. We talk about these starting on page 159. And the Controller! The Rails controller is the logical center of your application. It coordinates the interaction between the user, the views, and the model. However, Rails handles most of this interaction behind the scenes; the code you write concentrates on application-level functionality. This makes Rails controller code remarkably easy to develop and maintain. The controller is also home to a number of important ancillary services: • It is responsible for routing external requests to internal actions. It handles people-friendly URLs extremely well. • It manages caching, which can give applications orders-of-magnitude performance boosts. • It manages helper modules, which extend the capabilities of the view templates without bulking up their code. • It manages sessions, giving users the impression of ongoing interaction with our applications. You’ve already seen and modiﬁed a controller in Section 2.2, Hello, Rails!, on page 43, and will be seeing and modifying a number of controllers in the development of the Depot application, starting with the Product Controller in Section 8.1, Iteration C1: Creating the Catalog Listing, on page 117. There’s a lot to Rails. But before going any further let’s have a brief refresher— and for some of you, a brief introduction—to the Ruby language itself. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 62: ACTION PACK: THE VIEW AND CONTROLLER 62 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 63: In this chapter, we’ll see • • • • • • objects: names, methods; data: strings, arrays, hashes, and regular expressions; control: if, while, blocks, iterators, exceptions; building blocks: classes, and modules; YAML and marshalling; and common idioms that you will see used in this book. Chapter 4 Introduction to Ruby Many people who are new to Rails are also new to Ruby. If you are familiar with a language like Java, JavaScript, PHP, Perl or Python, you will ﬁnd Ruby pretty easy to pick up. This chapter is not a complete introduction to Ruby, it will not cover things like precedence rules (like most other programming languages, 1+23==7 in Ruby), it is only meant to explain enough Ruby that the examples in the book make sense. This chapter draws heavily from material in Chapter 2 of Programming Ruby [TFH05]. If you feel you need more background on the Ruby language, and at the risk of being grossly self-serving, we’d like to suggest that the best way to learn Ruby, and the best reference for Ruby’s classes, modules, and libraries, is Programming Ruby [TFH05] (also known as the PickAxe book). Welcome to the Ruby community! 4.1 Ruby Is an Object-Oriented Language Everything you manipulate in Ruby is an object, and the results of those manipulations are themselves objects. When you write object-oriented code, you’re normally looking to model concepts from the real world. Typically during this modeling process you’ll discover categories of things that need to be represented. In an online store, the concept of a line item could be such a category. In Ruby, you’d deﬁne a class to represent each of these categories. You then use this class as a kind of factory that generates objects—instances of that class. An object is a combination of state (for example, the quantity and the product id) and methods that use that state (perhaps a method to calculate the line item’s total cost). We’ll show how to create classes on page 71. Prepared exclusively for Jared Rosoff Slide 64: RUBY IS AN OBJECT -ORIENTED LANGUAGE 64 Objects are created by calling a constructor, a special method associated with a class. The standard constructor is called new. Given a class called LineItem, you could create line item objects as follows: line_item_one = LineItem.new line_item_one.quantity = 1 line_item_one.sku = "AUTO_B_00" Methods are invoked by sending a message to an object. The message contains the method’s name, along with any parameters the method may need. When an object receives a message, it looks into its own class for a corresponding method. Let’s look at some method calls: "dave".length line_item_one.quantity() cart.add_line_item(next_purchase) submit_tag "Add to Cart" Parentheses are generally optional in method calls. In Rails applications, you’ll ﬁnd that most method calls involved in larger expressions will have parentheses, while those that look more like commands or declarations tend not to have them. Methods have names, as do many other constructs in Ruby. Names in Ruby have special rules, rules that you may not have seen if you come to Ruby from another language. Ruby Names Local variables, method parameters, and method names should all start with a lowercase letter or with an underscore: order, line_item, and xr2000 are all valid. Instance variables (which we talk about on page 71) begin with an “at” sign (@), such as @quantity and @product_id. The Ruby convention is to use underscores to separate words in a multiword method or variable name (so line_item is preferable to lineItem). Class names, module names, and constants must start with an uppercase letter. By convention they use capitalization, rather than underscores, to distinguish the start of words within the name. Class names look like Object, PurchaseOrder, and LineItem. Rails uses symbols to identify things. In particular, it uses them as keys when naming method parameters and looking things up in hashes. For example: redirect_to :action => "edit" , :id => params[:id] As you can see, a symbol looks like a variable name, but it’s preﬁxed with a colon. Examples of symbols include :action, :line_items, and :id. You can think of symbols as string literals that are magically made into constants. Alternatively, Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 65: DATA TYPES 65 you can consider the colon to mean “thing named” so :id is “the thing named id.” Now that we have used a few methods, let’s move on to how they are deﬁned. Methods Let’s write a method that returns a cheery, personalized greeting. We’ll invoke that method a couple of times: def say_goodnight(name) result = 'Good night, ' + name return result end # Time for bed... puts say_goodnight('Mary-Ellen' ) puts say_goodnight('John-Boy' ) Having deﬁned the method, we call it twice. In both cases, we pass the result to the method puts, which outputs to the console its argument followed by a newline (moving on to the next line of output). You don’t need a semicolon at the end of a statement as long as you put each statement on a separate line. Ruby comments start with a # character and run to the end of the line. Indentation is not signiﬁcant (but two-character indentation is the de facto Ruby standard). Ruby doesn’t use braces to delimit the bodies of compound statements and deﬁnitions (such as methods and classes). Instead, you simply ﬁnish the body with the keyword end. The keyword return is optional, and if not present, the results of the last expression evaluated will be returned. 4.2 Data Types While everything in Ruby is an object, some of the data types in Ruby have special syntax support, in particular for deﬁning literal values. In these examples, we’ve used some simple strings and even string concatenation. Strings This previous example also showed some Ruby string objects. One way to create a string object is to use string literals, which are sequences of characters between single or double quotation marks. The difference between the two forms is the amount of processing Ruby does on the string while constructing the literal. In the single-quoted case, Ruby does very little. With a few exceptions, what you type into the single-quoted string literal becomes the string’s value. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 66: DATA TYPES 66 In the double-quoted case, Ruby does more work. First, it looks for substitutions—sequences that start with a backslash character—and replaces them with some binary value. The most common of these is \n, which is replaced with a newline character. When you write a string containing a newline to the console, the \n forces a line break. Second, Ruby performs expression interpolation in double-quoted strings. In the string, the sequence #{expression} is replaced by the value of expression. We could use this to rewrite our previous method: def say_goodnight(name) "Good night, #{name.capitalize}" end puts say_goodnight('pa' ) When Ruby constructs this string object, it looks at the current value of name and substitutes it into the string. Arbitrarily complex expressions are allowed in the #{...} construct. Here we invoked the capitalize method, deﬁned for all strings, to output our parameter with a leading uppercase letter. Strings are a fairly primitive data type which contain an ordered collection of bytes or characters. Ruby also provides means for deﬁning collections of arbitrary objects via Arrays and Hashes. Arrays and Hashes Ruby’s arrays and hashes are indexed collections. Both store collections of objects, accessible using a key. With arrays, the key is an integer, whereas hashes support any object as a key. Both arrays and hashes grow as needed to hold new elements. It’s more efﬁcient to access array elements, but hashes provide more ﬂexibility. Any particular array or hash can hold objects of differing types; you can have an array containing an integer, a string, and a ﬂoating-point number, for example. You can create and initialize a new array object using an array literal—a set of elements between square brackets. Given an array object, you can access individual elements by supplying an index between square brackets, as the next example shows. Ruby array indices start at zero. a = [ 1, 'cat' , 3.14 ] a[0] a[2] = nil # # # # array with three elements access the first element (1) set the third element array now [ 1, 'cat', nil ] You may have noticed that we used the special value nil in this example. In many languages, the concept of nil (or null) means “no object.” In Ruby, that’s not the case; nil is an object, just like any other, that happens to represent nothing. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 67: DATA TYPES 67 The method << is commonly used with arrays. It appends a value to its receiver. ages = [] for person in @people ages << person.age end Ruby has a shortcut for creating an array of words: a = [ 'ant' , 'bee' , 'cat' , 'dog' , 'elk' ] # this is the same: a = %w{ ant bee cat dog elk } Ruby hashes are similar to arrays. A hash literal uses braces rather than square brackets. The literal must supply two objects for every entry: one for the key, the other for the value. For example, you may want to map musical instruments to their orchestral sections: inst_section :cello :clarinet :drum :oboe :trumpet :violin } ={ => 'string' , => 'woodwind' , => 'percussion' , => 'woodwind' , => 'brass' , => 'string' The thing to the left of the => is the key, and that on the right is the corresponding value. Keys in a particular hash must be unique—you can’t have two entries for :drum. The keys and values in a hash can be arbitrary objects— you can have hashes where the values are arrays, other hashes, and so on. In Rails, hashes typically use symbols as keys. Many Rails hashes have been subtly modiﬁed so that you can use either a string or a symbol interchangeably as a key when inserting and looking up values. Hashes are indexed using the same square bracket notation as arrays: inst_section[:oboe] inst_section[:cello] inst_section[:bassoon] #=> 'woodwind' #=> 'string' #=> nil As the last example shows, a hash returns nil when indexed by a key it doesn’t contain. Normally this is convenient, because nil means false when used in conditional expressions. You can pass hashes as parameters on method calls. Ruby allows you to omit the braces, but only if the hash is the last parameter of the call. Rails makes extensive use of this feature. The following code fragment shows a two-element hash being passed to the redirect_to method. In effect, though, you can ignore the fact that it’s a hash and pretend that Ruby has keyword arguments. redirect_to :action => 'show' , :id => product.id Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 68: LOGIC 68 There is one more data type worth mentioning—the regular expression. Regular Expressions A regular expression lets you specify a pattern of characters to be matched in a string. In Ruby, you typically create a regular expression by writing /pattern/ or %r{pattern}. For example, you could write a pattern that matches a string containing the text Perl or the text Python using the regular expression /Perl\|Python/. The forward slashes delimit the pattern, which consists of the two things we’re matching, separated by a vertical bar (\|). This bar character means “either the thing on the left or the thing on the right,” in this case either Perl or Python. You can use parentheses within patterns, just as you can in arithmetic expressions, so you could also have written this pattern as /P(erl\|ython)/. Programs typically test strings against regular expressions using the =~ match operator: if line =~ /P(erl\|ython)/ puts "There seems to be another scripting language here" end You can specify repetition within patterns. /ab+c/ matches a string containing an a followed by one or more b’s, followed by a c. Change the plus to an asterisk, and /abc/ creates a regular expression that matches one a, zero or more b’s, and one c. Backward slashes start special sequences, most notably \d matches any digit, \s matches any whitespace character, and \w matches any alphanumeric ("word") character. Ruby’s regular expressions are a deep and complex subject; this section barely skims the surface. See the PickAxe book for a full discussion. This book will only make light use of regular expressions. With that brief introduction to data, let’s move on to logic. 4.3 Logic Method calls are statements. Ruby also provides a number of ways to make decisions which affect the repetition and order in which methods are invoked. Control Structures Ruby has all the usual control structures, such as if statements and while loops. Java, C, and Perl programmers may well get caught by the lack of braces around the bodies of these statements. Instead, Ruby uses the keyword end to signify the end of a body: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 69: LOGIC if count > 10 puts "Try again" elsif tries == 3 puts "You lose" else puts "Enter a number" end 69 Similarly, while statements are terminated with end: while weight < 100 and num_pallets <= 30 pallet = next_pallet() weight += pallet.weight num_pallets += 1 end Ruby statement modiﬁers are a useful shortcut if the body of an if or while statement is just a single expression. Simply write the expression, followed by if or while and the condition: puts "Danger, Will Robinson" if radiation > 3000 distance = distance 1.2 while distance < 100 While if statements are fairly common in Ruby applications, newcomers to the Ruby language are often surprised to ﬁnd that looping constructs are rarely used. Blocks and iterators often take their place. Blocks and Iterators Code blocks are just chunks of code between braces or between do...end. A common convention is that people use braces for single-line blocks and do/end for multiline blocks: { puts "Hello" } do club.enroll(person) person.socialize end # this is a block ### # and so is this # ### To pass a block to a method, place the block after the parameters (if any) to the method. In other words, put the start of the block at the end of the source line containing the method call. For example, in the following code, the block containing puts "Hi" is associated with the call to the method greet: greet { puts "Hi" } If the method has parameters, they appear before the block: verbose_greet("Dave" , "loyal customer" ) { puts "Hi" } A method can invoke an associated block one or more times using the Ruby yield statement. You can think of yield as being something like a method call Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 70: LOGIC 70 that calls out to the block associated with the method containing the yield. You can pass values to the block by giving parameters to yield. Within the block, you list the names of the arguments to receive these parameters between vertical bars (\|). Code blocks appear throughout Ruby applications. Often they are used in conjunction with iterators: methods that return successive elements from some kind of collection, such as an array: animals = %w( ant bee cat dog elk ) animals.each {\|animal\| puts animal } # create an array # iterate over the contents Each integer N implements a times method, which invokes an associated block N times: 3.times { print "Ho! " } #=> Ho! Ho! Ho! The & preﬁx operator will allow a method to capture a passed block as a named parameter. def wrap &b print "Santa says: " 3.times(&b) print "\n" end wrap { print "Ho! " } Within a block, or a method, control is sequential except when there is an exception. Exceptions Exceptions are objects (of class Exception or its subclasses). The raise method causes an exception to be raised. This interrupts the normal ﬂow through the code. Instead, Ruby searches back through the call stack for code that says it can handle this exception. Both methods and blocks of code wrapped between begin and end keywords intercept certain classes of exceptions using rescue clauses. begin content = load_blog_data(file_name) rescue BlogDataNotFound STDERR.puts "File #{file_name} not found" rescue BlogDataFormatError STDERR.puts "Invalid blog data in #{file_name}" rescue Exception => exc STDERR.puts "General error loading #{file_name}: #{exc.message}" end rescue clauses can be directly placed on the outermost level of a method deﬁ- nition without needing to enclose the contents in a begin/end block. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 71: ORGANIZING STRUCTURES 71 That concludes our brief introduction to control ﬂow, and at this point we have our basic building blocks upon which we can build larger structures. 4.4 Organizing Structures There are two basic concepts in Ruby for organizing methods: namely classes and modules. We cover each in turn. Classes Here’s a Ruby class deﬁnition: Line 1 5 10 - class Order < ActiveRecord::Base has_many :line_items def self.find_all_unpaid self.where('paid = 0' ) end def total sum = 0 line_items.each {\|li\| sum += li.total} end end Class deﬁnitions start with the keyword class followed by the class name (which must start with an uppercase letter). This Order class is deﬁned to be a subclass of the class Base within the ActiveRecord module. Rails makes heavy use of class-level declarations. Here has_many is a method that’s deﬁned by Active Record. It’s called as the Order class is being deﬁned. Normally these kinds of methods make assertions about the class, so in this book we call them declarations. Within a class body you can deﬁne class methods and instance methods. Preﬁxing a method name with self. (as we do on line 5) makes it a class method; it can be called on the class generally. In this case, we can make the following call anywhere in our application: to_collect = Order.find_all_unpaid Objects of a class hold their state in instance variables. These variables, whose names all start with @, are available to all the instance methods of a class. Each object gets its own set of instance variables. Instance variables are not directly accessible outside the class. To make them available, write methods that return their values: class Greeter def initialize(name) @name = name Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 72: ORGANIZING STRUCTURES end def name @name end def name=(new_name) @name = new_name end end g = Greeter.new("Barney" ) #=> Barney puts g.name g.name = "Betty" puts g.name #=> Betty 72 Ruby provides convenience methods that write these accessor methods for you (which is great news for folks tired of writing all those getters and setters): class Greeter attr_accessor attr_reader attr_writer :name :greeting :age # create reader and writer methods # create reader only # create writer only A class’s instance methods are public by default; anyone can call them. You’ll probably want to override this for methods that are intended to be used only by other class instance methods: class MyClass def m1 # this method is public end protected def m2 end private def m3 end end # this method is private # this method is protected The private directive is the strictest; private methods can be called only from within the same instance. Protected methods can be called both in the same instance and by other instances of the same class and its subclasses. Classes are not the only organizing structure in Ruby. The other organizing structure is a module. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 73: ORGANIZING STRUCTURES 73 Modules Modules are similar to classes in that they hold a collection of methods, constants, and other module and class deﬁnitions. Unlike classes, you cannot create objects based on modules. Modules serve two purposes. First, they act as a namespace, letting you deﬁne methods whose names will not clash with those deﬁned elsewhere. Second, they allow you to share functionality between classes—if a class mixes in a module, that module’s instance methods become available as if they had been deﬁned in the class. Multiple classes can mix in the same module, sharing the module’s functionality without using inheritance. You can also mix multiple modules into a single class. Helper methods are an example of where Rails uses modules. Rails automatically mixes these helper modules into the appropriate view templates. For example, if you wanted to write a helper method that would be callable from views invoked by the store controller, you could deﬁne the following module in the ﬁle store_helper.rb in the app/helpers directory: module StoreHelper def capitalize_words(string) string.split(' ' ).map {\|word\| word.capitalize}.join(' ' ) end end There is one module that is a part of the standard library of Ruby that deserves special mention given its usage in Rails, namely YAML. YAML YAML1 is a recursive acronym which stands for YAML Ain’t Markup Language. In the context of Rails, YAML is used as a convenient way to deﬁne conﬁguration of things such as databases, test data, and translations. Here is an example: development: adapter: sqlite3 database: db/development.sqlite3 pool: 5 timeout: 5000 In YAML, indentation is important, so this deﬁnes development as having a set of four key/value pairs, separated by colons. While YAML is one way to represent data, particularly when interacting with humans, Ruby provides a more general way for representing data for use by applications. 1. http://www.yaml.org/ Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 74: MARSHALING OBJECTS 74 4.5 Marshaling Objects Ruby can take an object and convert it into a stream of bytes that can be stored outside the application. This process is called marshaling. This saved object can later be read by another instance of the application (or by a totally separate application), and a copy of the originally saved object can be reconstituted. There are two potential issues when you use marshaling. First, some objects cannot be dumped. If the objects to be dumped include bindings, procedure or method objects, instances of class IO, singleton objects, or if you try to dump anonymous classes or modules, a TypeError will be raised. Second, when you load a marshaled object, Ruby needs to know the deﬁnition of the class of that object (and of all the objects it contains). Rails uses marshaling to store session data. If you rely on Rails to dynamically load classes, it is possible that a particular class may not have been deﬁned at the point it reconstitutes session data. For that reason, you’ll use the model declaration in your controller to list all models that are marshaled. This preemptively loads the necessary classes to make marshaling work. Now that you have the Ruby basics down, let’s give what we learned a whirl with a slightly larger, annotated example that pulls together a number of concepts. We’ll follow that with a walkthrough of special features that will help you with your Rails coding. 4.6 Pulling It All Together Let’s look at an example of how Rails applies a number of Ruby features together to make the code you need to maintain more declarative. You will see this example again in Section 6.1, Generating the Scaffold, on page 90. For now, we will focus on the Ruby language aspects of the example. class CreateProducts < ActiveRecord::Migration def self.up create_table :products do \|t\| t.string :title t.text :description t.string :image_url t.decimal :price, :precision => 8, :scale => 2 t.timestamps end end def self.down drop_table :products end end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 75: RUBY IDIOMS 75 Even if you didn’t know any Ruby, you would probably be able to decipher that up creates a table named products and down drops that table. The ﬁelds deﬁned when creating this table include title, description, image_url, and price as well as a few timestamps (we’ll describe these on page 407). Now let’s look at the same example from a Ruby perspective. A class named CreateProducts is deﬁned, which inherits from the Migration class from the ActiveRecord module. Two class methods are deﬁned, one named up, and the other named down. Each calls a single class method (deﬁned in ActiveRecord::Migration), passing it the name of the table in the form of a symbol. The call to up also passes a block which is to be evaluated before the table is created. This block, when called, is passed an object named t which is used to accumulate a list of ﬁelds. Rails deﬁnes a number of methods on this object, methods with names which are named after common data types. These methods, when called, simply add a ﬁeld deﬁnition to the ever accumulating set of names. The deﬁnition of decimal also accepts a number of optional parameters, expressed as a hash. To someone new to Ruby, this is a lot of heavy machinery thrown at solving such a simple problem. To someone familiar with Ruby, none of this machinery is particularly heavy. In any case, Rails makes extensive use of the facilities provided by Ruby to make deﬁning operations (for example, migration tasks) as simple and as declarative as possible. Even small features of the language, like optional parentheses and braces, contribute to the overall readability and ease of authoring. Finally, there are a number of small features, or rather idiomatic combinations of features that are often not immediately obvious to people new to the Ruby language. We close this chapter with them. 4.7 Ruby Idioms A number of individual Ruby features can be combined in interesting ways, and the meaning of such idiomatic usage is often not immediately obvious to people new to the language. We use these common Ruby idioms in this book: Methods such as empty! and empty? Ruby method names can end with an exclamation mark (a bang method) or a question mark (a predicate method). Bang methods normally do something destructive to the receiver. Predicate methods return true or false depending on some condition. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 76: RUBY IDIOMS a \|\| b 76 The expression a \|\| b evaluates a. If it isn’t false or nil, then evaluation stops and the expression returns a. Otherwise, the statement returns b. This is a common way of returning a default value if the ﬁrst value hasn’t been set. a \|\|= b The assignment statement supports a set of shortcuts: a op= b is the same as a = a op b. This works for most operators. count += 1 price = discount count \|\|= 0 # same as count = count + 1 # price = price discount # count = count \|\| 0 So, count \|\|= 0 gives count the value 0 if count doesn’t already have a value. obj = self.new Sometimes a class method needs to create an instance of that class. class Person < ActiveRecord::Base def self.for_dave Person.new(:name => 'Dave' ) end end This works ﬁne, returning a new Person object. But later, someone might subclass our class: class Employee < Person # .. end dave = Employee.for_dave # returns a Person The for_dave method was hardwired to return a Person object, so that’s what is returned by Employee.for_dave. Using self.new instead returns a new object of the receiver’s class, Employee. lambda The lambda operator converts a block into a object of type Proc. We will see this used on page 311. require File.dirname(__FILE__) + ’/../test_helper’ Ruby’s require method loads an external source ﬁle into our application. This is used to include library code and classes that our application relies on. In normal use, Ruby ﬁnds these ﬁles by searching in a list of directories, the LOAD_PATH. Sometimes we need to be speciﬁc about what ﬁle to include. We can do that by giving require a full ﬁlesystem path. The problem is, we don’t know what that path will be—our users could install our code anywhere. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 77: RUBY IDIOMS 77 Wherever our application ends up getting installed, the relative path between the ﬁle doing the requiring and the target ﬁle will be the same. Knowing this, we can construct the absolute path to the target by taking the absolute path to the ﬁle doing the requiring (available in the special variable __FILE__), stripping out all but the directory name, and then appending the relative path to the target ﬁle. In addition, there are many good resources on the Web showing Ruby idioms and Ruby gotchas. Here are just a few. • http://www.ruby-lang.org/en/documentation/ruby-from-other-languages/ • http://en.wikipedia.org/wiki/Ruby_programming_language • http://www.zenspider.com/Languages/Ruby/QuickRef.html By this point, we have a ﬁrm foundation upon which to build: we’ve installed Rails, veriﬁed that we have things working with a simple application, covered a brief description of what Rails is, and reviewed (or for some of you, learned for the ﬁrst time) the basics of the Ruby language. Now it is time to put this knowledge in place to build a larger application. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 78: RUBY IDIOMS 78 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 79: Part II Building an Application Prepared exclusively for Jared Rosoff Slide 80: RUBY IDIOMS 80 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 81: In this chapter, we’ll see • incremental development, • use cases, page ﬂow, data, and • priorities. Chapter 5 The Depot Application We could mess around all day hacking together simple test applications, but that won’t help us pay the bills. So, let’s get our teeth into something meatier. Let’s create a web-based shopping cart application called Depot. Does the world need another shopping cart application? Nope, but that hasn’t stopped hundreds of developers from writing one. Why should we be different? More seriously, it turns out that our shopping cart will illustrate many of the features of Rails development. We’ll see how to create simple maintenance pages, link database tables, handle sessions, and create forms. Over the next ten chapters, we’ll also touch on peripheral topics such as unit testing, security, and page layout. 5.1 Incremental Development We’ll be developing this application incrementally. We won’t attempt to specify everything before we start coding. Instead, we’ll work out enough of a speciﬁcation to let us start and then immediately create some functionality. We’ll try ideas, gather feedback, and continue with another cycle of mini-design and development. This style of coding isn’t always applicable. It requires close cooperation with the application’s users, because we want to gather feedback as we go along. We might make mistakes, or the client might discover they asked for one thing but really wanted something different. It doesn’t matter what the reason—the earlier we discover we’ve made a mistake, the less expensive it will be to ﬁx that mistake. All in all, with this style of development there’s a lot of change as we go along. Because of this, we need to use a toolset that doesn’t penalize us for changing our minds. If we decide we need to add a new column to a database table or change the navigation between pages, we need to be able to get in there Prepared exclusively for Jared Rosoff Slide 82: WHAT DEPOT DOES 82 and do it without a bunch of coding or conﬁguration hassle. As you’ll see, Ruby on Rails shines when it comes to dealing with change—it’s an ideal agile programming environment. Along the way we will be building and maintaining a corpus of tests. These tests will ensure that the application is always doing what we intend to do. Rails not only enables the creation of such tests, it actually provides you with an initial set of tests each time you deﬁne a new controller. Anyway, on with the application. 5.2 What Depot Does Let’s start by jotting down an outline speciﬁcation for the Depot application. We’ll look at the high-level use cases and sketch out the ﬂow through the web pages. We’ll also try working out what data the application needs (acknowledging that our initial guesses will likely be wrong). Use Cases A use case is simply a statement about how some entity uses a system. Consultants invent these kinds of phrases to label things we’ve all known all along—it’s a perversion of business life that fancy words always cost more than plain ones, even though the plain ones are more valuable. Depot’s use cases are simple (some would say tragically so). We start off by identifying two different roles or actors: the buyer and the seller. The buyer uses Depot to browse the products we have to sell, select some to purchase, and supply the information needed to create an order. The seller uses Depot to maintain a list of products to sell, to determine the orders that are awaiting shipping, and to mark orders as shipped. (The seller also uses Depot to make scads of money and retire to a tropical island, but that’s the subject of another book.) For now, that’s all the detail we need. We could go into excruciating detail about what it means to maintain products and what constitutes an order ready to ship, but why bother? If there are details that aren’t obvious, we’ll discover them soon enough as we reveal successive iterations of our work to the customer. Talking of getting feedback, let’s not forget to get some right now—let’s make sure our initial (admittedly sketchy) use cases are on the mark by asking our user. Assuming the use cases pass muster, let’s work out how the application will work from the perspectives of its various users. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 83: WHAT DEPOT DOES 83 Page Flow We always like to have an idea of the main pages in our applications and to understand roughly how users navigate between them. This early in the development, these page ﬂows are likely to be incomplete, but they still help us focus on what needs doing and know how actions are sequenced. Some folks like to mock up web application page ﬂows using Photoshop, Word, or (shudder) HTML. We like using a pencil and paper. It’s quicker, and the customer gets to play too, grabbing the pencil and scribbling alterations right on the paper. Figure 5.1: Flow of buyer pages The ﬁrst sketch of the buyer ﬂow is shown in Figure 5.1. It’s pretty traditional. The buyer sees a catalog page, from which he selects one product at a time. Each product selected gets added to the cart, and the cart is displayed after each selection. The buyer can continue shopping using the catalog pages or check out and buy the contents of the cart. During checkout, we capture contact and payment details and then display a receipt page. We don’t yet know how we’re going to handle payment, so those details are fairly vague in the ﬂow. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 84: WHAT DEPOT DOES 84 The seller ﬂow, shown in Figure 5.2, is also fairly simple. After logging in, the seller sees a menu letting her create or view a product or ship existing orders. Once viewing a product, the seller may optionally edit the product information or delete the product entirely. Figure 5.2: Flow of seller pages Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 85: WHAT DEPOT DOES 85 Figure 5.3: Initial guess at application data The shipping option is very simplistic. It displays each order that has not yet been shipped, one order per page. The seller may choose to skip to the next, or may ship the order, using the information from the page as appropriate. The shipping function is clearly not going to survive long in the real world, but shipping is also one of those areas where reality is often stranger than you might think. Overspecify it up front, and we’re likely to get it wrong. For now let’s leave it as it is, conﬁdent that we can change it as the user gains experience using our application. Data Finally, we need to think about the data we’re going to be working with. Notice that we’re not using words such as schema or classes here. We’re also not talking about databases, tables, keys, and the like. We’re simply talking about data. At this stage in the development, we don’t know whether we’ll even be using a database. Based on the use cases and the ﬂows, it seems likely that we’ll be working with the data shown in Figure 5.3. Again, using pencil and paper seems a whole lot easier than some fancy tool, but use whatever works for you. Working on the data diagram raised a couple of questions. As the user buys items, we’ll need somewhere to keep the list of products they bought, so we added a cart. But apart from its use as a transient place to keep this product list, the cart seems to be something of a ghost—we couldn’t ﬁnd anything meaningful to store in it. To reﬂect this uncertainty, we put a question mark Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 86: LET’S CODE 86 General Recovery Advice Everything in this book has been tested. If you follow along with this scenario precisely, using the recommended version of Rails and SQLite3 on Linux, Mac OS X, or Windows, then everything should work as described. However, deviations from this path may occur. Typos happen to the best of us, and side explorations are not only possible, but they are positively encouraged. Be aware that this might lead you to strange places. Don’t be afraid: speciﬁc recovery actions for common problems appear in the speciﬁc sections where such problems often occur. A few additional general suggestions are included here. You should only ever need to restart the server in the few places where doing so is noted in the book. But if you ever get truly stumped, restarting the server might be worth trying. A “magic” command worth knowing, explained in detail in part III, is rake db:migrate:redo. It will undo and reapply the last migration. If your server won’t accept some input on a form, refresh the form on your browser, and resubmit it. inside the cart’s box in the diagram. We’re assuming this uncertainty will get resolved as we implement Depot. Coming up with the high-level data also raised the question of what information should go into an order. Again, we chose to leave this fairly open for now—we’ll reﬁne this further as we start showing the customer our early iterations. Finally, you might have noticed that we’ve duplicated the product’s price in the line item data. Here we’re breaking the “initially, keep it simple” rule slightly, but it’s a transgression based on experience. If the price of a product changes, that price change should not be reﬂected in the line item price of currently open orders, so each line item needs to reﬂect the price of the product at the time the order was made. Again, at this point we’ll double-check with the customer that we’re still on the right track. (The customer was most likely sitting in the room with us while we drew these three diagrams.) 5.3 Let’s Code So, after sitting down with the customer and doing some preliminary analysis, we’re ready to start using a computer for development! We’ll be working from our original three diagrams, but the chances are pretty good that we’ll be throwing them away fairly quickly—they’ll become outdated as we gather feedReport erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 87: LET’S CODE 87 back. Interestingly, that’s why we didn’t spend too long on them—it’s easier to throw something away if you didn’t spend a long time creating it. In the chapters that follow, we’ll start developing the application based on our current understanding. However, before we turn that page, we have to answer just one more question: what should we do ﬁrst? We like to work with the customer so we can jointly agree on priorities. In this case, we’d point out to her that it’s hard to develop anything else until we have some basic products deﬁned in the system, so we’d suggest spending a couple of hours getting the initial version of the product maintenance functionality up and running. And, of course, she’d agree. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 88: LET’S CODE 88 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 89: In this chapter, we’ll see • • • • creating a new application, conﬁguring the database creating models and controllers, and updating a layout and a view. Chapter 6 Task A: Creating the Application Our ﬁrst development task is to create the web interface that lets us maintain our product information—create new products, edit existing products, delete unwanted ones, and so on. We’ll develop this application in small iterations, where small means “measured in minutes.” Let’s get started. Typically, our iterations will involve multiple steps, as in iteration C will have steps C1, C2, C3, and so on. In this case, the iteration will have two steps. 6.1 Iteration A1: Creating the Products Maintenance Application At the heart of the Depot application is a database. Getting this installed and conﬁgured and tested before proceeding further will prevent a lot of headaches. If you aren’t sure of what you want, go with the defaults, and it will go easy. If you already know what you want, Rails makes it easy for you to describe your conﬁguration. Creating a Rails Application Back on page 41, we saw how to create a new Rails application. We’ll do the same thing here. Go to a command prompt, and type rails new followed by the name of our project. In this case, our project is called depot, so make sure that you are not inside an existing application directory and type this: work> rails new depot We see a bunch of output scroll by. When it has ﬁnished, we ﬁnd that a new directory, depot, has been created. That’s where we’ll be doing our work. work> cd depot depot> ls -p app/ config.ru config/ db/ doc/ Gemfile lib/ log/ public/ Rakefile README script/ test/ tmp/ vendor/ Prepared exclusively for Jared Rosoff Slide 90: ITERATION A1: CREATING THE PRODUCTS MAINTENANCE APPLICATION 90 Creating the Database For this application, we’ll use the open source SQLite database (which you’ll need too if you’re following along with the code). We’re using SQLite version 3 here. SQLite 3 is the default database for Rails development, and was installed along with Rails itself in Chapter 1, Installing Rails, on page 29. With SQLite 3 there are no steps required to create a database, and there are no special user accounts or passwords to deal with. So, now you get to experience one of the beneﬁts of going with the ﬂow (Or, convention over conﬁguration, as Rails folks say ad nauseam). If, however, it is important to you to use a database server other than SQLite 3, the commands you’ll need to create the database and grant permissions will be different. You will ﬁnd some helpful hints in the Getting Started Rails Guide1 . Generating the Scaffold Back in Figure 5.3, on page 85, we sketched out the basic content of the products table. Now let’s turn that into reality. We need to create a database table and a Rails model that lets our application use that table, a number of views to make up the user interface, and a controller to orchestrate the application. So, let’s go ahead and create the model, views, controller and migration for our products table. With Rails, you can do all that with one command by asking Rails to generate what is known as a scaffold for a given model. Note that on the command line2 that follows, we use the singular form, Product. In Rails, a model is automatically mapped to a database table whose name is the plural form of the model’s class. In our case, we asked for a model called Product, so Rails associated it with the table called products. (And how will it ﬁnd that table? The development entry in conﬁg/database.yml tells Rails where to look for it. For SQLite 3 users, this will be a ﬁle in the db directory.) depot> rails generate scaffold Product \ title:string description:text image_url:string price:decimal invoke active_record create db/migrate/20100301000001_create_products.rb create app/models/product.rb invoke test_unit create test/unit/product_test.rb create test/fixtures/products.yml route resources :products 1. http://guides.rubyonrails.org/getting_started.html#conﬁguring-a-database 2. This command is too wide to ﬁt comfortably on the page. To enter a command on multiple lines, name mapping ֒ page 287 → simply put a backslash as the last character on all but the last line, and you will be prompted for more input. Windows users will need to substitute a caret (^) for the backslash. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 91: ITERATION A1: CREATING THE PRODUCTS MAINTENANCE APPLICATION 91 invoke create invoke create create create create create create invoke create invoke create invoke create scaffold_controller app/controllers/products_controller.rb erb app/views/products app/views/products/index.html.erb app/views/products/edit.html.erb app/views/products/show.html.erb app/views/products/new.html.erb app/views/products/_form.html.erb test_unit test/functional/products_controller_test.rb helper app/helpers/products_helper.rb test_unit test/unit/helpers/products_helper_test.rb The generator creates a bunch of ﬁles. The one we’re interested in ﬁrst is the migration one, namely 20100301000001_create_products.rb. A migration represents a change we want to make to the data, expressed in a source ﬁle in database-independent terms. These changes can update both the database schema and the data in the database tables. We apply these migrations to update our database, and we can unapply them to roll our database back. We have a whole section on migrations starting on page 407. For now, we’ll just use them without too much more comment. The migration has a UTC-based timestamp preﬁx (20100301000001), a name (create_products), and a ﬁle extension (.rb, because it’s a Ruby program). The timestamp preﬁx you will see will be different. In fact, the timestamps used in this book are clearly ﬁctitious. Typically your timestamps will not be consecutive, instead they will reﬂect the time the migration was created. Applying the Migration While we have already told Rails about the basic data types of each property, let’s go ahead and reﬁne the deﬁnition of the price to have eight digits of signiﬁcance, and two digits after the decimal point. Download depot_a/db/migrate/20100301000001_create_products.rb class CreateProducts < ActiveRecord::Migration def self.up create_table :products do \|t\| t.string :title t.text :description t.string :image_url t.decimal :price, :precision => 8, :scale => 2 t.timestamps end end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 92: ITERATION A1: CREATING THE PRODUCTS MAINTENANCE APPLICATION 92 def self.down drop_table :products end end Now that we are done with our changes, we need to get Rails to apply this migration to our development database. We do this using the rake command. Rake is like having a reliable assistant on hand all the time: you tell it to do some task, and that task gets done. In this case, we’ll tell Rake to apply any unapplied migrations to our database: depot> rake db:migrate (in /Users/rubys/work/depot) == CreateProducts: migrating ================================================= -- create_table(:products) -> 0.0027s == CreateProducts: migrated (0.0023s) ======================================== And that’s it. Rake looks for all the migrations not yet applied to the database and applies them. In our case, the products table is added to the database deﬁned by the development section of the database.yml ﬁle. OK, all the groundwork has been done. We set up our Depot application as a Rails project. We created the development database and conﬁgured our application to be able to connect to it. We created a product controller and a product model and used a migration to create the corresponding products table. And a number of views have been created for us. It’s time to see all this in action. See the List of Products With three commands we have created an application and a database (or a table inside an existing database, if you chose something other than SQLite 3). Before we worry too much about just what happened behind the scenes here, let’s try our shiny new application. First, we’ll start a local server, supplied with Rails: depot> rails server => Booting WEBrick => Rails 3.0.0 application starting in development on http://0.0.0.0:3000 => Call with -d to detach => Ctrl-C to shutdown server [2010-05-05 17:45:38] INFO WEBrick 1.3.1 [2010-05-05 17:45:38] INFO ruby 1.8.7 (2010-01-10) [x86_64-linux] [2010-05-05 17:45:43] INFO WEBrick::HTTPServer#start: pid=24649 port=3000 Just as it did with our demo application in Chapter 2, Instant Gratiﬁcation, this command starts a web server on our local host, port 3000. If you get an error saying Address already in use when you try to run the server, that simply means that you already have a Rails server running on your machine. If you’ve been Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 93: ITERATION A1: CREATING THE PRODUCTS MAINTENANCE APPLICATION 93 following along with the examples in the book, that might well be the “Hello, World!” application from Chapter 4. Find its console, and kill the server using Ctrl-C. If you are running on Windows, you may see the prompt Terminate batch job (Y/N)?. If so, respond with y. Let’s connect to it. Remember, the URL we give to our browser contains both the port number (3000) and the name of the controller in lowercase (products). That’s pretty boring. It’s showing us an empty list of products. Let’s add some. Click the New product link, and a form should appear. These forms are simply HTML templates, just like the ones you created in Section 2.2, Hello, Rails!, on page 43. In fact, we can modify them. Let’s change the number of lines in the description ﬁeld: Download depot_a/app/views/products/_form.html.erb <%= form_for(@product) do \|f\| %> <% if @product.errors.any? %> <div id="error_explanation"> Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 94: ITERATION A1: CREATING THE PRODUCTS MAINTENANCE APPLICATION 94 <h2><%= pluralize(@product.errors.count, "error" ) %> prohibited this product from being saved:</h2> <ul> <% @product.errors.full_messages.each do \|msg\| %> <li><%= msg %></li> <% end %> </ul> </div> <% end %> <div class="field"> <%= f.label :title %><br /> <%= f.text_field :title %> </div> <div class="field"> <%= f.label :description %><br /> <%= f.text_area :description, :rows => 6 %> </div> <div class="field"> <%= f.label :image_url %><br /> <%= f.text_field :image_url %> </div> <div class="field"> <%= f.label :price %><br /> <%= f.text_field :price %> </div> <div class="actions"> <%= f.submit %> </div> <% end %> We will explore this more in Chapter 8, Task C: Catalog Display, on page 117. But for now: we’ve adjusted one ﬁeld to taste, so let’s go ahead and ﬁll it in: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 95: ITERATION A1: CREATING THE PRODUCTS MAINTENANCE APPLICATION 95 Click the Create button, and you should see the new product was successfully created. If you now click the Back link, you should see the new product in the list: Perhaps it isn’t the prettiest interface, but it works, and we can show it to our client for approval. She can play with the other links (showing details, editing existing products, and so on...). We explain to her that this is only a ﬁrst step—we know it’s rough, but we wanted to get her feedback early. (And three commands probably count as early in anyone’s book.) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 96: ITERATION A2: MAKING PRETTIER LISTINGS 96 At this point, you’ve accomplished a lot with only four commands. Before we move on, let’s try one more command: rake test Included in the output should be two lines that each say 0 failures, 0 errors. This is for the unit, functional, and integration tests that Rails generates along with the scaffolding. They are minimal at this point, but simply knowing that they are there and that they pass should give you conﬁdence. As you proceed through these chapters in Part II, you are encouraged to run this command frequently as it will help you spot and track down errors. We will cover this more in Section 7.2, Iteration B2: Unit Testing of Models, on page 108. Note: if you’ve used a database other than SQLite3, this step may have failed. Check your database.yml ﬁle and see notes on page 427. 6.2 Iteration A2: Making Prettier Listings Our customer has one more request (customers always seem to have one more request). The listing of all the products is ugly. Can we “pretty it up” a bit? And, while we’re in there, can we also display the product image along with the image URL? We’re faced with a dilemma here. As developers, we’re trained to respond to these kinds of requests with a sharp intake of breath, a knowing shake of the head, and a murmured “You want what?” At the same time, we also like to show off a bit. In the end, the fact that it’s fun to make these kinds of changes using Rails wins out, and we ﬁre up our trusty editor. Before we get too far, though, it would be nice if we had a consistent set of test data to work with. We could use our scaffold-generated interface and type data in from the browser. However, if we did this, future developers working on our codebase would have to do the same. And, if we were working as part of a team on this project, each member of the team would have to enter their own data. It would be nice if we could load the data into our table in a more controlled way. It turns out that we can. Rails has the ability to import seed data. To start, we simply modify the ﬁle in the db directory named seeds.rb. We then add the code to populate the products table. This uses the create method of the Product model. The following is an extract from that ﬁle. Rather than type the ﬁle in by hand, you might want to download the ﬁle from the sample code available online3 . 3. http://media.pragprog.com/titles/rails4/code/depot_b/db/seeds.rb download ֒ page 23 → Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 97: ITERATION A2: MAKING PRETTIER LISTINGS 97 While you’re there, copy the images4 and the depot.css ﬁle5 into corresponding places (public/images and public/stylesheets in your application). Be warned: this seeds.rb script removes existing data from the products table before loading in the new data. You might not want to run it if you’ve just spent several hours typing your own data into your application! Download depot_b/db/seeds.rb Product.delete_all Product.create(:title => 'Programming Ruby 1.9' , :description => %{<p> Ruby is the fastest growing and most exciting dynamic language out there. If you need to get working programs delivered fast, you should add Ruby to your toolbox. </p>}, :image_url => '/images/ruby.jpg' , :price => 49.50) #... (Note that this code uses %{...}. This is an alternative syntax for double-quoted string literals, convenient for use with long strings. Note also that because it uses Rails’ create method, it will fail silently if records cannot be inserted because of validation errors.) To populate your products table with test data, simply run the following command: depot> rake db:seed Now let’s get the product listing tidied up. There are two pieces to this. Eventually we’ll be writing some HTML that uses CSS to style the presentation. But for this to work, we’ll need to tell the browser to fetch the stylesheet. We need somewhere to put our CSS style deﬁnitions. All scaffold-generated applications use the stylesheet scaffold.css in the directory public/stylesheets. Rather than alter this ﬁle, we created a new application stylesheet, depot.css, and put it in the same directory.6 . Finally, we need to link these stylesheets into our HTML page. If you look at the .html.erb ﬁles we’ve created so far, you won’t ﬁnd any reference to stylesheets. You won’t even ﬁnd the HTML <head> section where such references would normally live. Instead, Rails keeps a separate ﬁle that is used to create a standard page environment for the entire application. This ﬁle, called application.html.erb, is a Rails layout and lives in the layouts directory: 4. http://media.pragprog.com/titles/rails4/code/depot_b/public/images 5. http://media.pragprog.com/titles/rails4/code/depot_b/public/stylesheets/depot.css 6. If you haven’t already done so, this stylesheet can be downloaded http://media.pragprog.com/titles/rails4/code/depot_b/public/stylesheets/depot.css from Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 98: ITERATION A2: MAKING PRETTIER LISTINGS 98 Download depot_b/app/views/layouts/application.html.erb <!DOCTYPE html> <html> <head> <title>Depot</title> <%= stylesheet_link_tag :all %> <%= javascript_include_tag :defaults %> <%= csrf_meta_tag %> </head> <body> <%= yield %> </body> </html> The stylesheet_link_tag creates an HTML <link> tag, which loads stylesheets from the public/stylesheets directory. We could list the name of the stylesheets we want to be linked here, but as it is currently set up to load all stylesheets, we’ll leave it alone for now. We’ll look at the rest of the ﬁle in more detail in Section 8.2, Iteration C2: Adding a Page Layout, on page 120. Now that we have the stylesheet all in place, we will use a simple tablebased template, editing the ﬁle index.html.erb in app/views/products, replacing the scaffold-generated view: Download depot_b/app/views/products/index.html.erb <div id="product_list"> <h1>Listing products</h1> <table> <% @products.each do \|product\| %> <tr class="<%= cycle('list_line_odd', 'list_line_even') %>"> <td> <%= image_tag(product.image_url, :class => 'list_image') %> </td> <td class="list_description"> <dl> <dt><%= product.title %></dt> <dd><%= truncate(strip_tags(product.description), :length => 80) %></dd> </dl> </td> <td class="list_actions"> <%= link_to 'Show', product %><br/> <%= link_to 'Edit', edit_product_path(product) %><br/> <%= link_to 'Destroy', product, :confirm => 'Are you sure?', :method => :delete %> Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 99: ITERATION A2: MAKING PRETTIER LISTINGS 99 What’s with :method => :delete? You may have noticed that the scaffold-generated Destroy link includes the parameter :method => :delete. This determines which method is called in the ProductsController class and also affects which HTTP method is used. Browsers use HTTP to talk with servers. HTTP deﬁnes a set of verbs that browsers can employ and deﬁnes when each can be used. A regular hyperlink, for example, uses an HTTP GET request. A GET request is deﬁned by HTTP to be used to retrieve data; it isn’t supposed to have any side effects. Using this parameter in this way indicates that an HTTP DELETE method should be used for this hyperlink. Rails uses this information to determine which action in the controller to route this request to. Note: when used within a browser, Rails will substitute the POST HTTP method for PUT and DELETE methods, and in the process tack on an additional parameter so that the router can determine the original intent. Either way, the request will not be cached or triggered by web crawlers. </td> </tr> <% end %> </table> </div> <br /> <%= link_to 'New product', new_product_path %> Even this simple template uses a number of built-in Rails features: • The rows in the listing have alternating background colors. The Rails helper method called cycle does this by setting the CSS class of each row to either list_line_even or list_line_odd, automatically toggling between the two style names on successive lines. • The truncate helper is used to display just the ﬁrst eighty characters of the description. But before we call truncate, we called strip_tags in order to remove the HTML tags from the description. • Look at the link_to ’Destroy’ line. See how it has the parameter :conﬁrm => ’Are you sure?’. If you click this link, Rails arranges for your browser to pop up a dialog box asking for conﬁrmation before following the link and deleting the product. (Also, see the sidebar on this page for some inside scoop on this action.) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 100: ITERATION A2: MAKING PRETTIER LISTINGS 100 We loaded some test data into the database, we rewrote the index.html.erb ﬁle that displays the listing of products, we added a depot.css stylesheet, and that stylesheet was loaded into our page by the layout ﬁle application.html.erb. Now, lets bring up a browser, point to http://localhost:3000/products, and the resulting product listing might look something like the following: So, we proudly show our customer her new product listing, and she’s pleased. Now it is time to create the storefront. What We Just Did In this chapter, we laid the groundwork for our store application: • We created a development database. • We used migration to create and modify the schema in our development database. • We created the products table and used the scaffold generator to write an application to maintain it. • Updated an application wide layout as well as controller speciﬁc view in order to show a list of products. What we’ve done did not require much effort, and got us up and running quickly. Databases are vital to this application, but need not be scary—in fact in many cases we can defer to later the selection of the database, and simply get started using the default that Rails provides. Getting the model right is more important at this stage. As we will soon see, simple selection of data types doesn’t always fully capture the essence of all of Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 101: ITERATION A2: MAKING PRETTIER LISTINGS 101 the properties of the model, even in this small application, so that’s what we will tackle next. Playtime Here’s some stuff to try on your own: • If you’re feeling frisky, you can experiment with rolling back the migration. Just type the following: depot> rake db:rollback Your schema will be transported back in time, and the products table will be gone. Calling rake db:migrate again will re-create it. You will also want to reload the seed data. More information can be found in Chapter 23, Migrations, on page 407 • We mentioned version control in Section 1.5, Version Control, on page 35, and now would be a great point at which to save your work. Should you happen to choose git (highly recommended, by the way), there is a tiny bit of conﬁguration you need to do ﬁrst – basically all you need to do is provide your name and email address. This typically goes into your home directory, with a ﬁlename of .gitconﬁg. Mine looks like this: [user] name = Sam Ruby email = rubys@intertwingly.net You can verify the conﬁguration with the following command: depot> git repo-config --get-regexp user.* Rails also provides a ﬁle named .gitignore, which tells Git which ﬁles are not to be version controlled: Download depot_b/.gitignore .bundle db/.sqlite3 log/.log tmp/*/ Note that as this ﬁlename begins with a dot, Unix based operating systems won’t show it by default in directory listings. Use ls -a to see it. At this point, you are fully conﬁgured. The only tasks that remain are to initialize a database, add in all of the ﬁles, and commit them with a commit message: depot> git init depot> git add . depot> git commit -m "Depot Scaffold" Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 102: ITERATION A2: MAKING PRETTIER LISTINGS 102 This may not seem very exciting at this point, but it does mean that you are more free to experiment. Should you overwrite or delete a ﬁle that you didn’t mean to, you can get back to this point by issuing a single command: depot> git checkout . Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 103: In this chapter, we’ll see • performing validation and error reporting, and • unit testing. Chapter 7 Task B: Validation and Unit Testing At this point, we have an initial model for a Product, as well as a complete maintenance application for this data provided for us by Rails scaffolding. In this chapter, we are going to focus on making the model more bulletproof – as in, making sure that errors in the data provided never get committed to the database – before we proceed onto other aspects of the Depot application in subsequent chapters. 7.1 Iteration B1: Validating! While playing with the results of iteration A1, our client noticed something. If she entered an invalid price or forgot to set up a product description, the application happily accepted the form and added a line to the database. Although a missing description is embarrassing, a price of $0.00 actually costs her money, so she asked that we add validation to the application. No product should be allowed in the database if it has an empty title or description ﬁeld, an invalid URL for the image, or an invalid price. So, where do we put the validation? The model layer is the gatekeeper between the world of code and the database. Nothing to do with our application comes out of the database or gets stored into the database that doesn’t ﬁrst go through the model. This makes models an ideal place to put validations; it doesn’t matter whether the data comes from a form or from some programmatic manipulation in our application. If a model checks it before writing to the database, then the database will be protected from bad data. Let’s look again at the source code of the model class (in app/models/product.rb): class Product < ActiveRecord::Base end Prepared exclusively for Jared Rosoff Slide 104: ITERATION B1: VALIDATING! 104 Adding our validation should be fairly clean. Let’s start by validating that the text ﬁelds all contain something before a row is written to the database. We do this by adding some code to the existing model: validates :title, :description, :image_url, :presence => true The validates method is the standard Rails validator. It will check one or more model ﬁelds against one or more conditions. :presence => true tells the validator to check that each of the named ﬁelds is present and its contents are not empty. In Figure 7.1, on the next page, we can see what happens if we try to submit a new product with none of the ﬁelds ﬁlled in. It’s pretty impressive: the ﬁelds with errors are highlighted, and the errors are summarized in a nice list at the top of the form. That’s not bad for one line of code. You might also have noticed that after editing and saving the product.rb ﬁle you didn’t have to restart the application to test your changes—the same reloading that caused Rails to notice the earlier change to our schema also means it will always use the latest version of our code. We’d also like to validate that the price is a valid, positive number. We’ll use the delightfully named numericality option to verify that the price is a valid number. We also pass the rather verbosely named :greater_than_or_equal_to option a value of 0.01: validates :price, :numericality => {:greater_than_or_equal_to => 0.01} Now, if we add a product with an invalid price, the appropriate message will appear, as shown in Figure 7.2, on page 106. Why test against 1 cent, rather than zero? Well, it’s possible to enter a number such as 0.001 into this ﬁeld. Because the database stores just two digits after the decimal point, this would end up being zero in the database, even though it would pass the validation if we compared against zero. Checking that the number is at least 1 cent ensures only correct values end up being stored. We have two more items to validate. First, we want to make sure that each product has a unique title. One more line in the Product model will do this. The uniqueness validation will perform a simple check to ensure that no other row in the products table has the same title as the row we’re about to save: validates :title, :uniqueness => true Lastly, we need to validate that the URL entered for the image is valid. We’ll do this using the format option, which matches a ﬁeld against a regular expression. For now we’ll just check that the URL ends with one of .gif, .jpg, or .png: validates :image_url, :format => { :with => %r{\.(gif\|jpg\|png)$}i, :message => 'must be a URL for GIF, JPG or PNG image.' regular expression ֒ page 68 → Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 105: ITERATION B1: VALIDATING! 105 Figure 7.1: Validating that ﬁelds are present } Later, we’d probably want to change this form to let the user select from a list of available images, but we’d still want to keep the validation to prevent malicious folks from submitting bad data directly. So, in a couple of minutes we’ve added validations that check the following: • The ﬁeld’s title, description, and image URL are not empty. • The price is a valid number not less than $0.01. • The title is unique among all products. • The image URL looks reasonable. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 106: ITERATION B1: VALIDATING! 106 Figure 7.2: The price fails validation. Your updated Product model should look like this: Download depot_b/app/models/product.rb class Product < ActiveRecord::Base validates :title, :description, :image_url, :presence => true validates :price, :numericality => {:greater_than_or_equal_to => 0.01} validates :title, :uniqueness => true validates :image_url, :format => { :with => %r{\.(gif\|jpg\|png)$}i, :message => 'must be a URL for GIF, JPG or PNG image.' } end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 107: ITERATION B1: VALIDATING! 107 Nearing the end of this cycle, we ask our customer to play with the application, and she’s a lot happier. It took only a few minutes, but the simple act of adding validation has made the product maintenance pages seem a lot more solid. Before we move on, we once again try our tests: rake test Uh oh. This time we see failures. Two, actually. One in test_should_create_product and one in test_should_update_product. Clearly something we did caused something to do with the creation and updating of products to fail. This isn’t all that surprising. After all, when you think about it, isn’t that the whole point of validation? The solution is to provide valid test data in test/functional/products_controller_test.rb: Download depot_c/test/functional/products_controller_test.rb require 'test_helper' class ProductsControllerTest < ActionController::TestCase # ... setup do @product = products(:one) @update = { :title => 'Lorem Ipsum' , :description => 'Wibbles are fun!' , :image_url => 'lorem.jpg' , :price => 19.95 } end test "should get index" do get :index assert_response :success assert_not_nil assigns(:products) end test "should get new" do get :new assert_response :success end test "should create product" do assert_difference('Product.count' ) do post :create, :product => @update end assert_redirected_to product_path(assigns(:product)) end # ... test "should update product" do put :update, :id => @product.to_param, :product => @update Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 108: ITERATION B2: UNIT TESTING OF MODELS 108 assert_redirected_to product_path(assigns(:product)) end # ... end After making this change, we rerun the tests, and they report that all is well. But all that means is that we didn’t break anything. We need to do more than that. We need to make sure that our validation code that we just added not only works now, but will continue to work as we make further changes. We’ll cover functional tests in more detail in Section 8.4, Iteration C4: Functional Testing of Controllers, on page 124. As for now, it is time for us to write some unit tests. 7.2 Iteration B2: Unit Testing of Models One of the real joys of the Rails framework is that it has support for testing baked right in from the start of every project. As we have seen, from the moment you create a new application using the rails command, Rails starts generating a test infrastructure for you. Let’s take a peek inside the unit subdirectory to see what’s already there: depot> ls test/unit helpers product_test.rb product_test.rb is the ﬁle that Rails created to hold the unit tests for the model we created earlier with the generate script. This is a good start, but Rails can help us only so much. Let’s see what kind of test goodies Rails generated inside the ﬁle test/unit/product_test.rb when we generated that model: Download depot_b/test/unit/product_test.rb require 'test_helper' class ProductTest < ActiveSupport::TestCase # Replace this with your real tests. test "the truth" do assert true end end The generated ProductTest is a subclass of ActiveSupport::TestCase. The fact that ActiveSupport::TestCase is a subclass of the Test::Unit::TestCase class tells us that Rails generates tests based on the Test::Unit framework that comes preinstalled with Ruby. This is good news because it means if we’ve already been testing our Ruby programs with Test::Unit tests (and why wouldn’t we be?), Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 109: ITERATION B2: UNIT TESTING OF MODELS 109 then we can build on that knowledge to test Rails applications. If you’re new to Test::Unit, don’t worry. We’ll take it slow. Inside this test case, Rails generated a single test called "the truth". The test...do syntax may seem surprising at ﬁrst, but here ActiveSupport is combining a class method, optional parenthesis, and a block to make deﬁning a test method just the tiniest bit simpler for you. Sometimes it is the little things that make all the difference. The assert line in this method is an actual test. It isn’t much of one, though— all it does is test that true is true. Clearly, this is a placeholder, but it’s an important one, because it lets us see that all the testing infrastructure is in place. A Real Unit Test Let’s get onto the business of testing validation. First, if we create a product with no attributes set, we’ll expect it to be invalid and for there to be an error associated with each ﬁeld. We can use the model’s valid? and invalid? methods to see whether it validates, and we can use the any? method of the error list to see whether or not there is an error associated with a particular attribute. Now that we know what to test, we need to know how to tell the test framework whether our code passes or fails. We do that using assertions. An assertion is simply a method call that tells the framework what we expect to be true. The simplest assertion is the method assert, which expects its argument to be true. If it is, nothing special happens. However, if the argument to assert is false, the assertion fails. The framework will output a message and will stop executing the test method containing the failure. In our case, we expect that an empty Product model will not pass validation, so we can express that expectation by asserting that it isn’t valid. assert product.invalid? Let’s write the full test: Download depot_c/test/unit/product_test.rb test "product attributes must not be empty" do product = Product.new assert product.invalid? assert product.errors[:title].any? assert product.errors[:description].any? assert product.errors[:price].any? assert product.errors[:image_url].any? end We can rerun just the unit tests by issuing the command rake test:units. When we do so, we now see two tests executed (the original the truth test and our new test): Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 110: ITERATION B2: UNIT TESTING depot> rake test:units Loaded suite lib/rake/rake_test_loader Started .. Finished in 0.092314 seconds. 2 tests, 6 assertions, 0 failures, 0 errors OF MODELS 110 Sure enough, the validation kicked in, and all our assertions passed. Clearly at this point we can dig deeper and exercise individual validations. Let’s look at just three of the many possible tests. First, we’ll check that the validation of the price works the way we expect: Download depot_c/test/unit/product_test.rb test "product price must be positive" do product = Product.new(:title => "My Book Title" , :description => "yyy" , :image_url => "zzz.jpg" ) product.price = -1 assert product.invalid? assert_equal "must be greater than or equal to 0.01" , product.errors[:price].join('; ' ) product.price = 0 assert product.invalid? assert_equal "must be greater than or equal to 0.01" , product.errors[:price].join('; ' ) product.price = 1 assert product.valid? end In this code we create a new product and then try setting its price to -1, 0, and +1, validating the product each time. If our model is working, the ﬁrst two should be invalid, and we verify the error message associated with the price attribute is what we expect. The last price is acceptable, so we assert that the model is now valid. (Some folks would put these three tests into three separate test methods—that’s perfectly reasonable.) Next, we’ll test that we’re validating that the image URL ends with one of .gif, .jpg, or .png: Download depot_c/test/unit/product_test.rb def new_product(image_url) Product.new(:title :description :price :image_url end test "image url" do => => => => "My Book Title" , "yyy" , 1, image_url) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 111: ITERATION B2: UNIT TESTING OF MODELS 111 ok = %w{ fred.gif fred.jpg fred.png FRED.JPG FRED.Jpg http://a.b.c/x/y/z/fred.gif } bad = %w{ fred.doc fred.gif/more fred.gif.more } ok.each do \|name\| assert new_product(name).valid?, "#{name} shouldn't be invalid" end bad.each do \|name\| assert new_product(name).invalid?, "#{name} shouldn't be valid" end end Here we’ve mixed things up a bit. Rather than write out the nine separate tests, we’ve used a couple of loops, one to check the cases we expect to pass validation, the second to try cases we expect to fail. At the same time, we factored out the common code between the two loops. You’ll notice that we’ve also added an extra parameter to our assert method calls. All of the testing assertions accept an optional trailing parameter containing a string. This will be written along with the error message if the assertion fails and can be useful for diagnosing what went wrong. Finally, our model contains a validation that checks that all the product titles in the database are unique. To test this one, we’re going to need to store product data in the database. One way to do this would be to have a test create a product, save it, then create another product with the same title, and try to save it too. This would clearly work. But there’s a much simpler way—we can use Rails ﬁxtures. Test Fixtures In the world of testing, a ﬁxture is an environment in which you can run a test. If you’re testing a circuit board, for example, you might mount it in a test ﬁxture that provides it with the power and inputs needed to drive the function to be tested. In the world of Rails, a test ﬁxture is simply a speciﬁcation of the initial contents of a model (or models) under test. If, for example, we want to ensure that our products table starts off with known data at the start of every unit test, we can specify those contents in a ﬁxture, and Rails will take care of the rest. You specify ﬁxture data in ﬁles in the test/ﬁxtures directory. These ﬁles contain test data in either comma-separated value (CSV) or YAML format. For our tests, we’ll use YAML, the preferred format. Each ﬁxture ﬁle contains the data for a single model. The name of the ﬁxture ﬁle is signiﬁcant; the base name of the ﬁle must match the name of a database table. Because we need some data for a Product model, which is stored in the products table, we’ll add it to the ﬁle YAML ֒ page 73 → Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 112: ITERATION B2: UNIT TESTING OF MODELS 112 called products.yml. Rails already created this ﬁxture ﬁle when we ﬁrst created the model: Download depot_b/test/ﬁxtures/products.yml # Read about fixtures at http://ar.rubyonrails.org/classes/Fixtures.html one: title: MyString description: MyText image_url: MyString price: 9.99 two: title: MyString description: MyText image_url: MyString price: 9.99 The ﬁxture ﬁle contains an entry for each row that we want to insert into the database. Each row is given a name. In the case of the Rails-generated ﬁxture, the rows are named one and two. This name has no signiﬁcance as far as the database is concerned—it is not inserted into the row data. Instead, as we’ll see shortly, the name gives us a convenient way to reference test data inside our test code. They also are the names used in the generated integration tests, so for now, we’ll leave them alone. Inside each entry you’ll see an indented list of name/value pairs. Just like in your conﬁg/database.yml, you must use spaces, not tabs, at the start of each of the data lines, and all the lines for a row must have the same indentation. Be careful as you make changes because you will need to make sure the names of the columns are correct in each entry; a mismatch with the database column names may cause a hard-to-track-down exception. Let’s add some more data to the ﬁxture ﬁle with something we can use to test our product model. (Note that you do not have to include the id column in test ﬁxtures.) Download depot_c/test/ﬁxtures/products.yml ruby: title: Programming Ruby 1.9 description: Ruby is the fastest growing and most exciting dynamic language out there. If you need to get working programs delivered fast, you should add Ruby to your toolbox. price: 49.50 image_url: ruby.png Now that we have a ﬁxture ﬁle, we want Rails to load up the test data into the products table when we run the unit test. And, in fact, Rails is already doing Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 113: ITERATION B2: UNIT TESTING OF MODELS 113 David Says. . . Picking Good Fixture Names Just like the names of variables in general, you want to keep the names of ﬁxtures as self-explanatory as possible. This increases the readability of the tests when you’re asserting that product(:valid_order_for_fred) is indeed Fred’s valid order. It also makes it a lot easier to remember which ﬁxture you’re supposed to test against without having to look up p1 or order4. The more ﬁxtures you get, the more important it is to pick good ﬁxture names. So, starting early keeps you happy later. But what do we do with ﬁxtures that can’t easily get a self-explanatory name like valid_order_for_fred? Pick natural names that you have an easier time associating to a role. For example, instead of using order1, use christmas_order. Instead of customer1, use fred. Once you get into the habit of natural names, you’ll soon be weaving a nice little story about how fred is paying for his christmas_order with his invalid_credit_card ﬁrst, then paying with his valid_credit_card, and ﬁnally choosing to ship it all off to aunt_mary. Association-based stories are key to remembering large worlds of ﬁxtures with ease. this (convention over conﬁguration for the win!), but you can control which ﬁxtures to load by specifying the following line in test/unit/product_test.rb: class ProductTest < ActiveSupport::TestCase fixtures :products #... end The ﬁxtures directive loads the ﬁxture data corresponding to the given model name into the corresponding database table before each test method in the test case is run. The name of the ﬁxture ﬁle determines the table that is loaded, so using :products will cause the products.yml ﬁxture ﬁle to be used. Let’s say that again another way. In the case of our ProductTest class, adding the ﬁxtures directive means that the products table will be emptied out and then populated with the three rows deﬁned in the ﬁxture before each test method is run. The products method indexes into that table. We need to change the index used to match the name we gave in the ﬁxture. So far, we’ve been doing all our work in the development database. Now that we’re running tests, though, Rails needs to use a test database. If you look in Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 114: ITERATION B2: UNIT TESTING OF MODELS 114 the database.yml ﬁle in the conﬁg directory, you’ll notice Rails actually created a conﬁguration for three separate databases. • db/development.sqlite3 will be our development database. All of our programming work will be done here. • db/test.sqlite3 is a test database. • db/production.sqlite3 is the production database. Our application will use this when we put it online. Each test method gets a freshly initialized table in the test database, loaded from the ﬁxtures we provide. This is automatically done by the rake test command, but can be done separately by running rake db:test:prepare. Using Fixture Data Now that we know how to get ﬁxture data into the database, we need to ﬁnd ways of using it in our tests. Clearly, one way would be to use the ﬁnder methods in the model to read the data. However, Rails makes it easier than that. For each ﬁxture it loads into a test, Rails deﬁnes a method with the same name as the ﬁxture. You can use this method to access preloaded model objects containing the ﬁxture data: simply pass it the name of the row as deﬁned in the YAML ﬁxture ﬁle, and it’ll return a model object containing that row’s data. In the case of our product data, calling products(:ruby) returns a Product model containing the data we deﬁned in the ﬁxture. Let’s use that to test the validation of unique product titles: Download depot_c/test/unit/product_test.rb test "product is not valid without a product = Product.new(:title :description :price :image_url unique title" do => products(:ruby).title, => "yyy" , => 1, => "fred.gif" ) assert !product.save assert_equal "has already been taken" , product.errors[:title].join('; ' ) end The test assumes that the database already includes a row for the Ruby book. It gets the title of that existing row using this: products(:ruby).title It then creates a new Product model, setting its title to that existing title. It asserts that attempting to save this model fails and that the title attribute has the correct error associated with it. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 115: ITERATION B2: UNIT TESTING OF MODELS 115 If you want to avoid using a hard-coded string for the Active Record error, you can compare the response against its built-in error message table: Download depot_c/test/unit/product_test.rb test "product is not valid without a product = Product.new(:title :description :price :image_url unique title - i18n" do => products(:ruby).title, => "yyy" , => 1, => "fred.gif" ) assert !product.save assert_equal I18n.translate('activerecord.errors.messages.taken' ), product.errors[:title].join('; ' ) end We will cover the I18n functions in Chapter 15, Task J: Internationalization, on page 233. Now we can feel conﬁdent that our validation code not only works, but will continue to work. Our product now has a model, a set of views, a controller, and a set of unit tests. It will serve as a good foundation upon which to build the rest of the application. What We Just Did In just about a dozen lines of code, we augmented that generated code with validation: • We ensured that required ﬁelds were present. • We ensured that price ﬁelds were numeric, and at least one cent. • We ensured that titles were unique. • We ensured that images matched a given format. • We updated the unit tests that Rails provided, both to conform to the constraints we have imposed on the model and to verify the new code that we added. We show this to our customer, and while she agrees that this is something an administrator could use, she says that it certainly isn’t anything that she would feel comfortable turning loose on her customers. Clearly, in the next iteration we are going to have to focus a bit on the user interface. Playtime Here’s some stuff to try on your own: • If you are using Git, now might be a good time to commit our work. You can ﬁrst see what ﬁles we changed by using the git status command: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 116: ITERATION B2: UNIT TESTING depot> git status # On branch master # Changed but not updated: # (use "git add <file>..." to update what will be committed) # # modified: app/models/product.rb # modified: test/fixtures/products.yml # modified: test/functional/products_controller_test.rb # modified: test/unit/product_test.rb # no changes added to commit (use "git add" and/or "git commit -a") OF MODELS 116 Since we only modiﬁed some existing ﬁles, and didn’t add any new ones, we can combine the git add and git commit commands and simply issue a single git commit command with the -a option: depot> git commit -a -m 'Validation!' With this done, we can play with abandon, secure in the knowledge that we can return to this state at any time using a single git checkout . command. • The validation option :length checks the length of a model attribute. Add validation to the product model to check that the title is at least ten characters long. • Change the error message associated with one of your validations. (You’ll ﬁnd hints at http://www.pragprog.com/wikis/wiki/RailsPlayTime.) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 117: In this chapter, we’ll see • • • • • writing our own views, using layouts to decorate pages, integrating CSS, using helpers, and writing functional tests Chapter 8 Task C: Catalog Display All in all, it’s been a successful set of iterations. We gathered the initial requirements from our customer, documented a basic ﬂow, worked out a ﬁrst pass at the data we’ll need, and put together the maintenance page for the Depot application’s products. It hasn’t even taken many lines of code. We even have a small but growing test suite. Thus emboldened, it’s on to our next task. We chatted about priorities with our customer, and she said she’d like to start seeing what the application looks like from the buyer’s point of view. Our next task is to create a simple catalog display. This also makes a lot of sense from our point of view. Once we have the products safely tucked into the database, it should be fairly simple to display them. It also gives us a basis from which to develop the shopping cart portion of the code later. We should also be able to draw on the work we just did in the product maintenance task—the catalog display is really just a gloriﬁed product listing. Finally, we will also need to complement our unit tests for the model with some functional tests for the controller. 8.1 Iteration C1: Creating the Catalog Listing We’ve already created the products controller, used by the seller to administer the Depot application. Now it’s time to create a second controller, one that interacts with the paying customers. Let’s call it Store. depot> rails generate controller store index create app/controllers/store_controller.rb route get "store/index" invoke erb create app/views/store create app/views/store/index.html.erb Prepared exclusively for Jared Rosoff Slide 118: ITERATION C1: CREATING THE CATALOG LISTING 118 invoke create invoke create invoke create test_unit test/functional/store_controller_test.rb helper app/helpers/store_helper.rb test_unit test/unit/helpers/store_helper_test.rb Just as in the previous chapter, where we used the generate utility to create a controller and associated scaffolding to administer the products, here we’ve asked it to create a controller (class StoreController in the ﬁle store_controller.rb) containing a single action method, index. While everything is already set up for this action to be accessed via http:// localhost:3000/store/index (feel free to try it!), we can do better. Let’s simplify things for the user and make this the root URL for the web site. We do this by editing conﬁg/routes.rb: Download depot_d/conﬁg/routes.rb Depot::Application.routes.draw do get "store/index" resources :products # ... # You can have the root of your site routed with "root" # just remember to delete public/index.html. # root :to => "welcome#index" root :to => 'store#index' , :as => 'store' # ... end At the top of the ﬁle, you can see the lines added to support the Store and Products controller. We’ll leave those lines alone. Further along in the ﬁle you will see a commented out line that deﬁnes a root for the website. Either uncomment out that line, or add a new line immediately after that one. All we are changing on that line is the name of the controller (from welcome to store), and adding :as => store. The latter tells rails to create a store_path variable, just like the say_goodbye_path that we saw on on page 52. Note that the comments also instruct you to delete public/index.html. Let’s do that now:1 depot> rm public/index.html Let’s try it. Point a browser at http://localhost:3000/ and up pops our web page: 1. Windows users will want to execute erase public\index.html Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 119: ITERATION C1: CREATING THE CATALOG LISTING 119 It might not make us rich, but at least we know everything is wired together correctly. The page even tells us where to ﬁnd the template ﬁle that draws this page. Let’s start by displaying a simple list of all the products in our database. We know that eventually we’ll have to be more sophisticated, breaking them into categories, but this will get us going. We need to get the list of products out of the database and make it available to the code in the view that will display the table. This means we have to change the index method in store_controller.rb. We want to program at a decent level of abstraction, so let’s just assume we can ask the model for a list of the products we can sell: Download depot_d/app/controllers/store_controller.rb class StoreController < ApplicationController def index @products = Product.all end end We ask our customer whether she had a preference regarding the order things should be listed, and we jointly decided to see what happened if we displayed the products in alphabetical order. We do this by adding a default_scope call to the Product model. Default scopes apply to all queries that start with this model. Download depot_d/app/models/product.rb class Product < ActiveRecord::Base default_scope :order => 'title' # validation stuff... end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 120: ITERATION C2: ADDING A PAGE LAYOUT 120 Now we need to write our view template. To do this, edit the ﬁle index.html.erb in app/views/store. (Remember that the path name to the view is built from the name of the controller (store) and the name of the action (index). The .html.erb part signiﬁes an ERb template that produces an HTML result.) Download depot_d/app/views/store/index.html.erb <% if notice %> <p id="notice"><%= notice %></p> <% end %> <h1>Your Pragmatic Catalog</h1> <% @products.each do \|product\| %> <div class="entry"> <%= image_tag(product.image_url) %> <h3><%= product.title %></h3> <%=sanitize product.description %> <div class="price_line"> <span class="price"><%= product.price %></span> </div> </div> <% end %> Note the use of the sanitize method for the description. This allows us to safely add HTML stylings to make the descriptions more interesting for our customers. (Note: this decision opens a potential security hole, but because product descriptions are created by people who work for our company, we think that the risk is minimal. See Section 21.1, Escaping Substituted Values, on page 365 for details. We’ve also used the image_tag helper method. This generates an HTML <img> tag using its argument as the image source. Hitting Refresh brings up the display shown on Figure 8.1, on the next page. It’s pretty ugly, because we haven’t yet included the CSS stylesheet. The customer happens to be walking by as we ponder this, and she points out that she’d also like to see a decent-looking title and sidebar on public-facing pages. At this point in the real world, we’d probably want to call in the design folks— we’ve all seen too many programmer-designed websites to feel comfortable inﬂicting another on the world. But Pragmatic Web Designer is off getting inspiration on a beach somewhere and won’t be back until later in the year, so let’s put a placeholder in for now. It’s time for another iteration. 8.2 Iteration C2: Adding a Page Layout The pages in a typical website often share a similar layout—the designer will have created a standard template that is used when placing content. Our job is to add this page decoration to each of the store pages. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 121: ITERATION C2: ADDING A PAGE LAYOUT 121 Figure 8.1: Our ﬁrst (ugly) catalog page By naming the layout application.html.erb, it will be the layout used for all views for all controllers that don’t otherwise provide a layout. By using only one layout, we can change the look and feel of the entire site by editing just one ﬁle. This makes us feel better about putting a placeholder page layout in for now; we can update it when the designer eventually returns from the islands. We place this ﬁle in the app/views/layouts directory: Download depot_e/app/views/layouts/application.html.erb Line 1 5 10 - <!DOCTYPE html> <html> <head> <title>Pragprog Books Online Store</title> <%= stylesheet_link_tag "scaffold" %> <%= stylesheet_link_tag "depot" , :media => "all" %> <%= javascript_include_tag :defaults %> <%= csrf_meta_tag %> </head> <body id="store"> <div id="banner"> <%= image_tag("logo.png" ) %> Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 122: ITERATION C2: ADDING <%= @page_title \|\| "Pragmatic Bookshelf" %> </div> <div id="columns"> <div id="side"> <a href="http://www....">Home</a><br /> <a href="http://www..../faq">Questions</a><br /> <a href="http://www..../news">News</a><br /> <a href="http://www..../contact">Contact</a><br /> </div> <div id="main"> <%= yield %> </div> </div> </body> </html> A PAGE LAYOUT 122 15 20 25 - Apart from the usual HTML gubbins, this layout has four Rails-speciﬁc items. Line 6 uses a Rails helper method to generate a <link> tag to our depot.css stylesheet. Line 8 sets up all the behind-the-scenes data needed to prevent Cross Site Request Forgery attacks, which will be important once we start adding forms in Chapter 12, Task G: Check Out!, on page 173. On line 13, we set the page heading to the value in the instance variable @page_title. The real magic, however, takes place on line 23. When we invoke yield, Rails automatically substitutes in the page-speciﬁc content—the stuff generated by the view invoked by this request. In our case, this will be the catalog page generated by index.html.erb. yield ֒ page 69 → To make this all work, we need to add the following to our depot.css stylesheet: Download depot_e/public/stylesheets/depot.css /* Styles for main page / #banner { background: #9c9; padding-top: 10px; padding-bottom: 10px; border-bottom: 2px solid; font: small-caps 40px/40px "Times New Roman", serif; color: #282; text-align: center; } #banner img { float: left; } #columns { background: #141; } #main { Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 123: ITERATION C2: ADDING A PAGE LAYOUT 123 Figure 8.2: Catalog with layout added margin-left: 13em; padding-top: 4ex; padding-left: 2em; background: white; } #side { float: left; padding-top: 1em; padding-left: 1em; padding-bottom: 1em; width: 12em; background: #141; } #side a { color: #bfb; font-size: small; } Hit Refresh, and the browser window looks something like Figure 8.2. It won’t win any design awards, but it’ll show our customer roughly what the ﬁnal page will look like. Looking at this page, we spot a minor problem with how prices are displayed. The database stores the price as a number, but we’d like to show it as dollars Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 124: ITERATION C3: USING A HELPER TO FORMAT THE PRICE 124 and cents. A price of 12.34 should be shown as $12.34, and 13 should display as $13.00. We’ll tackle that next. 8.3 Iteration C3: Using a Helper to Format the Price Ruby provides a sprintf function which can be used to format prices. One could place logic which makes use of this function directly in the view. For example, we could say this: <span class="price" ><%= sprintf("$%0.02f" , product.price) %></span> This would work, but it embeds knowledge of currency formatting into the view. Should we want to internationalize the application later, this would be a maintenance problem. Instead, let’s use a helper method to format the price as a currency. Rails has an appropriate one built in—it’s called number_to_currency. Using our helper in the view is simple: in the index template, we change this: <span class="price" ><%= product.price %></span> to the following: <span class="price" ><%= number_to_currency(product.price) %></span> Sure enough, when we hit Refresh, we see a nicely formatted price: While it looks nice enough, we are starting to get a nagging feeling that we really should be running and writing tests for all this new functionality. Particularly after our experience after adding logic to our model. 8.4 Iteration C4: Functional Testing of Controllers Now for the moment of truth. Before we focus on writing new tests, we need to determine whether or not we have actually broken anything. Remembering our Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 125: ITERATION C4: FUNCTIONAL TESTING OF CONTROLLERS 125 experience after we added validation logic to our model, with some trepidation we run our tests again: depot> rake test This time, all is well. We added a lot, but we didn’t break anything. That’s a relief, but our work is not yet done... we still need tests for what we just added. The unit testing of models that we did previously seemed straightforward enough – we called a method and compared what it returned against what we expected it to return. But now we are dealing with a server which processes requests and a user viewing responses in a browser. What we will need is functional tests that verify that the model, view, and controller work well together. Never fear, Rails makes this easy too. First, let’s take a look at what Rails generated for us. Download depot_d/test/functional/store_controller_test.rb require 'test_helper' class StoreControllerTest < ActionController::TestCase test "should get index" do get :index assert_response :success end end The should get index test gets the index and asserts that a successful response is expected. That certainly seems straightforward enough. That’s a reasonable beginning, but we also want to verify that the response contains our layout, our product information, and number formatting. Let’s see what that looks like in code: Download depot_e/test/functional/store_controller_test.rb require 'test_helper' class StoreControllerTest < ActionController::TestCase test "should get index" do get :index assert_response :success assert_select '#columns #side a' , :minimum => 4 assert_select '#main .entry' , 3 assert_select 'h3' , 'Programming Ruby 1.9' assert_select '.price' , /\$[,\d]+\.\d\d/ end end The four lines we added take a look into the HTML that is returned, using CSS selector notation. As a refresher, selectors that start with a pound sign Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 126: ITERATION C4: FUNCTIONAL TESTING OF CONTROLLERS 126 (#) match on id attributes, selectors that start with a dot (.) match on class attributes, and selectors that contain no preﬁx at all match on element names. So the ﬁrst select test looks for an element named a that is contained in an element with an id with a value of side which is contained within an element with an id with a value of columns. This test veriﬁes that there are a minimum of four such elements. Pretty powerful stuff, assert_select, eh? The next three lines verify that all of our products are displayed. The ﬁrst veriﬁes that there are three elements with a class name of entry inside the main portion of the page. The next line veriﬁes that there is a h3 element with the title of the Rails book that we had entered previously. These assertions are based on the test data that we had put inside our ﬁxtures: Download depot_e/test/ﬁxtures/products.yml # Read about fixtures at http://ar.rubyonrails.org/classes/Fixtures.html one: title: MyString description: MyText image_url: MyString price: 9.99 two: title: MyString description: MyText image_url: MyString price: 9.99 ruby: title: Programming Ruby 1.9 description: Ruby is the fastest growing and most exciting dynamic language out there. If you need to get working programs delivered fast, you should add Ruby to your toolbox. price: 49.50 image_url: ruby.png If you noticed, the type of test that assert_select performs varies based on the type of the second parameter. If it is a number, it will be treated as a quantity. If it is a string, it will be treated as an expected result. Another useful type of test is a regular expression, which is what we use in our ﬁnal assertion. We verify that there is a price which has a value which contains a dollar sign followed by any number (but at least one) commas or digits, followed by a decimal point, followed by two digits. One ﬁnal point before we move on: both validation and functional tests will only test the behavior of controllers, they will not retroactively affect any data that already exists in the database or in ﬁxtures. In the example above, two regular expression ֒ page 68 → Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 127: ITERATION C4: FUNCTIONAL TESTING OF CONTROLLERS 127 products contain the same title. Such data will cause no problems and will go undetected up to the point where such records are modiﬁed and saved. We’ve only touched on a few things that assert_select can do. More information can be found in the online documentation.2 That’s a lot of veriﬁcation in just a few lines of code. We can see that it works by rerunning just the functional tests (after all, that’s all we changed): depot> rake test:functionals Now we not only have something recognizable as a store front, we have tests that ensure that all of the pieces – the model, view, and controller – are all working together to produce the desired result. While this sounds like a lot: with Rails it was easy, in fact it was mostly HTML and CSS, and not much in the way of code or tests. What We Just Did We’ve put together the basis of the store’s catalog display. The steps were as follows: 1. Create a new controller to handle customer-centric interactions. 2. Implement the default index action. 3. Add a default_scope to the Product model to specify the order to list the items on the website. 4. Implement a view (an .html.erb ﬁle) and a layout to contain it (another .html.erb ﬁle). 5. Use a helper to format prices the way we want. 6. Make use of a CSS stylesheet. 7. Write functional tests for our controller. It’s time to check it all in and move on to the next task, namely, making a shopping cart! Playtime Here’s some stuff to try on your own: • Add a date and time to the sidebar. It doesn’t have to update; just show the value at the time the page was displayed. • Experiment with setting various number_to_currency helper method options, and see the effect on your catalog listing. 2. http://api.rubyonrails.org/classes/ActionController/Assertions/SelectorAssertions.html Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 128: ITERATION C4: FUNCTIONAL TESTING OF CONTROLLERS 128 • Write some functional tests for the product maintenance application using assert_select. The tests will need to be placed into the test/functional/products_controller_test.rb ﬁle. • Just a reminder, the end of an iteration is a good time to save your work using git. If you have been following along, you’ve got the basics you need at this point. We will pick things back up, in terms of exploring more git functionality, in Section 16.2, Prepping Your Deployment Server, on page 261. (You’ll ﬁnd hints at http://www.pragprog.com/wikis/wiki/RailsPlayTime .) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 129: In this chapter, we’ll see • sessions and session management, • adding relationships between models, and • adding a button to add a product to a cart. Chapter 9 Task D: Cart Creation Now that we have the ability to display a catalog containing all our wonderful products, it would be nice to be able to sell them. Our customer agrees, so we’ve jointly decided to implement the shopping cart functionality next. This is going to involve a number of new concepts, including sessions, relationships between models, and adding a button to the view, so let’s get started. 9.1 Iteration D1: Finding a Cart As users browse our online catalog, they will (we hope) select products to buy. The convention is that each item selected will be added to a virtual shopping cart, held in our store. At some point, our buyers will have everything they need and will proceed to our site’s checkout, where they’ll pay for the stuff in the carts. This means that our application will need to keep track of all the items added to the cart by the buyer. To do that we’ll keep a cart in the database and store its unique identiﬁer, cart.id, in the session. Every time a request comes in, we can recover the identity from the session and use it to ﬁnd the cart in the database. So lets go ahead and create a Cart. depot> rails generate scaffold cart ... depot> rake db:migrate == CreateCarts: migrating ==================================================== -- create_table(:carts) -> 0.0012s == CreateCarts: migrated (0.0014s) =========================================== Rails makes the current session look like a hash to the controller, so we’ll store the cart in the session by indexing it with the symbol :cart_id. Download depot_f/app/controllers/application_controller.rb class ApplicationController < ActionController::Base Prepared exclusively for Jared Rosoff Slide 130: ITERATION D2: CONNECTING PRODUCTS TO CAR TS 130 protect_from_forgery private def current_cart Cart.find(session[:cart_id]) rescue ActiveRecord::RecordNotFound cart = Cart.create session[:cart_id] = cart.id cart end end The current_cart starts by getting the :cart_id from the session object, and attempts to ﬁnd a cart corresponding to this id. If such a Cart record is not found (which will happen if the id is nil or invalid for any reason), then this method will proceed to create a new Cart, store the id of the created cart into the session, and then return the new cart. Note that we make the current_cart method private. This makes this method only available to other controllers, and in particular it prevents Rails from ever making it available as an action on the controller. private ֒ page 72 → 9.2 Iteration D2: Connecting Products to Carts We’re looking at sessions because we need somewhere to keep our shopping cart. We’ll cover sessions in more depth in Section 20.3, Rails Sessions, on page 351, but for now let’s move on to implement the cart. Let’s keep things simple. A cart contains a set of products. Based on the diagram on page 85, combined with a brief chat with our customer, we can now generate the Rails models and populate the migrations to create the corresponding tables: depot> rails generate scaffold line_item product_id:integer cart_id:integer ... depot> rake db:migrate == CreateLineItems: migrating ================================================ -- create_table(:line_items) -> 0.0013s == CreateLineItems: migrated (0.0014s) ======================================= The database now has a place to store the relationships between line items, carts, and products. However, the Rails application does not. We need to add some declarations to our model ﬁles that specify their interrelationships. Open the newly created cart.rb ﬁle in app/models, and add a call to has_many: class Cart < ActiveRecord::Base has_many :line_items, :dependent => :destroy end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 131: ITERATION D2: CONNECTING PRODUCTS TO CAR TS 131 That has_many :line_items part of the directive is fairly self-explanatory: a cart (potentially) has many associated line items. These are linked to the cart because each line item contains a reference to its cart’s id. The :dependent => :destroy part indicates that the existence of line items is dependent on the existence of the cart. If we destroy a cart, deleting it from the database, we’ll want Rails also to destroy any line items that are associated with that cart. Next, we’ll specify links in the opposite direction, from the line item to the carts and products tables. To do this, we use the belongs_to declaration twice in the line_item.rb ﬁle: Download depot_f/app/models/line_item.rb class LineItem < ActiveRecord::Base belongs_to :product belongs_to :cart end belongs_to tells Rails that rows in the line_items table are children of rows in the carts and products tables. No line item can exist unless the corresponding cart and product rows exist. There’s an easy way to remember where to put belongs_to declarations: if a table has foreign keys, the corresponding model should have a belongs_to for each. Just what do these various declarations do? Basically, they add navigation capabilities to the model objects. Because we added the belongs_to declaration to LineItem, we can now retrieve its Product and display the book’s title: li = LineItem.find(...) puts "This line item is for #{li.product.title}" And because Cart is declared to have many line items, we can reference them (as a collection) from a cart object: cart = Cart.find(...) puts "This cart has #{cart.line_items.count} line items" Now, for completeness, we should add a has_many directive to our product model. After all, if we have lots of carts, each product might have many line items referencing it. This time, we will make use of validation code to prevent removal of products that are referenced by line items. Download depot_f/app/models/product.rb class Product < ActiveRecord::Base default_scope :order => 'title' has_many :line_items before_destroy :ensure_not_referenced_by_any_line_item # ensure that there are no line items referencing this product def ensure_not_referenced_by_any_line_item Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 132: ITERATION D3: ADDING if line_items.count.zero? return true else errors[:base] << "Line Items present" return false end end #... A BUTTON 132 Here we declare that a product has many line items, and deﬁne a hook method named ensure_not_referenced_by_any_line_item. A hook method is a method that Rails calls automatically at a given point in an object’s life. In this case, the method will be called before Rails attempts to destroy a row in the database. If the hook method returns false, the row will not be destroyed. We’ll have more to say about intermodel relationships starting on page 299. 9.3 Iteration D3: Adding a Button Now that that’s done, it is time to add an Add to Cart button for each product. There is no need to create a new controller or even a new action. Taking a look at the actions provided by the scaffold generator, you ﬁnd index, show, new, edit, create, update and destroy. The one that matches this operation is create. (new may sound similar, but its use is to get a form that is used to solicit input for a subsequent create action.) Once this decision is made, the rest follows. What are we creating? Certainly not a Cart or even a Product. What we are creating is a LineItem. Looking at the comment associated with the create method in app/controllers/line_items_controller.rb, you see that this choice also determines the URL to use (/line_items) and the HTTP method (POST). This choice even suggests the proper UI control to use. When we added links before, we used link_to, but links default to using HTTP GET. We want to use POST, so we will add a button this time, this means that we will be using the button_to method. We could connect the button to the line item by specifying the URL, but again we can let Rails take care of this for us by simply appending _path to the controller’s name. In this case, we will use line_items_path. However, there’s a problem with this: how will the line_items_path method know which product to add to our cart? We’ll need to pass it the id of the product corresponding to the button. That’s easy enough—all we need to do is add the :product_id option to the line_items_path call. We can even pass in the product Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 133: ITERATION D3: ADDING A BUTTON 133 instance itself—Rails knows to extract the id from the record in circumstances such as these. In all, the one line that we need to add to our index.html.erb looks like this: Download depot_f/app/views/store/index.html.erb <% if notice %> <p id="notice"><%= notice %></p> <% end %> <h1>Your Pragmatic Catalog</h1> <% @products.each do \|product\| %> <div class="entry"> <%= image_tag(product.image_url) %> <h3><%= product.title %></h3> <%=sanitize product.description %> <div class="price_line"> <span class="price"><%= number_to_currency(product.price) %></span> <%= button_to 'Add to Cart', line_items_path(:product_id => product) %> </div> </div> <% end %> There’s one more formatting issue. button_to creates an HTML <form>, and that form contains an HTML <div>. Both of these are normally block elements, which will appear on the next line. We’d like to place them next to the price, so we need a little CSS magic to make them inline: Download depot_f/public/stylesheets/depot.css #store .entry form, #store .entry form div { display: inline; } Now our index page looks like Figure 9.1, on the following page. But before we push the button, we need to modify the create method in the line items controller to expect a product id as a form parameter. Here’s where we start to see how important the id ﬁeld is in our models. Rails identiﬁes model objects (and the corresponding database rows) by their id ﬁelds. If we pass an id to create, we’re uniquely identifying the product to add. Why the create method? The default HTTP method for a link is a get, and the default HTTP method for a button is a post, and rails uses these conventions to determine which method to call. See the comments inside the app/controller/line_items_controller ﬁle to see other conventions. We’ll be making extensive use of these conventions inside the Depot application. Now let’s modify the LineItemsController to ﬁnd the shopping cart for the current session (creating one if there isn’t one there already), add the selected product Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 134: ITERATION D3: ADDING A BUTTON 134 Figure 9.1: Now there’s an Add to Cart button. to that cart, and display the cart contents. All we need to modify is a few lines of code in the create method in app/controllers/line_items_controller.rb1 : Download depot_f/app/controllers/line_items_controller.rb def create @cart = current_cart product = Product.find(params[:product_id]) @line_item = @cart.line_items.build(:product => product) respond_to do \|format\| if @line_item.save format.html { redirect_to(@line_item.cart, :notice => 'Line item was successfully created.' ) } format.xml { render :xml => @line_item, :status => :created, :location => @line_item } else format.html { render :action => "new" } format.xml { render :xml => @line_item.errors, :status => :unprocessable_entity } end end end We use the current_cart method we implemented on page 129 to ﬁnd (or create) a cart in the session. Next, we use the params object to get the :product_id parameter from the request. The params object is important inside Rails appli1. Some lines have been wrapped to ﬁt on the page Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 135: ITERATION D3: ADDING A BUTTON 135 cations. It holds all of the parameters passed in a browser request. We store the result in a local variable as there is no need to make this available to the view. We then pass that product we found in to @cart.line_items.build, which builds a new Line Item associated with both this @cart and the product speciﬁed. We save the result into a instance variable named @line_item. The remainder of this method takes care of xml requests, which we will cover on page 363, and handling errors which we will cover in more detail on page 144. But for now, we only want to modify one more thing: once the Line Item is created we want to redirect you to the cart instead of back to the line item itself. Since the line item object knows how to ﬁnd the cart object, all we need to do is add .cart to the method call. As we changed the function of our controller, we know that we will need to update the corresponding functional test. We need to pass a product id on the call to create, and change what we expect for the target of the redirect. We do this by updating test/functional/line_items_controller_test.rb. Download depot_g/test/functional/line_items_controller_test.rb test "should create line_item" do assert_difference('LineItem.count' ) do post :create, :product_id => products(:ruby).id end assert_redirected_to cart_path(assigns(:line_item).cart) end We rerun the functional tests. depot> rake test:functionals Conﬁdent that the code works as intended, we try the Add to Cart buttons in our browser. And here is what we see: This is a bit underwhelming. While we have scaffolding for the Cart, when we created it we didn’t provide any attributes, so the view doesn’t have anything to show. For now, lets write a trivial template (we’ll tart it up in a minute): Download depot_f/app/views/carts/show.html.erb <h2>Your Pragmatic Cart</h2> <ul> <% for item in @cart.line_items %> Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 136: ITERATION D3: ADDING <li><%= item.product.title %></li> <% end %> </ul> A BUTTON 136 So, with everything plumbed together, let’s hit Refresh in our browser, and see our simple view displayed: Go back to http://localhost:3000/, the main catalog page, and add a different product to the cart. You’ll see the original two entries plus our new item in your cart. It looks like we’ve got sessions working. It’s time to show our customer, so we call her over and proudly display our handsome new cart. Somewhat to our dismay, she makes that tsk-tsk sound that customers make just before telling you that you clearly don’t get something. Real shopping carts, she explains, don’t show separate lines for two of the same product. Instead, they show the product line once with a quantity of 2. Looks like we’re lined up for our next iteration. What We Just Did It has been a busy, productive day so far. We’ve added a shopping cart to our store, and along the way we’ve dipped our toes into some neat Rails features: • We created a Cart object in one request and were able to successfully locate the same Cart in subsequent requests using a session object, • we added a private method in the base class for all of our controllers, making it accessible to all of our controllers, • we created relationships between Carts and Line Items, relationships between Line Items and Products, and were able to navigate using these relationships, and • we added a button which caused a product to be POSTed to a cart, causing a new LineItem to be created. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 137: ITERATION D3: ADDING A BUTTON 137 Playtime Here’s some stuff to try on your own: • Change the application so that clicking a book’s image will also invoke the create action. Hint: the ﬁrst parameter to link_to is placed in the generated <a> tag, and the Rails helper image_tag constructs an HTML <img> tag. Include a call to it as the ﬁrst parameter to a link_to call. Be sure to include :method => :post in your html_options on your call to link_to. • Add a new variable to the session to record how many times the user has accessed the store controller’s index action. The ﬁrst time through, your count won’t be in the session. You can test for this with code like this: if session[:counter].nil? ... If the session variable isn’t there, you’ll need to initialize it. Then you’ll be able to increment it. • Pass this counter to your template, and display it at the top of the catalog page. Hint: the pluralize helper (described on page 374) might be useful when forming the message you display. • Reset the counter to zero whenever the user adds something to the cart. • Change the template to display the counter only if it is greater than ﬁve. (You’ll ﬁnd hints at http://pragprog.com/wikis/wiki/RailsPlayTime.) Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 138: ITERATION D3: ADDING A BUTTON 138 Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 139: In this chapter, we’ll see • • • • modifying the schema and existing data, error diagnosis and handling, the ﬂash, and logging. Chapter 10 Task E: A Smarter Cart While we have rudimentary cart functionality implemented, we have much to do. To start with, we will need to recognize when customers add multiples of the same item to the cart. Once that’s done we will also have to make sure that the cart itself can handle error cases and communicate problems encountered along the way to the customer or the system administrator, as appropriate. 10.1 Iteration E1: Creating a Smarter Cart Associating a count with each product in our cart is going to require us to modify the line_items table. We’ve used migration before in Section 6.1, Applying the Migration, on page 91 to update the schema of the database. While that was as a part of creating the initial scaffolding for a model, the basic approach is the same. depot> rails generate migration add_quantity_to_line_item quantity:integer Rails can tell from the name of the migration that you are adding one or more columns to the line_item table, and can pick up the names and data types for each column from the last argument. The two patterns that Rails matches on is add_XXX_to_TABLE and remove_XXX_from_TABLE where the value of XXX is ignored: what matters is the list of column names and types that appear after the migration name. The only thing Rails can’t tell is what a reasonable default is for this column. In many cases a null value would do, but let’s make it the value one for existing carts by modifying the migration before we apply it: Download depot_g/db/migrate/20100301000004_add_quantity_to_line_item.rb class AddQuantityToLineItem < ActiveRecord::Migration def self.up add_column :line_items, :quantity, :integer, :default => 1 end def self.down Prepared exclusively for Jared Rosoff Slide 140: ITERATION E1: CREATING A SMAR TER CAR T 140 remove_column :line_items, :quantity end end Once complete, we run the migration. depot> rake db:migrate Now we need a smart add_product method in our Cart, one that checks whether our list of items already includes the product we’re adding; if it does, it bumps the quantity, and if it doesn’t, it adds a new LineItem: Download depot_g/app/models/cart.rb def add_product(product_id) current_item = line_items.where(:product_id => product_id).first if current_item current_item.quantity += 1 else current_item = LineItem.new(:product_id=>product_id) line_items << current_item end current_item end We also need to modify the line item controller to make use of this method: Download depot_g/app/controllers/line_items_controller.rb def create @cart = current_cart product = Product.find(params[:product_id]) @line_item = @cart.add_product(product.id) respond_to do \|format\| if @line_item.save format.html { redirect_to(@line_item.cart, :notice => 'Line item was successfully created.' ) } format.xml { render :xml => @line_item, :status => :created, :location => @line_item } else format.html { render :action => "new" } format.xml { render :xml => @line_item.errors, :status => :unprocessable_entity } end end end One last quick change to the show view to use this new information: Download depot_g/app/views/carts/show.html.erb <h2>Your Pragmatic Cart</h2> <ul> <% for item in @cart.line_items %> <li><%= item.quantity %> × <%= item.product.title %></li> <% end %> Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 141: ITERATION E1: CREATING </ul> A SMAR TER CAR T 141 Now that all the pieces are in place, we can go back to the store page and hit the Add to Cart button for a product that is already in the cart. What we are likely to see is a mixture of individual products listed separately, and a single product listed with a quantity of two. This is because we added a quantity of one to existing columns instead of collapsing multiple rows when possible. What we need to do next is migrate the data. We start by creating a migration. depot> rails generate migration combine_items_in_cart This time, Rails can’t infer what we are trying to do, so it is entirely up to us to ﬁll in the self.up method: Download depot_g/db/migrate/20100301000005_combine_items_in_cart.rb def self.up # replace multiple items for a single product in a cart with a single item Cart.all.each do \|cart\| # count the number of each product in the cart sums = cart.line_items.group(:product_id).sum(:quantity) sums.each do \|product_id, quantity\| if quantity > 1 # remove individual items cart.line_items.where(:product_id=>product_id).delete_all # replace with a single item cart.line_items.create(:product_id=>product_id, :quantity=>quantity) end end end end This is easily the most extensive code we’ve seen so far. Let’s look at it small pieces. • We start by iterating over each cart. • For each cart, we get a sum of the quantity ﬁelds for each of the line items associated with this cart, grouped by product_id. The resulting sums will be a list of ordered pairs of product_ids and quantity. • We iterate over these sums, extracting the product_id and quantity from each. • In cases where the quantity is greater than one, we will delete all of the individual line items associated with this cart and this product, and replace them with a single line item with the correct quantity. Note how easily and elegantly Rails enables you to express this algorithm. iterating ֒ page 69 → Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 142: ITERATION E1: CREATING A SMAR TER CAR T 142 Figure 10.1: A cart with quantities With this code in place, we apply this migration just like any other migration. depot> rake db:migrate We can immediately see the results by looking at the cart, as shown in Figure 10.1. While we have reason to be pleased with ourselves, we are not done yet. An important principle of migrations is that each step needs to be reversible, so we implement a self.down too. This method ﬁnds line items with a quantity of greater than one, adds new line items for this cart and product, each with a quantity of one, and ﬁnally deletes the line item. The following code accomplishes that: Download depot_g/db/migrate/20100301000005_combine_items_in_cart.rb def self.down # split items with quantity>1 into multiple items LineItem.where("quantity>1" ).each do \|lineitem\| # add individual items lineitem.quantity.times do LineItem.create :cart_id=>lineitem.cart_id, :product_id=>lineitem.product_id, :quantity=>1 end # remove original item lineitem.destroy end end At this point, we can just as easily roll back our migration with a single command. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 143: ITERATION E1: CREATING A SMAR TER CAR T 143 Figure 10.2: A cart after the migration has been rolled back depot> rake db:rollback Once again, we can immediately inspect the results by looking at the cart, as shown in Figure 10.2. Once we reapply the migration (with the rake db:migrate command), we have a cart that maintains a count for each of the products that it holds, and we have a view that displays that count. Happy that we have something presentable, we call our customer over and show her the result of our morning’s work. She’s pleased—she can see the site starting to come together. However, she’s also troubled, having just read an article in the trade press on the way e-commerce sites are being attacked and compromised daily. She read that one kind of attack involves feeding requests with bad parameters into web applications, hoping to expose bugs and security ﬂaws. She noticed that the link to cart looks like carts/nnn, where nnn is our internal cart id. Feeling malicious, she manually types this request into a browser, giving it a cart id of wibble. She’s not impressed when our application displays the page in Figure 10.3, on the following page. This reveals way too much information about our application. It also seems fairly unprofessional. So, our next iteration will be spent making the application more resilient. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 144: ITERATION E2: HANDLING ERRORS 144 Figure 10.3: Our application spills its guts. 10.2 Iteration E2: Handling Errors Looking at the page displayed in Figure 10.3, it’s apparent that our application raised an exception at line 16 of the carts controller.1 That turns out to be this line: @cart = Cart.find(params[:id]) If the cart cannot be found, Active Record raises a RecordNotFound exception,2 which we clearly need to handle. The question arises—how? We could just silently ignore it. From a security standpoint, this is probably the best move, because it gives no information to a potential attacker. However, it also means that should we ever have a bug in our code that generates bad cart ids, our application will appear to the outside world to be unresponsive—no one will know there has been an error. Instead, we’ll take two actions when an exception is raised. First, we’ll log the fact to an internal log ﬁle using Rails’ logger facility (described on page 439). And second, we’ll redisplay the catalog page, along with a short message to the user (something along the lines of “Invalid cart”), so they can continue to use our site. 1. Your line number might be different. We have some book-related formatting stuff in our source ﬁles. 2. This is the error raised when running with SQLite 3. Other databases might cause a different error to be raised. If you use PostgreSQL, for example, it will refuse to accept wibble as a valid value for the primary key column and raise a StatementInvalid exception instead. You’ll need to adjust your error handling accordingly. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 145: ITERATION E2: HANDLING ERRORS 145 Rails has a convenient way of dealing with errors and error reporting. It deﬁnes a structure called a ﬂash. A ﬂash is a bucket (actually closer to a Hash) in which you can store stuff as you process a request. The contents of the ﬂash are available to the next request in this session before being deleted automatically. Typically the ﬂash is used to collect error messages. For example, when our show method detects that it was passed an invalid cart id, it can store that error message in the ﬂash area and redirect to the index action to redisplay the catalog. The view for the index action can extract the error and display it at the top of the catalog page. The ﬂash information is accessible within the views by using the ﬂash accessor method. Why couldn’t we just store the error in any old instance variable? Remember that after a redirect is sent by our application to the browser, the browser sends a new request back to our application. By the time we receive that request, our application has moved on—all the instance variables from previous requests are long gone. The ﬂash data is stored in the session in order to make it available between requests. Armed with all this background about ﬂash data, we can now change our show method to intercept bad product ids and report on the problem: Download depot_h/app/controllers/carts_controller.rb # GET /carts/1 # GET /carts/1.xml def show begin @cart = Cart.find(params[:id]) rescue ActiveRecord::RecordNotFound logger.error "Attempt to access invalid cart #{params[:id]}" redirect_to store_url, :notice => 'Invalid cart' else respond_to do \|format\| format.html # show.html.erb format.xml { render :xml => @cart } end end end The rescue clause intercepts the exception raised by Cart.ﬁnd. In the handler, we do the following: • Use the Rails logger to record the error. Every controller has a logger attribute. Here we use it to record a message at the error logging level. • Redirect to the catalog display using the redirect_to method. The :notice parameter speciﬁes a message to be stored in the ﬂash as a notice. Why redirect, rather than just display the catalog here? If we redirect, the user’s browser will end up displaying the store URL, rather than Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 146: ITERATION E3: FINISHING THE CAR T 146 http://.../cart/wibble. We expose less of the application this way. We also prevent the user from retriggering the error by hitting the Reload button. With this code in place, we can rerun our customer’s problematic query. This time, when we enter the following URL: http://localhost:3000/carts/wibble we don’t see a bunch of errors in the browser. Instead, the catalog page is displayed. If we look at the end of the log ﬁle (development.log in the log directory), we’ll see our message: Processing CartsController#show to /* sql (0.0ms) SELECT * FROM "products" WHERE (("products"."id" = 2)) Completed in 38ms (View: 28, DB: 0) \| 200 [unknown] Parameters: {"id"=>"1"} sql (0.0ms) SELECT * FROM "carts" WHERE (("carts"."id" = 0)) ActiveRecord::RecordNotFound (Couldn't find Cart with ID=wibble): app/controllers/carts_controller.rb:22:in `show' : : Attempt to access invalid cart wibble sql (0.0ms) SELECT * FROM "carts" WHERE (("carts"."id" = 0)) Redirected to http://127.0.0.1:3000/store : : Rendering app/views/store/index.html.erb Rendering template within app/views/layouts/application.html.erb See Figure 10.4, on the following page for a much more user friendly result. On Unix machines, we’d probably use a command such as tail or less to view this ﬁle. On Windows, you could use your favorite editor. It’s often a good idea to keep a window open showing new lines as they are added to this ﬁle. In Unix you’d use tail -f. You can download a tail command for Windows from http:// gnuwin32.sourceforge.net/packages/coreutils.htm or get a GUI-based tool from http:// tailforwin32.sourceforge.net/. Finally, some OS X users use Console.app to track log ﬁles. Just say open name.log at the command line. Sensing the end of an iteration, we call our customer over and show her that the error is now properly handled. She’s delighted and continues to play with the application. She notices a minor problem on our new cart display—there’s no way to empty items out of a cart. This minor change will be our next iteration. We should make it before heading home. 10.3 Iteration E3: Finishing the Cart We know by now that in order to implement the “empty cart” function, we have to add a link to the cart and modify the destroy method in the carts controller to cleanup the session. Let’s start with the template and again use the button_to method to put a button on the page: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 147: ITERATION E3: FINISHING THE CAR T 147 Figure 10.4: Much more user-oriented error message Download depot_h/app/views/carts/show.html.erb <h2>Your Pragmatic Cart</h2> <ul> <% for item in @cart.line_items %> <li><%= item.quantity %> × <%= item.product.title %></li> <% end %> </ul> <%= button_to 'Empty cart', @cart, :method => :delete, :confirm => 'Are you sure?' %> In the controller, we’ll modify the destroy method to remove the cart from the session before redirecting to the index page with a notiﬁcation message: Download depot_h/app/controllers/carts_controller.rb def destroy @cart = Cart.find(params[:id]) @cart.destroy session[:cart_id] = nil respond_to do \|format\| format.html { redirect_to(store_url, :notice => 'Your cart is currently empty' ) } format.xml { head :ok } end end And we update the corresponding test in test/functional/carts_controller_test.rb. Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 148: ITERATION E3: FINISHING THE CAR T 148 David Says. . . Battle of the routes: product_path vs product_url It can seem hard in the beginning to know when to use product_path and when to use product_url when you want to link or redirect to a given route. In reality, it’s really quite simple, though. When you use product_url, you’ll get the full enchilada with protocol and domain name, like http://example.com/products/1. That’s the thing to use when you’re doing redirect_to because the HTTP spec requires a fully qualiﬁed URL when doing 302 Redirect and friends. You also need the full URL if you’re redirecting from one domain to another, ala product_url(:domain => "example2.com", :product => product). The rest of the time, you can happily use product_path. This will only generate the /products/1 part and that’s all you need when doing links or pointing forms. Like link_to "My lovely product", product_path(product). Now the confusing part is that often times the two are interchangeable because of lenient browsers. You can do a redirect_to with a product_path and it’ll probably work, but it won’t be valid according to spec. And you can link_to a product_url, but then you’re littering up your HTML with needless characters and that’s a bad idea too. Download depot_i/test/functional/carts_controller_test.rb test "should destroy cart" do assert_difference('Cart.count' , -1) do delete :destroy, :id => @cart.to_param end assert_redirected_to store_path end Now when we view our cart and click the Empty Cart button, we get taken back to the catalog page, and a nice little message says this: We can also remove the ﬂash message that is automatically generated when a Line Item is added. Download depot_i/app/controllers/line_items_controller.rb def create Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 149: ITERATION E3: FINISHING THE CAR T 149 @cart = current_cart product = Product.find(params[:product_id]) @line_item = @cart.add_product(product.id) respond_to do \|format\| if @line_item.save format.html { redirect_to(@line_item.cart) } format.xml { render :xml => @line_item, :status => :created, :location => @line_item } else format.html { render :action => "new" } format.xml { render :xml => @line_item.errors, :status => :unprocessable_entity } end end end And, ﬁnally, we’ll get around to tidying up the cart display. Rather than use <li> elements for each item, let’s use a table. Again, we’ll rely on CSS to do the styling: Download depot_i/app/views/carts/show.html.erb <div class="cart_title">Your Cart</div> <table> <% for item in @cart.line_items %> <tr> <td><%= item.quantity %>×</td> <td><%= item.product.title %></td> <td class="item_price"><%= number_to_currency(item.total_price) %></td> </tr> <% end %> <tr class="total_line"> <td colspan="2">Total</td> <td class="total_cell"><%= number_to_currency(@cart.total_price) %></td> </tr> </table> <%= button_to 'Empty cart', @cart, :method => :delete, :confirm => 'Are you sure?' %> To make this work, we need to add a method to both the LineItem and Cart models that returns the total price for the individual line item and entire cart, respectively. First the line item, which only involves simple multiplication: Download depot_i/app/models/line_item.rb def total_price product.price * quantity end Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010) Slide 150: ITERATION E3: FINISHING THE CAR T 150 Figure 10.5: Cart display with a total We implement the Cart method using Rails’ nifty sum method to sum the prices of each item in the collection: Download depot_i/app/models/cart.rb def total_price line_items.to_a.sum { \|item\| item.total_price } end Then we need to add a small bit to our depot.css stylesheet: Download depot_i/public/stylesheets/depot.css /* Styles for the cart in the main page */ #store .cart_title { font: 120% bold; } #store .item_price, #store .total_line { text-align: right; } #store .total_line .total_cell { font-weight: bold; border-top: 1px solid #595; } See Figure 10.5 for a nicer-looking cart. What We Just Did Our shopping cart is now something the client is happy with. Along the way, we covered: Report erratum Prepared exclusively for Jared Rosoff this copy is (B8.0 printing, September 9, 2010)