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 finished 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, spelling mistakes, and the occasional creative piece of grammar. And there’s been no effort spent doing layout, so you’ll find bad page breaks, over-long code lines, incorrect hyphen- ation, and all the other ugly things that you wouldn’t expect to see in a finished book. It also doesn't have an index. 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 get updated ebooks from your account at pragprog.com/my_account. When the book is com- plete, you’ll get the final version (and subsequent updates) from the same ad- dress. Send us your feedback: In the meantime, we’d appreciate you sending us your feedback on this book at pragprog.com/titles/jvrails2/errata, or by using the links at the bottom of each page. Thank you for being part of the Pragmatic community! Dave & Andy Crafting Rails 4 Applications Expert Practices for Everyday Rails Development Jose Valim The Pragmatic Bookshelf Dallas, Texas • Raleigh, North Carolina 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, PragProg and the linking g device are trade- marks 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://pragprog.com. Copyright © 2013 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-13: 978-1-937785-55-0 Encoded using the finest acid-free high-entropy binary digits. Book version: B2.0—June 21, 2013 Contents Changes . . . . . . . . . . . . . . v Preface . . . . . . . . . . . . . . vii 1. Creating Our Own Renderer . . . . . . . . . 1 1.1 Creating your first Rails Plugin 2 1.2 Writing the Renderer 5 1.3 Understanding The Rails Rendering Stack 9 1.4 Taking It to the Next Level 15 1.5 Wrapping Up 16 2. Building Models with Active Model . . . . . . . 17 2.1 Creating Our Model 17 2.2 Integration tests with Capybara 28 2.3 Taking It to the Next Level 32 2.4 Wrapping Up 37 3. Retrieving View Templates from Custom Stores . . . . 39 3.1 Revisiting the Rendering Stack 39 3.2 Setting Up a SqlResolver 41 3.3 Configuring Our Resolver for Production 48 3.4 Serving Templates with Metal 56 3.5 Wrapping Up 60 4. Sending Multipart Emails Using Template Handlers . . . 61 4.1 Playing with the Template Handler API 63 4.2 Building a Template Handler with Markdown + ERB 67 4.3 Customizing Rails Generators 71 4.4 Extending Rails with Railties 80 4.5 Wrapping Up 82 Contents • iv 5. Streaming Server Events to Clients Asynchronously . . . 85 5.1 Extending Rails with Engines 86 5.2 Live Streaming 89 5.3 File system notifications with Threads 95 5.4 Code loading techniques 103 5.5 Wrapping up 107 6. Writing DRY Controllers with Responders . . . . . 109 6.1 Understanding Responders 110 6.2 Exploring ActionController::Responder 114 6.3 The Flash Responder 119 6.4 HTTP Cache Responder 124 6.5 More Ways to Customize Generators 128 6.6 Wrapping Up 134 7. Managing Application Events with Mountable Engines . . 137 7.1 Mountable and Isolated Engines 137 7.2 Storing Notifications in the Database 139 7.3 Rails and Rack 146 7.4 Middleware Stacks 149 7.5 Streaming with Rack 157 7.6 Wrapping Up 161 8. Translating Applications Using Key-Value Backends . . 163 8.1 Revisiting Rails::Application 164 8.2 I18n Backends and Extensions 168 8.3 Rails and Sinatra 171 8.4 Taking It to the Next Level with Devise and Capybara 177 8.5 Wrapping Up 184 Changes Beta 2 - June 21st, 2013 You’ll find two new chapters: Chapter 5, Streaming Server Events to Clients Asynchronously, on page 85 and Chapter 8, Translating Applications Using Key-Value Backends, on page 163, making the book content-complete. In addition, all the code has been updated to support Rails 4.0 RC2. All outstanding errata has been addressed. Thanks to everyone who submitted items that needed fixing. Keep them coming! report erratum • discuss Preface When Rails was first released in 2004, it revolutionized how web development was done by embracing concepts like Don’t Repeat Yourself (DRY) and con- vention over configuration. As Rails gained momentum, the conventions that were making things work so well on the golden path started to get in the way of developers who had the urge to extend how Rails behaved or even replace whole components. Some developers felt that using DataMapper instead of Active Record was a better fit. Other developers turned to MongoDB and other nonrelational databases but still wanted to use their favorite web framework. Then there were those developers who preferred RSpec to Test::Unit. These developers hacked, cobbled, or monkey-patched solutions together to accomplish their goals because previous versions of Rails did not provide a solid API or the modularity required to make these changes in a clean, maintainable fashion. With time, Rails started to listen to those developers and after years, the end result is a robust and wide set of plugin APIs, targetted to developers that want to customize their wokflows, replace whole components, bending Rails to their needs without messy hacks. This book guides you through these plugin APIs through practical examples. In each chapter, we will use test-driven development to build a Rails plugin or application that covers those APIs and how they fit in the Rails architecture. By the time you finish this book, you will understand Rails better and be more productive while writing more modular and faster Rails applications. Who Should Read This Book? If you’re an intermediate or advanced Rails developer looking to dig deeper and make the Rails framework work for you, this is for you. We’ll go beyond the basics of Rails; instead of showing how Rails lets you use its built-in features to render HTML or XML from a controller, we’ll show you how the report erratum • discuss Preface • viii render() method works so you can customize it to accept custom options, such as :pdf. Rails Versions All projects in Crafting Rails Applications were developed and tested against Rails 4.0.0. Future stable releases, like Rails 4.0.1, 4.0.2, and so forth, should be suitable as well. You can check your Rails version with the following command: rails -v And you can use geminstall to get the most appropriate version: gem install rails -v 4.0.0 This book also has excerpts from Rails’ source code. All these excerpts were extracted from Rails 4.0.0. Most of the APIs described in this book should remain compatible throughout Rails releases. Very few of them changed since the release of the first edition of this book.1. Note for Windows Developers Some chapters have dependencies that rely on C extensions. These dependen- cies install fine in UNIX systems, but Windows developers need the DevKit,2 a toolkit that enables you to build many of the native C/C++ extensions available for Ruby. Download and installation instructions are available online at http://rubyin- staller.org/downloads/. Alternatively, you can get everything you need by installing RailsInstaller,3 which packages Ruby, Rails, and the DevKit, as well as several other common libraries. What Is in the Book? We’ll explore the inner workings of Rails across eight chapters. In Chapter 1, Creating Our Own Renderer, on page 1, we will introduce rails plugin, a tool used throughout this book to create Rails plugins, and customize 1. http://www.pragprog.com/titles/jvrails/ 2. http://rubyinstaller.org/downloads/ 3. http://railsinstaller.org report erratum • discuss What Is in the Book? • ix render() to accept :pdf as an option with a behavior we will define. This chapter starts a series of discussions about Rails’ rendering stack. In Chapter 2, Building Models with Active Model, on page 17, we will take a look at Active Model and its modules as we create an extension called Mail Form that receives data through a form and sends it to a preconfigured email. Then in Chapter 3, Retrieving View Templates from Custom Stores, on page 39, we will revisit the Rails rendering stack and customize it to read templates from a database instead of the filesystem. At the end of the chapter, we will learn how to build faster controllers using Rails’ modularity. In Chapter 4, Sending Multipart Emails Using Template Handlers, on page 61, we will create a new template handler (like ERB and Haml) on top of Mark- down.4 We’ll then create new generators and seamlessly integrate them into Rails. And in Chapter 5, Streaming Server Events to Clients Asynchronously, on page 85, we will build a Rails engine that streams data to clients. We will also see how we can use Ruby’s Queue class in the Ruby Standard Library to synchro- nize the exchange of information in between threads, finishing with a discus- sion about thread safety and eager loading. In Chapter 6, Writing DRY Controllers with Responders, on page 109, we will study Rails’ responders and how we can use them to encapsulate controllers’ behavior, making our controllers simpler and our applications more modular. We will then extend Rails responders to add HTTP Cache and internationalized Flash messages by default. At the end of the chapter, we’ll learn how to cus- tomize Rails’ scaffold generators for enhanced productivity. In Chapter 7, Managing Application Events with Mountable Engines, on page 137, we will build a mountable engine that stores information about each action processed by our application in a MongoDB database and exposes them for further analysis through a web interface. We will finish the chapter talking about Rack and Rack’ middleware stacks while writing our own mid- dleware. Finally, in Chapter 8, Translating Applications Using Key-Value Backends, on page 163, we will learn about I18n and customize it to read and store transla- tions in a Redis data store. We will create an application that uses Sinatra as a Rails extension so we can modify these translations from Redis through 4. http://daringfireball.net/projects/markdown report erratum • discuss