From the Library of Shirong Chen The Merb Way From the Library of Shirong Chen Addison-Wesley Professional Ruby Ser...

Author: Foy Savas

220 downloads 581 Views 4MB Size Report

This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!

Report copyright / DMCA form

DOWNLOAD PDF

From the Library of Shirong Chen

The Merb Way

From the Library of Shirong Chen

Addison-Wesley Professional Ruby Series Obie Fernandez, Series Editor

The Addison-Wesley Professional Ruby Series provides readers with practical, people-oriented, and in-depth information about applying the Ruby platform to create dynamic technology solutions. The series is based on the premise that the need for expert reference books, written by experienced practitioners, will never be satisﬁed solely by blogs and the Internet.

informit.com/ruby

From the Library of Shirong Chen

The Merb Way

Foy Savas

Upper Saddle River, NJ • Boston • Indianapolis • San Francisco New York • Toronto • Montreal • London • Munich • Paris • Madrid Capetown • Sydney • Tokyo • Singapore • Mexico City

From the Library of Shirong Chen

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 publisher was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals. The author and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein. The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact:

Acquisitions Editor Debra Williams Cauley Development Editor Michael Thurston Managing Editor John Fuller Project Editor Anna Popick

U.S. Corporate and Government Sales (800) 382-3419 [email protected]

Copy Editor Barbara Wood

For sales outside the United States please contact:

Indexer Richard Evans

International Sales [email protected]

Proofreader Barbara Wood

Visit us on the Web: informit.com/aw Library of Congress Cataloging-in-Publication Data Savas, Foy. The Merb way / Foy Savas. p. cm. ISBN 978-0-321-60638-9 (pbk. : alk. paper) 1. Web site development. 2. Merb (Electronic resource) I. Title. TK5105.888.S2775 2009 006.7’6—dc22

Editor-in-Chief Mark Taub

Technical Reviewers Matthew Knox Jen Lindner Editorial Assistant Kim Boedigheimer Cover Designer Chuti Prasertsith

2009013263

c 2009 Pearson Education, Inc. Copyright All rights reserved. Printed in the United States of America. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to:

Compositor ITC

Pearson Education, Inc. Rights and Contracts Department 501 Boylston Street, Suite 900 Boston, MA 02116 Fax: (617) 671-3447 The code in this book may be distributed only subject to the terms and conditions set forth in the MIT License. The MIT License reads: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation to the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. ISBN-13: 978-0-321-60638-9 ISBN-10: 0-321-60638-8 Text printed in the United States on recycled paper at Donnelley in Crawfordsville, Indiana. First printing, June 2009

From the Library of Shirong Chen

To Sophia —I think we can afford to eat this month

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

Contents

Foreword xix Acknowledgments xxi Merb pastie xxiii Introduction xxvii About the author xxxi

Chapter 1 1.1 1.2

1.3

1.4

Fundamentals 1

Generating a new application 1 The layout of a Merb application 2 1.2.1 Very flat layout 3 1.2.2 Flat layout 6 1.2.3 Standard layout 8 Interactive Merb 9 1.3.1 Console methods 10 1.3.2 Sandboxing 11 Merb configuration 12 1.4.1 Init script 12 1.4.1.1 Gems and load path 12 1.4.1.2 Dependencies 13 after_app_loads 14 1.4.1.3 1.4.1.4 Template engine 14 1.4.1.5 Basic configuration 14

vii From the Library of Shirong Chen

viii

Contents

1.5

1.6

1.4.1.6 ORM options 14 1.4.1.7 Testing options 15 1.4.1.8 Inflector 15 1.4.2 Environments 16 1.4.3 Router 17 1.4.4 Logging 17 1.4.4.1 Using logging 18 1.4.4.2 Viewing logs 18 1.4.5 Database 19 Understanding the Merb stack 20 1.5.1 Extlib 20 1.5.1.1 ObjectSpace 20 Class 20 1.5.1.2 Object 21 1.5.1.3 1.5.1.4 String 21 Time 22 1.5.1.5 DateTime 22 1.5.1.6 1.5.1.7 Pathname 22 1.5.1.8 blank? 22 Logger 22 1.5.1.9 1.5.1.10 Mash 22 1.5.1.11 SimpleSet 23 1.5.1.12 VirtualFile 23 1.5.1.13 LazyArray 23 1.5.1.14 Hook 23 1.5.1.15 Pooling 23 1.5.2 Rack 23 1.5.2.1 Adapter options 23 1.5.2.2 How Rack works 24 1.5.3 ORMs 26 1.5.4 Plugins 26 An overview of Merb internals 27 1.6.1 Boot loaders 27 1.6.1.1 BootLoader::Logger 27 1.6.1.2 BootLoader::DropPidFile 28 BootLoader::Defaults 28 1.6.1.3 BootLoader::BuildFramework 28 1.6.1.4

From the Library of Shirong Chen

Contents

1.7

ix

1.6.1.5 BootLoader::Dependencies 29 1.6.1.6 BootLoader::MixinSession 29 BootLoader::BeforeAppHooks 29 1.6.1.7 BootLoader::LoadClasses 29 1.6.1.8 BootLoader::Templates 29 1.6.1.9 1.6.1.10 BootLoader::MimeTypes 30 1.6.1.11 BootLoader::Cookies 30 1.6.1.12 BootLoader::SetupSession 30 1.6.1.13 BootLoader::AfterAppLoads 30 1.6.1.14 BootLoader::SetupStubClasses 31 1.6.1.15 BootLoader::ChooseAdapter 31 1.6.1.16 BootLoader::StartWorkerThread 31 1.6.1.17 BootLoader::RackUpApplication 31 1.6.1.18 BootLoader::ReloadClasses 32 1.6.1.19 BootLoader::ReloadTemplates 32 1.6.2 Server 32 1.6.3 Requests 33 1.6.4 Router 33 1.6.5 Dispatcher 33 1.6.6 Controllers 34 1.6.7 Sessions 34 1.6.8 Worker 34 Conclusion 35

Chapter 2 2.1

2.2

Routing 37

How Merb routing works 38 2.1.1 Route conditions 39 2.1.1.1 Route method 39 2.1.1.2 Route path 40 2.1.1.3 Other conditions 41 2.1.2 Route parameters 42 Router configuration 43 2.2.1 The router file 43 2.2.2 The prepare block 43 2.2.3 Route order 44 2.2.4 Adding routes later on 44

From the Library of Shirong Chen

x

Contents

2.3

2.4

2.5

2.6

2.7

Checking routes 45 2.3.1 Listing routes 45 2.3.1.1 Using interactive Merb 45 2.3.1.2 Using the audit routes rake task 48 2.3.2 Trying the router 49 2.3.2.1 For URL recognition 49 2.3.2.2 For URL generation 50 Match rules 50 2.4.1 Literal matching 50 2.4.2 Symbolic matches 51 2.4.2.1 Automatic parameters 51 2.4.2.2 Flexible segmentation 52 2.4.2.3 Segment-specific regular expressions 52 2.4.3 Optional matches 52 2.4.4 Full regular expressions 53 2.4.5 Deferred routes 53 Registering routes 54 2.5.1 Using to 54 2.5.2 Using with 55 2.5.3 Using register 55 2.5.4 Redirects 56 2.5.5 Using symbols 56 2.5.6 Using other captures 56 Other route settings 57 2.6.1 Setting defaults 57 2.6.2 Named routes 57 2.6.3 Setting prefixes 58 2.6.3.1 Name prefix 58 2.6.3.2 Controller prefix 59 2.6.3.3 Namespaces 59 2.6.4 Fixatable routes 59 Resource routes 60 2.7.1 Standard resources routing 60 2.7.1.1 Index 61 2.7.1.2 New 62 2.7.1.3 Create 62 2.7.1.4 Edit 62

From the Library of Shirong Chen

Contents

2.8

xi

2.7.1.5 Update 62 2.7.1.6 Destroy 62 2.7.1.7 Show 62 2.7.2 Singular resource routing 2.7.3 Using identify 63 Conclusion 64

Chapter 3 3.1

3.2

3.3

3.4

62

Controllers 65

From request to controller 65 3.1.1 A simple application 66 3.1.2 How requests get dispatched 66 3.1.3 The controller’s perspective 67 The controller classes 68 3.2.1 The abstract controller 69 3.2.1.1 Class methods 69 3.2.1.2 Instance methods 70 3.2.2 The Merb controller 70 3.2.2.1 Class methods 70 3.2.2.2 Instance methods 72 3.2.3 The application controller 72 3.2.4 The exceptions controller 74 3.2.5 Other controllers 74 Custom controller classes 75 3.3.1 Controller location 75 3.3.2 Naming controllers 76 3.3.3 Organizing controller methods 76 3.3.3.1 Sharing a nonaction method 77 3.3.3.2 Making methods available to subclasses 3.3.3.3 Increasing readability of an action 78 3.3.4 Setting callable actions 79 3.3.4.1 Hiding an action 79 3.3.4.2 Showing an action 79 Filters 79 3.4.1 Before filters 80 3.4.2 After filters 81 3.4.3 Filter options 82

77

From the Library of Shirong Chen

xii

Contents

3.5

3.6

3.7

3.8 3.9

3.10

3.4.4 Skipping filters 83 Redirects 84 3.5.1 A redirect caveat 84 3.5.2 Redirects after POST requests 85 3.5.3 Redirecting in before filters 86 Exceptions 87 3.6.1 Raising an exception 87 3.6.2 Controller exceptions 87 3.6.3 The exceptions controller 88 Rendering templates 89 3.7.1 How templates are compiled 89 3.7.2 Basic rendering 91 3.7.3 Template 91 3.7.4 Formats 92 3.7.5 Status 94 3.7.6 Layout 94 display 95 3.7.7 3.7.8 render_chunked 96 3.7.9 render_deferred 96 3.7.10 render_then_call 97 run_later 97 Sending and streaming 97 3.9.1 Sending files 98 3.9.2 Streaming files 98 Conclusion 99

Chapter 4 4.1

4.2

Views 101

ERB 101 4.1.1 Basic delimiters 102 4.1.2 Removing whitespace 102 4.1.3 Comments 103 4.1.4 Merb’s block-aware enhancer Haml 105 4.2.1 Tags 105 4.2.2 Indentation 106 4.2.3 IDs and classes 106

103

From the Library of Shirong Chen

Contents

4.3 4.4 4.5

xiii

4.2.4 Attributes 107 4.2.5 Interpreting lines 107 4.2.6 Outputting lines 107 4.2.7 Outputting string lines 108 4.2.8 Sanitized lines 108 4.2.9 Preserving whitespace 108 4.2.10 Filters 109 Merb view templates 109 Partials 111 Conclusion 112

Chapter 5 5.1 5.2 5.3

5.4

5.5

Models 113

Configuration 113 Model classes 115 Properties 118 5.3.1 Database storage 120 5.3.1.1 Automigrating the DB schema 121 5.3.2 Defining properties 127 5.3.2.1 Property types 127 5.3.2.2 Option hash 131 Associations 132 5.4.1 Belongs to 133 5.4.2 Has 135 5.4.3 Has through 138 CRUD basics 140 5.5.1 Creating records 140 5.5.2 Retrieving records 142 5.5.2.1 Special query parameters 145 5.5.2.2 Lazy loading of collections 146 5.5.2.3 Lazy loading of properties 148 5.5.2.4 Strategic eager loading 150 5.5.3 Updating records 152 5.5.3.1 Using update_attributes 152 5.5.3.2 Original and dirty attribute values 153 5.5.4 Destroying records 154

From the Library of Shirong Chen

xiv

Contents

5.6 5.7

5.8

Hooks Plugins 5.7.1 5.7.2 5.7.3 5.7.4

154 155 Extra property types 155 Timestamps 156 Aggregates 158 Validations 162 5.7.4.1 Conditions 163 5.7.4.2 Contexts 164 5.7.4.3 Errors 164 Conclusion 165

Chapter 6 6.1 6.2

6.3

6.4 6.5 6.6

6.7

Truncate helper 167 Numeric helpers 168 6.2.1 Two digits 168 6.2.2 Minutes to hours 169 6.2.3 Currency strings 169 Date and time helpers 171 6.3.1 Formats 171 6.3.2 Ordinals 173 6.3.3 Time DSL 174 6.3.4 Relative time 175 Cycle helper 176 Tag helpers 177 Form helpers 179 6.6.1 Builders 179 6.6.2 Helpers 187 Conclusion 192

Chapter 7 7.1

7.2 7.3

Helpers 167

Slices 193

Slice development 193 7.1.1 Generating slices 193 7.1.2 Running slices 196 7.1.3 Building slices 199 7.1.4 Slice controllers 200 Slice usage 201 Conclusion 203

From the Library of Shirong Chen

Contents

xv

Chapter 8 8.1 8.2 8.3

8.4 8.5 8.6

How sessions work 205 Configuration 206 Storing sessions 207 8.3.1 Session containers 207 8.3.2 Session store containers 208 8.3.3 Session storage mechanisms 211 8.3.3.1 Cookie sessions 211 8.3.3.2 Memory sessions 214 8.3.3.3 Memcached sessions 216 8.3.3.4 DataMapper sessions 217 Request access 219 Controller access 220 Conclusion 220

Chapter 9 9.1

9.2

9.3

Sessions 205

Authentication 221

Auth core 221 9.1.1 Authentication 223 9.1.2 Strategy 227 9.1.3 Sessions 231 9.1.4 Errors 232 9.1.5 Responses 233 9.1.6 Helpers 234 9.1.7 Router helper 235 9.1.8 Customizations 236 9.1.9 Callbacks 236 Auth more 237 9.2.1 Strategies 238 9.2.1.1 Basic 239 9.2.1.2 Password form 241 9.2.1.3 OpenID 242 9.2.2 Models 242 9.2.3 Controller 245 Auth password slices 245 9.3.1 Lib file 246

From the Library of Shirong Chen

xvi

Contents

9.4

9.3.2 Controller 247 9.3.3 Views 249 Conclusion 251

Chapter 10 10.1

10.2 10.3

10.4 10.5 10.6

Configuration 253 10.1.1 SMTP 253 10.1.2 Sendmail 254 10.1.3 Test send 254 10.1.4 Custom delivery methods Using mailers directly 255 Mail controllers 257 10.3.1 Invoking actions 258 10.3.2 Parameters 259 10.3.3 Attaching files 260 10.3.4 Templates 261 Testing 261 Generation 261 Conclusion 262

Chapter 11 11.1 11.2 11.3 11.4

Mailers 253

254

Parts 263

Parts controllers 263 Invoking actions 266 Generation 267 Conclusion 267

Chapter 12

Caching 269

12.1

Configuration 269 12.1.1 Fundamental stores 269 12.1.2 Strategy stores 270 12.2 Caching basics 271 12.2.1 Writing 271 12.2.2 Reading 272 12.2.3 Fetching 273 12.2.4 Deleting 273 12.3 Caching helpers 274

From the Library of Shirong Chen

Contents

xvii

12.3.1 Action caching 274 12.3.2 Eager caching 275 12.3.3 Fragment caching 277 12.3.4 Partial caching 277 12.4 Conclusion 278

Chapter 13 13.1 13.2 13.3 13.4 13.5 13.6 13.7 13.8 13.9

Testing 279

Rake tasks 279 Spec files 282 Model specs 283 Request specs 285 Request helper 289 Request matchers 290 RSpec extensions 292 Miscellaneous extensions Conclusion 295

Afterword Index

294

297

299

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

Foreword

I viewed the Merb project with a big dollop of suspicion almost from the very start. First of all, it started out as a really simple concept, but got a lot more complicated as additional contributors got involved. And whether my suspicion was misplaced or not, I couldn’t shake the feeling that the Merb people were insisting on reinventing Ruby on Rails simply to be difficult. Merb isn’t that different from Rails, nor is it a major improvement as far as I was concerned. It was only slightly better (in some regards), and only slightly different from Ruby on Rails. Sure there were some benchmarks showing big performance gains for using Merb, but I was not convinced enough to switch. And I couldn’t bear to use Merb and Rails concurrently. You see, they were very similar, yet different in subtle ways. The last thing I want to do when I’m programming on hard deadlines is to slow down to remember the differences between Merb’s render method and the one in Rails, etc. Life continued, and while I was very happy and making a ton of money working with and writing about Rails, I still occasionally looked at Merb, if only to see what they were up to. Sure enough, by 2008 my perception of Merb had started to change. I met Foy Savas and he gave me the gist of why it would make sense to write The Merb Way. I concurred and Foy got busy writing. As Merb approached a 1.0 release, it appeared that Yehuda Katz and his band of merry discontents were actually achieving a viable platform, one that would attain permanent status as an alternative to Rails. I started hearing about significant production projects running on Merb, such as yellowpages.com. My appreciation for Merb grew, as I got familiar with the project goals and noticed how the competition was acting as a healthy stimulus for Rails to not rest on its laurels. I wasn’t ready to switch to Merb myself, since my key criterion is maturity, which Rails has in spades, but no longer was I suspicious. xix From the Library of Shirong Chen

xx

Foreword

In November of 2008 I was extremely happy about Foy being almost finished writing the first manuscript of this book, knowing that it would be a good complement to the Professional Ruby Series and a good companion for The Rails Way. Foy delivered an awesome conference presentation in Boston where he covered some of the key concepts from the book in an engaging and entertaining manner—the crowd ate it up and I knew The Merb Way would be a winner. It wasn’t too many weeks later that the unthinkable happened. After an eruption of feuding between members of the Rails and Merb teams, some secret meetings occurred and shocking news was unveiled right before Christmas: DHH and Yehuda happily proclaimed that the core teams of both frameworks were merging and that within a year, the Merb codebase would be merged with Rails in order to produce Rails Version 3, after which development of Merb would discontinue. The million-dollar question (okay, not quite that much) for Foy and myself as the Series Editor was whether to continue with the publication of The Merb Way. After all, if the Merb framework was going away, then what was the point? After letting the matter settle for a while, we arrived at our answer, which you already know since you are holding this book. It turns out that learning about Merb is valuable in a number of important ways. First, Merb is still used rather widely and we suspect that its lifetime will exceed what the current core team has in mind. Second, Foy is a gifted writer and his descriptions of the philosophies that impacted the design and implementation of Merb are definitely useful to everyone who will be affected by the changes that will happen in Rails 3. It’s with great pleasure that I welcome the incomparable Foy Savas and publish The Merb Way as a full-fledged and proud installment of the Professional Ruby Series. I sincerely hope you get as much out of this book as I have. Obie Fernandez March 31, 2009

From the Library of Shirong Chen

Acknowledgments

First off, thanks go to all the Merb and DataMapper contributors. Obviously, no Merb would mean no Merb Way, but that’s certainly not all I want to thank them for. The elegance of both Merb and DataMapper, especially within their implementations, profoundly sets off my passion for holding code to an even higher standard of clarity. Consequently, throughout this book I have highlighted and included extensive amounts of Merb and DataMapper source code, truly making the contributors to both projects contributors to this book as well. I would like to thank those individuals with whom I have personally interacted the most: Matt Aimonetti, Ben Burkert, Dirkjan Bussink, Lori Holden, Michael D. Ivey, Michael Klishin, Dan Kubb, Carl Lerche, Daniel Neighman, Sam Smoot, Ezra Zygmuntowics, and especially Yehuda Katz. Completing this book against a backdrop of changing technology demanded the help of numerous friends and editors. Without their advice, analysis, and sharp eyes, I don’t know how it would ever have gotten done. To Sophia Chou, Andrew Guay, Kieran Huggins, Matt Knox, Jennifer Lindner, Bryan Ray, and Michael Thurston—thank you for each and every note and correction you made. A huge thank you goes to both Obie Fernandez and Debra Williams Cauley. You two are truly the driving force behind the Addison-Wesley Professional Ruby Series and the reason why it produces such high-quality books. Obie, had you not spotted the importance of Merb at such an early stage, inspired me with your own book on Rails, and pushed me to write one on Merb even after the frameworks merged, who knows if such a topic would have received the treatment it deserved? And Debra, simply wow. I know coordinating this book was no easy job, but you did so with such a seemingly paradoxical mix of patience and drive that I will remain thankful forever.

xxi From the Library of Shirong Chen

xxii

Acknowledgments

Finally, my warmest thanks and love go to all the members of my family who undeniably play a strong part in all that I do. Without your support, encouragement, perspective, and insight, I don’t know where, or more important who, I would be—thank you, all.

From the Library of Shirong Chen

Merb pastie

Anything that starts off with pure code is good in my book. Pun intended, here is Ezra Zygmuntowicz’s original Merb pastie, as found at http://pastie.org/14416, here formatted for the pages of this book. #!/usr/local/bin/ruby require 'rubygems' require 'mongrel' # Add the request handler directory to the load path. # Files in the 'app/controllers' dir will be mapped # against the first segment of a URL $LOAD_PATH.unshift( File.join( File.dirname( _ _FILE_ _ ) , 'app/controllers' ) ) PORT = 4000 # If true, controller source files are 'load'ed # rather than 'require'd so you can tweak code and # reload a page. ALLOW_RELOADING = true class String def import ALLOW_RELOADING ? load( self + '.rb' ) : require( end

self )

def controller_class_name self.capitalize

xxiii From the Library of Shirong Chen

xxiv

Merb pastie

end end class MerberHandler < Mongrel::HttpHandler def instantiate_controller(controller_name) controller_name.import begin return Object.const_get( controller_name.controller_class_name ).new rescue Exception # If life is sad, then print the error and # re-raise the exception: warn "Error getting instance of "+ "'#{controller_name.controller_class_name}':"+ "#{$!}" raise $! end end # Grab the request URL and break it up to get the # parts that map to the code request. There's a # simple assumption that the first part defines a # class holding the desired code. def handle(request) path = request.params["PATH_INFO"] puts request.inspect puts '='*50 # Might want to consider returning a # default object if we have a bare URL. return [nil, nil, nil ] if path =˜ /ˆ\/$/ c, m, args = path.to_s.gsub( /ˆ\//, '' ).split( '/' , 3) args = args.to_s. strip.empty? ? nil : args.split( '/' ) # Return an array with our object instance, # the method name, and any args. [ instantiate_controller(c), m, args ] end def process(request, response) response.start(200) do |head,out| head["Content-Type"] = "text/html" begin # Looks at the URL and breaks it up into # chunks that map to a class, a method call, # and arguments.

From the Library of Shirong Chen

Merb pastie

xxv

# Basically, # /foo/bar/baz/baz # ends up becoming # Foo.new.bar( baz, baz ) controller, method, args = handle(request) if controller # No allowance for default methods. # Worth considering, maybe default # to 'index' or 'to_s' out << ( args ? controller.send( method, *args ) : controller.send( method ) ) else out << "Error: no merb "+ "controller found for this url."+ "" end rescue Exception out << "Error! #{$!}" end end end end h = Mongrel::HttpServer.new("0.0.0.0", PORT) h.register("/", MerberHandler.new) h.register("/", Mongrel::DirHandler.new("assets")) h.run.join - -merb.rb- - require 'erb' class Merb # Define a class variable to track the default # location of the template files. @@template_dir = File.expand_path( ( File.dirname( _ _FILE_ _ ) + "/../views/merb" ) )

def hello(*names) # Assign the parameter to an instance variable @name = names.join(', ') template = ERB.new( IO.read( @@template_dir + '/hello.rhtml' ) ) template.result( binding )

From the Library of Shirong Chen

xxvi

Merb pastie

end end --hello.rhtml- Hello, <%= @name %>

Hello, <%= @name %>!

From the Library of Shirong Chen

Introduction

ナ ൴ ナ㒋 ፆ ナ ඇ ൴ ඇ 㒋 ፆ ඇ — ❨ᆎ A way that can be taken rarely stays the way. A name that can be given rarely stays the name. —Laozi (translated by your author)

The first two lines of the Dao De Jing capture truths so fundamental that we find them everywhere—including, without exception, in this book. Originally entitled the The Merb Companion, it was intended to be the advanced practitioner’s bible. But the little framework named Merb grew quickly, so much so that the Rails world took notice, and before long, the core teams came together and decided to merge the two. Yet despite Merb’s fundamentals being seen as the basis for the features of the future, Rails conventions needed to be maintained long-term. Incidentally, this book’s content was left in an awkward limbo. Should we wait for the completion of the merge or perhaps publish immediately? Should we preserve the chapters we had written so far or produce them anew after the merge? Soon, however, an epiphany came. Though the book had material highly relevant to the Merb developers of the day and was equally suitable for bringing foresight to the Rails developers of tomorrow, its greatest and lasting potential was in shedding light on how Merb, the framework that even Rails envied, had been designed. Thus, we arrive here, at the introduction of The Merb Way.

xxvii From the Library of Shirong Chen

xxviii

Introduction

Born a pastie Zoom back to September 9, 2006. If you were using Rails, it was version 1.1. As for Git, it was still just something the Linux kernel used. So naturally, when Ezra Zygmuntowicz needed to publicly distribute the then only 120-line source code for Merb, a pastie made the most sense. Turn back a few pages and you’ll find that pastie, prepended to this book in all of its glory. Look it over once and you’ll realize Ezra had an itch to scratch: fast Ruby template rendering with the smallest possible memory footprint. To do this he used only two gems, Mongrel and ERB, which, for those keen on etymology, also serve as the roots of the name Merb itself. But like any project that starts off both small and practical, it grew. A few months later a gem was put up on RubyForge. For a while it came with an example app that touted Merb’s ability to handle file uploads while not locking out other requests. This became the most popular use of Merb, often appearing coupled with Rails applications in the wild.

Created by rebels But Merb has moved far beyond the stage when its application generator could produce the uploader application. This may have been because it quickly became a breeding ground in which Rails concepts could be rethought. Eventually, this led to a shared vision among developers that Merb would be Rails done right. Thankfully, the openly opinionated nature of Rails actually kept them away from simply adopting alternative opinions. Instead, they chose as one of their maxims agnosticism, in the form of opt-in modularity. This allowed Merb application developers to work with whatever tools they needed for their projects. Merb’s versatility meant that it would become the underlying framework for numerous customized stacks that otherwise did not easily fit within the opinions of Rails. Its developers, consequently, have often been thought of as rebels from the Rails mentality, since many of them maintain strong opposing views on particular Rails opinions. However, that’s not all there is to the Merb development story. The crowd of developers also had an arguably more scientific bent, aiming to make the best selection of the methods they employed through microbenchmarks. Ruby is often cited as one of the world’s slowest programming languages from a computational perspective, but to the developers of Merb, this didn’t mean that microseconds didn’t matter. After all, web development frameworks are often tested in terms of responses per second. So when it came to Merb internals, whether it was in route matching or filter chaining, only the fastest Ruby constructs were used. The end result was Merb blazing past Rails

From the Library of Shirong Chen

Introduction

xxix

in response time benchmarks. More profoundly, Merb raised the bar for Ruby web framework performance in general, finally allowing Ruby to win when pitted against other frameworks from different languages. Interestingly enough, this combination of performance and modularity is also indicative of another Merb development character trait: its desire to solve higher-level problems. Whereas Rails features have nearly consistently been born of necessity, Merb’s focus has been on abstract goals like versatility and design. This has pushed the limits of what can be done with Merb, resulting in advancements like the abstract controller class, code slices, and arbitrary application layout. In sum, Merb in many ways conceptually broke the “frame” in framework by thinking of itself less as a way to produce Model-ViewController (MVC) web apps and more as a highly modular platform upon which nearly all Ruby web development, no matter how unusual, can occur.

The future of Rails Put all this goodness together, and you’re bound to attract the attention of most developers. Not surprisingly, teams large and small began using Merb as a full application framework in production environments for their most demanding applications. This finally put Merb to the test, and the results were completely in line with its benchmarks: more responses per second with a solidly smaller memory footprint. All of this occurred at the cusp of its reaching its 1.0 release on November 7, 2008. Quickly the Merb development team oriented itself toward larger goals through what would have been a 2.0 release. Objectives included, among other things, an abstracted Object Relational Mapper (ORM) that could be used to create an agnostic admin panel and convenient direct routing to templates. But with the stable release already out, developers at large began taking Merb much more seriously, and soon online comment wars fanned flames between the Rails and Merb core teams. Thus prompted to confront each other, the core development teams began to talk it over. However, soon they began earnestly asking themselves whether the large amount of duplication between the two frameworks was warranted. At the end they concluded two things: first, that each side had aspects that would be beneficial to the other, and second, that yes, they could work together. Announced officially on December 23, 2008, the Rails and Merb development effort would be merged, with a promise of a smooth transition from both Merb 1 and Rails 2 to the combined Rails 3. So what can we expect from this merger? Well, above all will be the fusion of attitudes and objectives from both sides. The Rails of the future will undoubtedly appeal to developers in both pragmatic and idealistic ways. Merb will bring speed, performance,

From the Library of Shirong Chen

xxx

Introduction

and modularity along with a tempering of the preestablished Rails opinions. We will see a flowering of custom Rails stacks, some of which may eventually push the limits of the Rails framework itself. Toward what—who knows? But with the possibility of such a greatly expanded domain, two things are certain. The first is that anyone in software who needs to build an agile and sophisticated web application upon a highperformance framework should definitely get on this train. The second, which applies more to developers themselves, is that a firm understanding of the design decisions behind Merb’s development will not only prepare them for the future of Rails but can also open up their own talents through the elegance of its code. This book is thus focused on giving developers the deepest possible understanding of Merb itself. While you may use it as a reference guide in the development of Merb applications (which we strongly recommend without hesitance until the release of Rails 3), you may also appreciate its guided exploration of the Merb source. That said, for those afraid of code, it may perhaps be a good time to put this book back on the shelf. Everyone else, be warned; we’re going to cut deep into the framework itself, revealing not only what was done, but what can be learned from it. As you move forward, do not lose focus. After all, they say that one should always aim to learn from the best, and through Merb, the framework that without exaggeration brought the Rails monoculture to its knees, you are doing just that.

From the Library of Shirong Chen

About the author

Foy Savas runs Assembly, a Boston-based web consultancy focused on innovative technology. In the past, he has acted as CTO of a large health and fitness site and as a lead consultant for several white-labeled web applications. Foy is also one of the earliest adopters of Merb and over the past year has taken several Merb applications, both small and large, into production. Actively involved in the Merb open-source ecosystem, he has also been a core contributor to both Merb and DataMapper.

xxxi From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 1

Fundamentals

The true power of Merb arises from the framework’s emphasis on hackability. Though misinformed readers may misunderstand this term, thinking Merb means that their site is “pwnd” upon launch, that’s not the hack we’re talking about. Instead, when we say hack, we mean the act of extending the functionality of something beyond its original scope. Merb does this well, and in this chapter we’ll discover how Merb enables this kind of unbounded development by examining the hackability within Merb’s own fundamentals. To do this, we’ll explore the Merb stack, discuss configuration options, and pull apart internals. If you’re a newcomer to Merb, you’ll pick up the practical know-how to get started using the framework. Experienced developers shouldn’t overlook what’s here, though, because while we’ve designed this chapter as a walk-through of the basics, it’s in no way an installation guide. The digging we do into the internals may reveal aspects of Merb that you have not yet found through routine development. In any case and no matter your background, by the end of this chapter you should be able to concretely identify the design decisions that have made Merb so agile and robust.

1.1 Generating a new application The easiest way to set up a new Merb application is to use merb-gen. This command is standardly available as part of the Merb bundle. As a developer, you’ll be using it regularly to quickly generate common files used by Merb. One of its uses is the creation of a skeleton for the overall layout of new applications. Below we make our first app, by specifying the option app followed by the name of the application directory. $ merb-gen app first_app

This creates a new directory named first_app as well as a number of subdirectories and files. Merb uses all of these subdirectories and files to define the application’s desired 1 From the Library of Shirong Chen

2

Chapter 1: Fundamentals

behavior. To run our first app, we first need to change the directory into its root and fire up Merb using the command merb: $ cd first_app $ merb Loading init file from /home/foysavas/src/first_app/config/init.rb Loading /home/foysavas/src/first_app/config/environments/ development.rb ˜ Connecting to database... ˜ Loaded slice 'MerbAuthSlicePassword' ... ˜ Parent pid: 5917 ˜ Compiling routes... ˜ Activating slice 'MerbAuthSlicePassword' ... merb : worker (port 4000) ˜ Starting Mongrel at port 4000 merb : worker (port 4000) ˜ Successfully bound to port 4000

Our Merb app is now running and bound to port 4000. Consequently, if we visit http://localhost:4000, we’ll see a welcome page. We can shut down the Merb

server by using Ctrl-C. Note that this may not happen instantaneously as Merb looks to gracefully shut down each of the worker processes. Merb’s master process Merb uses a master process to manage clusters of server processes. This provides a number of benefits over its lone process alternative, including

• Graceful boot-up and port binding that enable seamless deployment • Huge memory saving for clusters when using Ruby Enterprise Edition • Blazing-fast worker process reload for live development

1.2 The layout of a Merb application Now that we’ve generated our first application, it’s a good time to bring up the fact that the directory structure and file arrangement we just saw are not set in stone. Merb out-of-the-box is far more versatile than that. Though the layout we just generated is the standard Merb layout, merb-gen itself can produce a few alternative common layouts. These are best used for simpler applications and are known as the flat and very flat layouts. Table 1.1 describes the various layouts available to you as a Merb application developer. In order to gain an understanding of what code is absolutely necessary to make

From the Library of Shirong Chen

1.2

The layout of a Merb application

3

Table 1.1 Merb layouts Layout

merb-gen Argument

Best Use

Standard

app

The standard layout provides the most comfort for most developers through a highly conventional and intelligent structure. We recommend it for nearly every application you develop.

Core

core

Like the standard layout but without the numerous dependencies the Merb stack makes. This is the best starting point for the Merb developer who does not intend to use the full default Merb stack.

Flat

flat

The flat layout is best used when you’re going to design an application that crafts simple responses but that still uses view templates. It’s also fairly easy to grow a flat layout into a standard one.

Very flat

very_flat

Very flat Merb applications are the way to go when keeping everything in one file provides some special advantage. We’ll use these numerous times in demonstration applications, and you may find them useful for micro-applications as well as proof-ofconcept work.

Custom

N/A

Custom layouts are possible when you define the location of the numerous types of files Merb uses. We definitely don’t advise taking this route, but if your circumstances are unique, Merb has the flexibility to handle your needs.

a Merb application tick, let’s take a detailed look at what’s inside both of these flatter layouts before we move on to studying the standard full layout.

1.2.1 Very flat layout Using merb-gen, you can easily create a single-file Merb application in the style of Camping or Sinatra. To do this, use the argument very_flat with merb-gen: $ merb-gen very_flat my_very_flat_app Generating with very_flat generator: [ADDED] my_very_flat_app.rb

From the Library of Shirong Chen

4

Chapter 1: Fundamentals [ADDED] [ADDED] [ADDED] [ADDED]

Rakefile spec .gitignore merb.thor

This produces a directory my_very_flat_app containing a single Ruby file along with some other useful files with content similar to the following snippet: # run very flat apps with merb -I . Merb::Config.use { |c| c[:framework] = { :public => [Merb.root / "public", nil] } c[:session_store] = 'none' c[:exception_details] = true c[:log_level] = :debug # or error, warn, info or fatal c[:log_stream] = STDOUT # or use file for logging: # c[:log_file] = Merb.root / "log" / "merb.log" c[:reload_classes] = true c[:reload_templates] = true } Merb::Router.prepare do match('/').to( :controller => 'my_very_flat_app', :action =>'index' ) end class MyVeryFlatApp < Merb::Controller def index "hi" end end

Stepping into its directory is not enough to run a very flat application. The comment on the first line, however, points us in the right direction. Using the -I flag, we can specify the init file for our Merb application: merb -I my_very_flat_app.rb

Now if you visit http://localhost:4000, you should see the message returned by the value of the index action.

From the Library of Shirong Chen

1.2

The layout of a Merb application

5

Design decision: the Principle of Least Surprise This simple example exhibits one of Merb’s founding principles, that of ‘‘least surprise.’’ Here, in order to give us the least surprise, any request handled by this method receives a response containing the returned string. This may seem like an obvious design decision, but other frameworks do not behave this way; among other things they presuppose that the purpose of your controller is nearly always to render a template. Consequently, they attempt to render that template without any such explicit method call. The Merb developers chose against so brashly deciding what your controllers would be used for, knowing that such a decision would come at the cost of hackability. They also realized that a great litmus test to make sure that the line between clear, hackable behavior and scope-narrowing magic remains uncrossed was the veritable Principle of Least Surprise, also known as the Principle of Least Astonishment. Anyway, don’t be surprised (pun intended) if you see signs of this principle at work in other aspects of Merb.

Getting back to the code, there are three sections: one for configuration, another for routing, and finally a controller. Each of these sections is fundamental in Merb application development, and that’s why they’re there. Strictly speaking, though, the configuration section wasn’t necessary in order to send “hi” to your browser. If it wasn’t there, Merb would use its default values instead. Design decision: Convention over Conﬁguration This, too, is another example of a principle to which Merb adheres, Convention over Configuration. Ruby on Rails notably popularized this paradigm, and Merb continues the tradition. We’ll find, however, that Merb has tempered the concept of Convention over Configuration through the primacy of hackability. To be more concrete, if a default configuration lessens the amount of code needed without reducing the hackability of your application, then Merb has provided it for you. This demonstrates how Merb has striven to keep opinions at bay and give you the maximum power to get the job done, no matter what the job.

Let’s take a look at the specifics of the config block and see which of the defaults have been overridden. The first of these is the location of public static assets. If you create a directory public/ in the same directory as the application and then add an image, say merb.jpg, you’ll be able to view it at http://localhost:4000/merb.jpg. The second line relating to sessions doesn’t actually override any default but has been included for you to change at will. The third line in the config block switches exception

From the Library of Shirong Chen

6

Chapter 1: Fundamentals

details to true. This allows you to see full exception details on error pages when they occur. For an example, take a look at http://localhost:4000/mybad. With exception details set to true, you will be able to view a stacktrace right in the browser. Set the config value instead to false, and after restarting Merb, you’ll no longer have access to the stacktrace via the browser.

1.2.2 Flat layout If you want to use view templates, but still prefer a single file for the bulk of your code, a flat layout may be just what you’re looking for. The flat layout is optimal for simple Merb applications that do not use models but still have templates. Using merb-gen once again, you can create a flat app using the --flat option: $ merb-gen flat my_flat_app Generating with flat generator: [ADDED] Rakefile [ADDED] application.rb [ADDED] config/framework.rb [ADDED] config/init.rb [ADDED] views/foo.html.erb [ADDED] spec [ADDED] gems [ADDED] merb.thor [ADDED] .gitignore [ADDED] README.txt

This creates a directory structure as follows: . |-|-|-|-| | |-|-|-| ‘-|

README.txt Rakefile application.rb config |-- framework.rb ‘-- init.rb gems merb.thor spec ‘-- spec_helper.rb views ‘-- foo.html.erb

In order to run a flat layout, all we have to do is step into its directory and run merb. You’ll notice that we no longer need to specify a file to include. This is because by default config/init.rb is automatically included.

From the Library of Shirong Chen

1.2

The layout of a Merb application

7

Incidentally, one of the largest benefits of jumping from the very flat to the flat layout is that the presence of the init file allows us to avoid restarting Merb every time we make changes to application code. Instead, in development mode, Merb automatically checks to see if application files have been updated and reloads the appropriate classes for us. You can try this by running Merb and altering the application.rb index method to say "Something Different" instead of "Hello...". If you check via your browser, the response will have changed without the need to restart Merb. Other environments Note that by convention, class reloading applies only to Merb applications running in development mode. This is the default mode for a Merb application, and it’s what we’ve used in every example so far. There are two other standard environments for running Merb applications---production and testing---and we’ll take a look at those later on.

The principal difference here from the Merb standard layout is that all controller code (and possibly model code) is found in application.rb. Another difference is the inclusion of config/framework.rb. This file is actually what prevents Merb from thinking the application is of the default form by defining the flat layout. You’ll notice that config/framework.rb does this by just defining a hash: Merb::Config[:framework] = { :application => Merb.root / "application.rb", :config => [Merb.root / "config", nil], :public => [Merb.root / "public", nil], :view => Merb.root / "views" }

If you change these values, Merb will on boot expect to find particular code in different places. Let’s say you start with a flat application, but soon decide it needs to grow to the standard layout. You won’t have much trouble accomplishing the transition. Here is a series of terminal commands to help you on your way: $ $ $ $ $

mkdir app mv views app/ mkdir app/controllers mv application.rb app/controllers/ rm config/framework.rb

From the Library of Shirong Chen

8

Chapter 1: Fundamentals

As exhibited above, it’s the removal of the config/framework.rb file that defaults us to the standard layout. Finally, though this will run as an application in standard layout, there may be a few more items of cleanup you’d like to attend to. Here’s a list to keep in mind: • Pull out the router in config/init.rb and put it in config/router.rb. • Separate app/controllers/application.rb into as many controllers as needed. • Alter your controllers to subclass from Application instead of Merb:: Controller.

1.2.3 Standard layout Now let’s take a look at the standard layout. Returning to the directory of the first application that we created with merb-gen, we find the following directory tree: . |-|-| | | | |-|-| | | | | | |-|-|-| | |-| | | | | | |-‘--

Rakefile app |-- controllers |-- helpers |-- models ‘-- views autotest config |-- database.yml |-- dependencies.rb |-- environments |-- init.rb |-- rack.rb ‘-- router.rb doc gems merb |-- merb-auth ‘-- session public |-- favicon.ico |-- images |-- javascripts |-- merb.fcgi |-- robots.txt ‘-- stylesheets spec tasks

From the Library of Shirong Chen

1.3

Interactive Merb

9

We haven’t included all the files the standard layout creates (there are a lot of them), but just enough to understand the structure. The directories spec/ and autotest/ serve to facilitate the testing of your application. The Rakefile and tasks directories provide common tasks for use in your application. For now, though, what matters most are these three directories: app/, config/, and public/. The first of these stores all of your application code. To keep everything organized in an MVC way, app/ also has a few subdirectories of its own. By default these include controllers/, helpers/, models/, and views/. Next up, config/ is a directory we saw in the flat layout. It holds init.rb and a number of other environment configuration files. Unlike the flat layout, however, it has a dependencies.rb file which is referenced in init.rb and by default includes the dependencies making up the Merb stack. Another file in the config directory is router.rb. This defines the routes for your application, mapping requests to specific controller actions. Another file definitely worth noticing is database.yml, which defines database access on a per-environment level. Finally, the directory public/, which we also saw in the flatter layouts, is meant to hold assets for your application to serve. These may include images, stylesheets, javascripts, and other static files.

1.3 Interactive Merb Often you’ll want to be able to dig around in a running Merb application. Interactive Merb allows you to do this by giving you an IRB session on a running Merb application. There are two ways to get this kind of console access. The first and simpler way is to add the -i flag to the command merb: $ merb -i Loading init file from /home/foysavas/src/first_app/config/init.rb Loading /home/foysavas/src/first_app/config/environments/ development.rb ˜ Connecting to database... ˜ Loaded slice 'MerbAuthSlicePassword' ... ˜ Parent pid: 25514 ˜ Compiling routes... ˜ Activating slice 'MerbAuthSlicePassword' ... irb: warn: can't alias context from irb_context. irb(main):001:0>

This creates an exclusive interactive instance of your Merb application not bound to any port. If, however, you wanted a Merb application that could respond to web requests as well, then using the -C flag provides a console trap on an otherwise typical

From the Library of Shirong Chen

10

Chapter 1: Fundamentals

Merb instance. To get to this console you have to hit Ctrl-C once Merb is booted. We do this below and then immediately return to server-only mode with the command exit. foysavas@navi:˜/src/first_app$ merb -C Loading init file from /home/foysavas/src/first_app/config/init.rb Loading /home/foysavas/src/first_app/config/environments/ development.rb ˜ Connecting to database... ˜ Loaded slice 'MerbAuthSlicePassword' ... ˜ Parent pid: 26366 ˜ Compiling routes... ˜ Activating slice 'MerbAuthSlicePassword' ... merb : worker (port 4000) ˜ Starting Mongrel at port 4000 merb : worker (port 4000) ˜ Successfully bound to port 4000 ˆCmerb : worker (port 4000) ˜ Interrupt a second time to quit. irb(main):001:0> exit merb : worker (port 4000) ˜ Exiting from IRB mode back into server mode.

Using interactive Merb during development can often speed up the process since you’ll be able to directly interact with the code you’re writing. Some words of caution, though. First, don’t let this lead to writing complex methods you can’t comprehend, just because they produce the right results. Second, direct interaction can’t take the place of proper behavior testing, so don’t treat it that way. Making either of these mistakes will only put you behind later on, especially when you need to rework or extend what you have. Another practical situation when interactive Merb is helpful is after you’ve deployed a production application and need to determine why something has seemingly gone wrong and correct it. Whether the bug is the result of a subtle misstep in deployment or an incidental result of rare production data, you’ll be glad you weren’t without console interaction.

1.3.1 Console methods Interactive Merb also comes with a number of console methods, all of which are accessible through the object merb. These let you do things such as conveniently faking requests within interactive Merb. Below we use a helper method to retrieve a response body from a URL using the HTTP GET method on a fresh very flat application. > merb.get('/').body ˜ Params: {"action"=>"index", "controller"=>"my_very_flat_app"} ˜ {:after_filters_time=>1.6e-05, :before_filters_time=>2.0e-05, :action_time=>0.000229} => "hi"

Table 1.2 lists the methods available on the merb object along with their use.

From the Library of Shirong Chen

1.3

Interactive Merb

11

Table 1.2 merb console methods Method

Use

check_request_for_route

Returns the parameters of what route a request matches

close_sandbox!

Ends a sandboxed session

delete

Uses HTTP DELETE on a URL with optional parameters

dispatch_request

Dispatches a request mimicking its handling and the return of a controller

dispatch_to

Dispatches to a specific controller action, with optional parameters

fake_request

Returns a request composed of defaults and merged-in parameters

get

Uses HTTP GET to retrieve a URL

open_sandbox!

Starts a sandboxed session

post

Uses HTTP POST on a URL with optional parameters

put

Uses HTTP PUT on a URL with optional parameters

reload!

Reloads your Merb application code

request

Builds a request from a URL and the request environment

show_routes

Lists all compiled routes in a tabular fashion

trace_log!

Explicitly sets logger output to be flushed

url

Generates a URL given parameters

1.3.2 Sandboxing Interactive Merb is capable of sandboxing your activity, allowing you to mess around with database resources only to have all changes reverted when you exit the sandbox. This is extremely useful when you have fixture data (and for those who live dangerously, even production data) that you need to work with. Because we haven’t seen

From the Library of Shirong Chen

12

Chapter 1: Fundamentals

anything that involves databases yet, we’ll leave the following example for you to revisit at will: > User.count ˜ SELECT COUNT(*) FROM ‘users‘ => 1 > merb.open_sandbox! Loading development environment in sandbox (Merb 1.0.0) Any modifications you make will be rolled back on exit => [Merb::Orms::DataMapper] > User.all.destroy! ˜ DELETE FROM ‘users‘ => true > User.count ˜ SELECT COUNT(*) FROM ‘users‘ => 0 > merb.close_sandbox! Modifications have been rolled back => nil > User.count ˜ SELECT COUNT(*) FROM ‘users‘ => 1

1.4 Merb conﬁguration The config/ directory found in the root of a Merb application holds all the configuration files for your application. Some of these files, like init.rb, are always there. The others depend upon the demands of your application. Let’s take a look at the most typical configuration files that Merb files use and what’s inside each of them.

1.4.1 Init script The init script is the first thing that Merb runs. As we saw when moving up from the very flat to the flat layout, it provided us with a jump in agility during development through class reloads. The init script itself, though, serves many other purposes, including basic configuration, inclusion of dependencies, and the selection of a testing environment.

1.4.1.1 Gems and load path In the Merb world, gems are the preferred form of distributing plugins and libraries. Merb developers did not want to create yet another vendor lock-in-inducing plugin system. Instead, RubyGems was chosen since it’s already the standard for distributed packets of Ruby functionality and could work well with the Merb plugin infrastructure.

From the Library of Shirong Chen

1.4

Merb configuration

13

Doing things the Ruby way Merb developers strive to get things done the Ruby way, that is, in the way most idiomatically compatible with the Ruby language and community. The use of RubyGems to distribute plugins is just one example of this. Others, like the refusal to use Symbol#to_proc or Module#alias_method_chain, not only keep Merb understandable but give it performance advantages over Rails and other frameworks.

Additionally, the convenience of the gem-based system allows us to install specific gems within an application, in the directory gems/ in the application’s root directory. When the gems are loaded as dependencies, they are given preference over system-wide gems. The benefit of being able to install version-specific gems in your application is huge, allowing you to • Share your application code with other developers without worrying about having

different versions • Deploy your application without any need to install all the gem dependencies on

the production server If at some point you want to freeze a specific gem inside your Merb application, you can do so using the install directory -i flag with gem. Here we do this from inside a directory with a gem by issuing the following command: $ gem -i ˜/src/your_app/gems dm-geokit-1.0.0.gem

Note that gem also installs the gem’s listed dependencies into your application for you. You may want to pass in the flag --no-rdoc to save on the size of your application’s gem/ directory.

1.4.1.2 Dependencies Including gems as dependencies instead of directly requiring has been done primarily so that we can load application-installed gems if they exist. The dependency method also defers loading until after logging has been initiated. With this in mind, you should be able to use the method dependency just as if you were using require. If the string you pass in doesn’t refer to a gem, dependency will attempt to load it as a file via require. dependency 'dm-geokit' dependency 'geokit-core', '>= 0.9.0' dependency 'lib/support/string'

From the Library of Shirong Chen

14

Chapter 1: Fundamentals

You can also use the method dependencies to require a few dependencies at once instead of one per line. By passing in hashes, you specify gem version. dependencies "RedCloth", "merb_helpers" dependencies "RedCloth" => "3.0"

1.4.1.3 after_app_loads Inside init.rb, you’ll find a method taking a block called Merb::BootLoader.after_ app_loads. The boot loader evaluates this passed-in block after most of the application is loaded. This is useful if you need certain classes loaded before including a dependency or defining a constant within a module: dependency 'merb_admin' GeoKit::default_units = :miles

1.4.1.4 Template engine You have your choice of template engines when using Merb. In fact, you can use multiple template engines by embedding templates inside one another. Still, when it comes to the template merb-gen, the templates are generated for ERB. If you prefer that they be in Haml when possible, you can change the following lines in init.rb so that the method use_template_engine has the :haml parameter: use_template_engine :erb # use_template_engine :haml

1.4.1.5 Basic configuration Merb stores configuration settings inside the class Merb::Config. You can do this in two different ways, first by explicitly using the class methods Merb::Config.[] and Merb::Config.[]=: Merb::Config[:session_store] = 'memory' if Merb::Config[:verbose] Merb.logger.info "Above all be terse." end

or instead by passing a block into the method Merb::Config.use: Merb::Config.use do |c| c[:session_store] = 'cookie' end

1.4.1.6 ORM options Inside the init script we see the lines for the three most popular ORMs, or Object Relations Mapping libraries, that work with Merb. Enabling any one of them is as easy as uncommenting a line. Below we’ve enabled the DataMapper ORM.

From the Library of Shirong Chen

1.4

Merb configuration

15

# Uncomment for DataMapper ORM use_orm :datamapper # Uncomment for ActiveRecord ORM # use_orm :activerecord # Uncomment for Sequel ORM # use_orm :sequel

For more information on ORMs, please see Chapter 5 on models, which uses DataMapper and briefly covers the use of both ActiveRecord and Sequel.

1.4.1.7 Testing options Another thing the init.rb file handles is your choice of testing suite. By default, Merb uses RSpec, and we’ll go over how to use it later on. If, however, you want to use Test::Unit instead, that’s as easy as commenting out one line and uncommenting the other: # use_test :test_unit use_test :rspec

Note that to complete this switch you may also have to install the merb_test_unit gem if it hasn’t been installed already.

1.4.1.8 Inflector At the bottom of the Merb init script you’ll find details about how to customize the inflector. The inflector is used to take English words (really just nouns) and switch between their singular and plural forms. This may seem odd to include in an MVC framework, but its existence allows us a lot of ease in abstracting URLs and working with RESTful resources (REST stands for Representational State Transfer). That said, you may not end up using the inflector, but in case you do, it’s always there. You can test it in interactive Merb, simply by tacking the methods singular or plural onto strings of nouns: > "users".singular => "user" > "forum".plural => "forums"

If, however, you run into a word that is not being pluralized as you need it to be (let’s say, for example, you wanted the plural of forum to be fora), you would be able to use the init.rb file to assure this behavior by adding a line like this: Extlib::Inflection.word "forum", "fora"

From the Library of Shirong Chen

16

Chapter 1: Fundamentals

1.4.2 Environments Merb can standardly run in three different environments: development, testing, and production. Up until now we’ve run Merb only under development mode. You can run Merb in these other modes by specifying the environment after the -e flag with the merb command: $ merb -e production

Each of these modes runs slightly differently. These differences are defined in the files inside config/environments. For instance, inside config/environment/ development.rb, we find Merb.logger.info("Loaded DEVELOPMENT Environment...") Merb::Config.use { |c| c[:exception_details] = true c[:reload_templates] = true c[:reload_classes] = true c[:reload_time] = 0.5 c[:ignore_tampered_cookies] = true c[:log_auto_flush ] = true c[:log_level] = :debug c[:log_stream] = STDOUT c[:log_file] = nil # Or redirect logging into a file: # c[:log_file] = Merb.root / "log" / "development.log" }

This file uses the method Merb::Config.use, just as init.rb does, to set environmentspecific settings. You can also set other constants or whatever environment-specific variables you need in here. We’ve seen some of these configuration settings before. The settings reload_classes and reload_time define what a development environment is by setting application classes to reload periodically. The low log level as well as log auto-flushing also mean that in development mode your application will log everything and write it out as it comes. Let’s take a look at production.rb to make a comparison: Merb.logger.info("Loaded PRODUCTION Environment...") Merb::Config.use { |c| c[:exception_details] = false c[:reload_classes] = false c[:log_level] = :error

From the Library of Shirong Chen

1.4

Merb configuration

17

c[:log_file] = Merb.root / "log" / "production.log" # or redirect logger using IO handle # c[:log_stream] = STDOUT }

Note that exception details are off, and users of the site will not see backtraces if they run into an error. The reloading of classes is also off to save on performance. Finally, the log level has been pushed up to error, because we don’t want to be dealing with huge logs. The log file has been explicitly set, and by omission, log auto-flushing is off. The third environment configuration file, test.rb, is used only when running tests. Its environment configuration is decently empty, setting a configuration key :testing to true. Note that you are able to create your own environments as well as configuration files. To do so, just pass in the same name to the -e flag as the filename of your custom configuration. Here we check via interactive Merb that we’re running in the “staging” environment: $ merb -i -e staging > Merb.environment => "staging"

1.4.3 Router The Merb file config/router.rb defines the routes used by your application. We’ll cover this in detail in the next chapter, but if you need only the most basic setup, you can rely on the default routes created by the line default_routes

1.4.4 Logging By default, all Merb logs are stored in log/ in the Merb root directory. If you’re running Merb under a testing environment, then the log file will be named merb_test.log. Otherwise, it’ll be labeled based on the port number under which it’s running. Typically this means the log filename will be merb.4000.log. You can manually change the location of the log file by setting Merb::Config[:log_file]. This is typically done per the environment and by default results in the log production.log for a Merb application running in production mode. The other log settings that can also be altered as part of Merb::Config are log_level and log_auto_flush. Log level determines

From the Library of Shirong Chen

18

Chapter 1: Fundamentals

the minimal level for a log message to be recorded. Starting from the lowest, these levels are • Debug—intended for development-only logging used for debugging • Info—typically used for logging uncommon events so you know when they hap-

pened • Warn—best used to warn developers that a near-miss happened though no error

occurred • Error—occurs when a user experiences an error • Fatal—logs an error that has killed the server

You can set Merb::Config[:log_level] by using a symbol for any one of these. log_auto_flush, on the other hand, can be set to true or false and will determine whether the log buffer is automatically flushed out to the log file or not.

1.4.4.1 Using logging Throughout your Merb application you will have access to logging via the Merb.logger. When the logger receives a call to any of the log levels, it logs the string it is given as a parameter. Here are some examples of logger usage: Merb.logger.info "Insides of @current_user:" Merb.logger.info @current_user.inspect

If auto-flushing is off, you can manually flush the logs by either using the method flush or using the bang method variant of a log level: Merb.logger.warn! "Need this in the log file now!" Merb.logger.warn "User creation has failed." Merb.logger.flush

1.4.4.2 Viewing logs Unless your Merb application is running as a background process, the first place you see your logs is in the terminal you run it under. If, however, you’re in production mode, you could use the UNIX command tail to actively watch your logs. Here we stream log changes to the terminal by using the flag -f: $ tail -f log/merb.4000.log

If more than one server is running, you can use a wildcard to stream all the logs. Below we also use the v flag to identify which file has been modified. $ tail -vf log/*.log

From the Library of Shirong Chen

1.4

Merb configuration

19

1.4.5 Database When you use an ORM with Merb, it has to know how to access the database or databases you use in the different environments. We’ll go over ORMs more in depth later on, but for reference let’s take a look at how the file config/database.yml helps DataMapper connect. As the YAML files are broken down into three sections, one for each environment, and since each of these is virtually the same, we’ll look at only one of them: development: \&defaults # These are the settings for repository :default adapter: postgres database: sample_development username: the_user password: secrets host: localhost # Add more repositories # repositories: # repo1: # adapter: postgres # database: sample_development # username: the_user # password: secrets # host: localhost # repo2: # ...

Here, adapter specifies the type of database program you’re running (and incidentally the adapter DataMapper will have to use to communicate with it). The rest of the lines are pretty self-explanatory. However, if you access your development database without a password (don’t ever do such a thing on a production server!), you may wonder how to do it. It’s simple enough; just leave whitespace after password: and before the next line. Two-space indents YAML files are whitespace-sensitive so you’ll have to make sure that there are two spaces for every nested line. Among Ruby developers, this is also the standard way of indenting code. Though it’s not necessary with Ruby code, please, for everyone’s sake, abide by this rule.

The extra repository options commented after the host line are a powerful option. DataMapper allows you to access alternative databases through either more explicit

From the Library of Shirong Chen

20

Chapter 1: Fundamentals

method calls or by specifying when they apply in model files. You can add these extra repositories under repositories by starting each with a name by which to reference it. Last, on the first line you may have noticed the inclusion of &defaults. This allows us to use these settings as defaults in the other environments. To do this, we’ll use << along with a YAML dereferencer: production: <<: *defaults database: sample_production

Notice that any one of the settings can be overriden by defining it again after the inclusion of the default.

1.5 Understanding the Merb stack Merb is a modular web framework. This means that to use it you’ll have to be comfortable with the various gems that it pulls together. We’ll take a glance at each of these and cover fundamentals as they come up.

1.5.1 Extlib One of the most powerful aspects of programming in Ruby is the ability to open up classes and add in new behavior. In the wrong hands, though, this could lead to many disastrous effects, including the polluting of the Ruby core classes. Consequently, the developers of Merb (and DataMapper) have chosen to limit the number of so-called support classes and maintain them as a shared side project called Extlib. As an application developer, you’ll be glad they did this, because nobody wants the libraries or frameworks they use to crowd up core classes. Anyway, because there aren’t many additions, let’s take a look at Extlib and the classes it extends.

1.5.1.1 ObjectSpace • ObjectSpace.classes—returns a list of all defined classes

1.5.1.2 Class • cattr_reader, cattr_writer, cattr_accessor—create a unified class and in-

stance variable in either reader, writer, or accessor form • class_inheritable_reader, class_inheritable_writer, class_inheritable_accessor—create a class-level variable that is inherited by

subclasses in either reader, writer, or accessor form

From the Library of Shirong Chen

1.5

Understanding the Merb stack

21

1.5.1.3 Object • in?—returns true if the object is in the array (or the array formed by multiple parameters): 1.in?([1,2,3]) #=> true 1.in?(1,2,3) #=> true

• try_dup—returns a duplicated object if possible. This method is overridden in

non-dupe-able classes to return self. • meta_class—gives you easy access to an object’s singleton class to make metapro-

gramming painless

1.5.1.4 String • escape_regex and unescape_regex—allow you to escape or unescape regex

special characters in strings: "*?{}.".escape_regexp #=> "\\*\\?\\{\\}\\." "\\*\\?\\{\\}\\.".unescape_regexp #=> "*?{}."

• snake_case and camel_case—return a string in either snake or camel case. These

are often used to convert class names to filenames and back again: "FooBar".snake_case #=> "foo_bar" "foo_bar".camel_case #=> "FooBar"

• to_const_string and to_const_path—used to convert a constant name to a

standard path and back again: "merb/core_ext/string".to_const_string #=> "Merb::CoreExt:: String" "FooBar::Baz".to_const_path # => "foo_bar/baz"

• /—used to join strings as part of a file path (uses File.join): "merb"/"core_ext" #=> "merb/core_ext"

• String.translate, String.translations, and t—enable phrase translations

with replacements: spanish_translations = { "hello %s" => "hola %s", "world" => "mundo" } spanish_translations.each_pair{ |x,y| String. translations[x] = y } String.translate("world") #=> "mundo" "hello %s".t("merb") #=> "hola merb" "hello %s".t("world") #=> "hola mundo"

From the Library of Shirong Chen

22

Chapter 1: Fundamentals

1.5.1.5 Time • to_json—returns an ISO-8601-compatible rendering of the Time object’s properties • to_datetime—returns the DateTime equivalent

1.5.1.6 DateTime • to_time—returns the Time equivalent 1.5.1.7 Pathname • /—returns its receiver plus parameter as path fully expanded 1.5.1.8 blank? blank? is a method that has been added to numerous classes. In each of these, the blank? method may vary slightly. Here’s a list of the classes to which it’s been applied and what it tests: • Object—tests if the object is nil; if it is not, it tests first if it responds to empty?

and then whether it is empty or not • Numeric—always responds false • NilClass—always responds true • TrueClass—always responds false • FalseClass—always responds true • String—asks if the string less whitespace is empty?

1.5.1.9 Logger Extlib::Logger is the logger used by both Merb and DataMapper. The Merb log is specifically created in a boot loader we’ll see later on, but creating another logger for any of your Ruby applications is easy enough: logger = Extlib::Logger.new('/tmp/extliblog') logger.info "Log!!"

1.5.1.10 Mash Mash is a subclass of Hash designed specifically to allow you to interchangeably use strings or symbols as keys. With Merb, the real impetus for the creation of Mash was being able to refer to request parameters by both the string key they come with and the more Ruby-programmer-friendly symbolic key.

From the Library of Shirong Chen

1.5

Understanding the Merb stack

23

1.5.1.11 SimpleSet SimpleSet is a simulation of a set where each object is a key in a Hash. This class is used to manage callable actions in Merb controllers. 1.5.1.12 VirtualFile VirtualFile is really just StringIO with a path accessor. This allows Merb to use strings as inline templates. 1.5.1.13 LazyArray LazyArray is an Enumerable used by DataMapper as the parent class of DataMapper::Collection. Notably, LazyArray is designed to limit the loading of data sets to only when they are needed. As an application developer, you won’t need to know any of its methods directly, but knowing of their existence is definitely useful in understanding DataMapper’s beauty. 1.5.1.14 Hook Extlib::Hook is a module used in DataMapper that allows models to associate methods before or after the execution of other methods. It’s similar in use and style to the before and after filters we’ll find in Merb controllers but is built quite differently. 1.5.1.15 Pooling Extlib::Pooling is a module that allows for the sharing of similar resources with the same purpose. It is used by DataMapper to pool database connections.

1.5.2 Rack Rack is a Ruby web server interface that shuttles responses from web applications to actual web servers. The simplicity, modularity, and adaptability of Rack’s implementation are truly beautiful. Consequently, it is used not only by Merb but by numerous other Ruby web frameworks. These frameworks not only have the convenience of allowing programming to an interface but have also enjoyed the benefit of sharing the code that finally pushes responses to different web servers.

1.5.2.1 Adapter options Rack leaves the final decision of which web server to use up to the application developer. The default web server is Mongrel, but you can change this option by passing in an option to Merb on the command line after the -a or --adapter flag or by setting the

From the Library of Shirong Chen

24

Chapter 1: Fundamentals

config variable Merb::Config[:adapter]. Table 1.3 is a list of the adapters available through Rack and the Merb core. If you feel overwhelmed by the number of web server options, don’t worry: The default Mongrel server will most likely serve all your needs, at least at first.

1.5.2.2 How Rack works Rack works by passing around a Ruby object that responds to the call method. This call method needs to take one block parameter known as the environment and return an array of three values: status, headers, and body. This design choice makes Rack applications capable of being as small as lambda expressions, which intrinsically accept a call method. Here’s a “Hello World” example using just Rack and Mongrel: require 'rack' app = lamdba{[ 200, {"Content-Type" => "text/plain"}, ["Hello World"] ]} Rack::Handler::Mongrel.run(app, {:Host => "127.0.0.1", :Port => 4000})

Merb, however, uses Rack in a more complex way than this. Here is the abbreviated source from the Merb core that defines the Merb Rack application: class Merb::Rack::Application def call(env) begin controller = ::Merb::Dispatcher.handle(Merb::Request.new(env)) rescue Object => e return [500, {Merb::Const::CONTENT_TYPE => "text/html"}, e.message + "
" + e.backtrace.join("
")] end Merb.logger.info "\n\n" Merb.logger.flush controller.rack_response end end

You can see how the call method uses the passed-in Rack environment, which is just the incoming request from the web server, and then ultimately returns a response

From the Library of Shirong Chen

1.5

Understanding the Merb stack

25

Table 1.3 Available adapters Adapter

Key

Description

Mongrel

(default)

Mongrel is a web server created by Zed Shaw that boasts high performance.

Evented Mongrel

emongrel

Evented Mongrel is an enhancement of the Mongrel web server that handles concurrent requests with more consistent output by using EventMachine, a current IO library.

Swiftiplied Mongrel

swift

Swiftiplied Mongrel further enhances Evented Mongrel with an unconventional clustering proxy that eliminates significant overhead performance costs in setting up and tearing down connections.

Thin

thin

Thin is a web server that glues together the Mongrel server, EventMachine, and a builtin Rack interface.

Ebb

ebb

Ebb is a Ruby web server that uses the lightweight HTTP server library libebb that boasts performance similar to or better than that of Evented servers.

FastCGI

fcgi

FastCGI is another web interface that will plug into other web servers, including Abyss, Apache, Cherokee, LiteSpeed, Microsoft IIS, nginx, and the Sun Java System Web Server.

WEBrick

webrick

WEBrick is an older Ruby web server often used before Mongrel.

IRB

irb

Not actually a web server, the IRB adapter enables you to interactively run a Merb application.

Runner

runner

Also not an actual web server, but the Runner adapter is used to run tests.

From the Library of Shirong Chen

26

Chapter 1: Fundamentals

that Rack passes up to the web server for client distribution. Here are the steps it takes: 1. Create a request object using the Rack environment which contains everything from the incoming request. 2. Use the dispatcher to handle the newly created request object, resulting in a controller object. 3. Rescue any unhandled errors, returning a backtrace if needed. 4. Flush the log. 5. Return the Rack response crafted by the controller.

1.5.3 ORMs If your applicaton needs to store, retrieve, and manipulate data in complex ways, using a database is a no-brainer. But having to litter your code with SQL queries is painful. Fortunately, a number of ORMs enable you to interact with a database almost without ever having to write a SQL statement. In this book we’ll mostly focus on the DataMapper ORM, which is part of the standard Merb stack. Still, because there are options, the Merb core stays agnostic, and when it comes down to picking the ORM, it’s all up to you. Here are the three officially supported ORMs: • ActiveRecord is the Rails ORM. If you’re porting a Rails application to Merb, using

the ActiveRecord ORM will save you the trouble of having to modify your models. • DataMapper is a next-generation ActiveRecord-like ORM that innovates past its

predecessor. Some of its enhancements include identity maps, lazy loading, strategic eager loading, dirty property tracking, connection pooling, and a Ruby syntax that minimizes or eliminates the need to ever write SQL statements. • Sequel is a robust ORM offering thread safety, connection pooling, and a very

natural DSL for constructing database queries and table schemas. It has numerous well-supported adapters as well as a sophisticated feature set, including prepared statements, bound variables, master/slave configuration, and database sharding.

1.5.4 Plugins The Merb core stays away from dumping in everything you aren’t going to use just in case you’ll need it in another project. Instead, Merb emphasizes plugins as integral parts of the Merb stack. This keeps your application footprint small, but it also demands knowledge of what plugins exist. The most often used plugins are maintained by the

From the Library of Shirong Chen

1.6

An overview of Merb internals

27

Merb developers themselves and are included in the standard Merb stack. Less often used plugins are distributed by third parties.

1.6 An overview of Merb internals You don’t need to understand Merb internals for the work you’ll do as an application developer, but taking a look under the hood to understand how it all came together will help you use them better.

1.6.1 Boot loaders When Merb starts up, the first significant thing it does is run its boot loader. This makes it the best place to start understanding Merb internals. More important, casual knowledge of the startup routine of the Merb boot loader can change your perception of Merb from that of a black box that runs your application code to a framework you can pull apart and extend. Merb actually uses subclasses of the principal boot loader to define subroutines needed at boot-up. The class Merb::BootLoader thus serves two major functions. First, it is the parent class of all boot loaders. Second, at startup it goes through each of its subclasses and calls a class method named run. With this in mind, let’s take a look at each of the subclassed boot loaders in the order in which they are loaded. We’ll also include excerpts from their run methods. There’s no need to be overwhelmed by the code included (especially since externally defined variables appear). Instead, just let it simmer, and appreciate the fact that you can concretely trace things back to their source.

1.6.1.1 BootLoader::Logger The first boot loader to be loaded is the logger. We need it to come first so that we can log any issues that may occur during boot-up. Here’s the code from inside the run method of the logger boot loader: Merb.logger = Merb::Logger.new(Merb.log_file, Merb:: Config[:log_level], Merb::Config[:log_delimiter], Merb::Config[:log_auto_flush])

Note how the Merb::Config variables we saw earlier are used to initiate the logger. Merb.log_file may seem unfamiliar, but it’s really only a method that references Merb::Config['log_file'] or otherwise constructs a default log filename.

From the Library of Shirong Chen

28

Chapter 1: Fundamentals

1.6.1.2 BootLoader::DropPidFile When our application is run either as a daemon or as one server among a cluster, we’ll need to store its process ID, so that we can, among other things, kill it later using merb -k. The DropPidFile boot loader does this for us by storing our server’s process ID number in a file found in log/: Merb::Server.store_pid(Merb::Config[:port]) if Merb:: Config[:daemonize] || Merb::Config[:cluster]

This run method doesn’t reveal much of what goes on, but by default the pidfile is named based on the number of the port on which the server is running. So, for example, the standard pidfile can be found at log/merb.4000.pid. You can change this default by setting Merb::Config[:pid_file] directly within either your config file or an environment file.

1.6.1.3 BootLoader::Defaults Within the Merb default boot loader, some critical overrides are defined to make up for the inability of a number of browsers to use all the HTTP methods, particularly PUT and DELETE. This is particularly useful in building RESTful routes for resources. Note how the default boot loader overrides some requests to imitate the client being capable of all the HTTP methods: Merb::Request.http_method_overrides.concat([ proc { |c| c.params[:_method] }, proc { |c| c.env['HTTP_X_HTTP_METHOD_OVERRIDE'] } ])

1.6.1.4 BootLoader::BuildFramework As we saw in the config section, Merb allows us to designate alternative layouts for our applications. The BuildFramework boot loader gets this working: if File.exists?(Merb.root / "config" / "framework.rb") require Merb.root / "config" / "framework" elsif File.exists?(Merb.root / "framework.rb") require Merb.root / "framework" else Merb::BootLoader.default_framework end (Merb::Config[:framework] || {}).each do |name, path| path = Array(path) Merb.push_path(name, path.first, path.length == 2 ? path[1] : "**/*.rb") end

From the Library of Shirong Chen

1.6

An overview of Merb internals

29

Note how, in the final lines, the inclusion of a second parameter alters the default of '**/*.rb'. This string is known as a glob and is used to recursively search for Ruby files. Changing the glob affects what files are included. This may come in handy in framework definition, where we want to include only one file (set the glob to nil) or only files named in a particular fashion (for example, '*_controller.rb').

1.6.1.5 BootLoader::Dependencies This boot loader actually does a bit more than load dependencies. It loads the init file, loads the applicable environment configuration file, loads other dependencies you’ve included in the init or environment file, and then finally updates the logger with any changes you may have made. 1.6.1.6 BootLoader::MixinSession This adds in session functionality by including relevant mixins in both Merb:: Controller and Merb::Request. It’s critical that this happens so early because custom subclasses of SessionContainer and SessionStoreContainer may be created through a before_app_loads block: def self.run require 'merb-core/dispatch/session' Merb::Controller.send(:include, ::Merb::SessionMixin) Merb::Request.send(:include, ::Merb::SessionMixin::RequestMixin) end

1.6.1.7 BootLoader::BeforeAppHooks This boot loader can be used to set or define whatever you need before your application code gets loaded. Plugins often use this hook to include code. The boot loader works by calling all the before load callbacks created by before_app_loads blocks: Merb::BootLoader.before_load_callbacks.each { |x| x.call }

1.6.1.8 BootLoader::LoadClasses The LoadClasses boot loader loads all the nontemplate application code. It also records modification times for each file so that they can be used by the ReloadClasses boot loader. Since the code gets fairly complex, we’ll leave it to you to check the source yourself. 1.6.1.9 BootLoader::Templates This boot loader does nearly the same thing as the LoadClasses boot loader but for templates. Pulling from a template path, it inlines each of the templates for later use by the controllers:

From the Library of Shirong Chen

30

Chapter 1: Fundamentals

template_paths.each do |path| Merb::Template.inline_template(File.open(path)) end

1.6.1.10 BootLoader::MimeTypes Merb is capable of rendering responses with different MIME types. The MimeTypes boot loader registers the default MIME types and serves as a good example of how you can add your own MIME types in an after_app_loads block: Merb.add_mime_type(:all, nil, %w[*/*]) Merb.add_mime_type(:yaml, :to_yaml, %w[application/x-yaml text/yaml], :charset => "utf-8") Merb.add_mime_type(:text, :to_text, %w[text/plain], : charset => "utf-8") Merb.add_mime_type(:html, :to_html, %w[text/html application/xhtml+xml application/html], :charset => " utf-8") Merb.add_mime_type(:xml, :to_xml, %w[application/xml text/xml application/x-xml], {:charset => "utf-8"}, 0.9998) Merb.add_mime_type(:js, :to_json, %w[text/javascript application/javascript application/x-javascript], : charset => "utf-8") Merb.add_mime_type(:json, :to_json, %w[application/json text/x-json], :charset => "utf-8")

Note that the addition of each MIME type takes an identifying symbol, a transformation method or nil, a list of Accept header values to associate with, and the response header to be sent out.

1.6.1.11 BootLoader::Cookies This boot loader mixes in cookie functionality in both controllers and requests: require 'merb-core/dispatch/cookies' Merb::Controller.send(:include, Merb::CookiesMixin) Merb::Request.send(:include, Merb::CookiesMixin::RequestMixin)

1.6.1.12 BootLoader::SetupSession This steps up the defined session containers and default values. Once again, here it’s best to take a look into the source code yourself if your interest is piqued. 1.6.1.13 BootLoader::AfterAppLoads Analogous to the before_app_loads boot loader, the after_app_loads boot loader calls all the callbacks collected from after_app_loads blocks: Merb::BootLoader.after_load_callbacks.each {|x| x.call }

From the Library of Shirong Chen

1.6

An overview of Merb internals

31

1.6.1.14 BootLoader::SetupStubClasses This boot loader creates stubbed classes for Merb::Application and Merb:: Exceptions. This is important in making sure exception controllers are available even in very flat applications: unless defined?(Exceptions) Object.class_eval <<-RUBY class Application < Merb::Controller end class Exceptions < Application end RUBY end

1.6.1.15 BootLoader::ChooseAdapter This sets the Merb Rack adapter to be used. By this time, if a value was passed in on the command line, it has been used to set Merb::Config[:adapter]: Merb.adapter = Merb::Rack::Adapter.get(Merb::Config[:adapter])

1.6.1.16 BootLoader::StartWorkerThread This starts a worker thread that will run deferred blocks as your controllers demand: Merb::Worker.new

1.6.1.17 BootLoader::RackUpApplication Here’s the boot loader that sets up Rack. You may want to take your time with it. require 'rack' if File.exists?(Merb.dir_for(:config) / "rack.rb") Merb::Config[:rackup] ||= Merb.dir_for(:config) / "rack.rb" end if Merb::Config[:rackup] rackup_code = File.read(Merb::Config[:rackup]) Merb::Config[:app] = eval("::Rack::Builder.new {( #{rackup_code} \n )}.to_app", TOPLEVEL_BINDING, Merb::Config[:rackup]) else Merb::Config[:app] = ::Rack::Builder.new { if prefix = ::Merb::Config[:path_prefix] use Merb::Rack::PathPrefix, prefix end

From the Library of Shirong Chen

32

Chapter 1: Fundamentals

use Merb::Rack::Static, Merb.dir_for(:public) run Merb::Rack::Application.new }.to_app end

Note that it looks for a file named rack.rb, which we saw when we covered configuration. It then uses the code from that file as part of an eval statement that initializes Rack::Builder. If there is no rack.rb, the boot loader uses the defaults we saw earlier.

1.6.1.18 BootLoader::ReloadClasses The ReloadClasses boot loader sets up a timed executor to reload classes as needed. You can change the reload time or turn it off completely in your configuration files. The standardly generated environment files set Merb::Config[:reload_classes] to true only in the development environment. Here’s the source from the boot loader that makes use of these configuration variables: return unless Merb::Config[:reload_classes] TimedExecutor.every(Merb::Config[:reload_time] || 0.5) do reload end

1.6.1.19 BootLoader::ReloadTemplates Templates are also set to be reloaded by the final boot loader. However, as the code below indicates, you turn this off either by setting Merb::Config[:reload_templates] or by not using the development environment. unless Merb::Config.key?(:reload_templates) Merb::Config[:reload_templates] = (Merb.environment == "development") end

1.6.2 Server A Merb server is a system process that responds to requests on a given port defined in configuration. You can also start clusters of Merb servers, but each runs on its own port and as its own process. The Merb::Server class offers a number of class methods to manage running servers, but the application developer typically accesses these via the merb command. For example, the following command kills a Merb server running on port 4000: $ merb -k 4000

From the Library of Shirong Chen

1.6

An overview of Merb internals

33

Using other Merb::Server class methods under the hood, we can start a cluster of ten daemonized Merb servers and then kill each one of them: $ merb -d -c 10 $ merb -k all

To see exactly how Merb makes these commands work, you can check out the source code for the files lib/merb-core.rb and lib/merb-core/server.rb inside the Merb core.

1.6.3 Requests The class Merb::Request describes the requests a Merb server receives. Each of these requests will exist for the duration of the creation of a response. We’ll see plenty of these in the next couple of chapters.

1.6.4 Router The Merb router stores routes that map requests to controller actions. We’ll go over this extensively in Chapter 2.

1.6.5 Dispatcher The Merb dispatcher is responsible for dispatching incoming requests from a work queue it maintains. Merb is thread-safe, meaning it’s capable of better performance through multithreading, but if the libraries you use make thread safety an issue, the dispatcher is capable of locking requests using mutual exclusion. You can do this in your configuration file as follows: Merb::Config[:use_mutex]

Alternatively, you can pass in “on” or “off” to the -X flag with the merb command: $ merb -X on

Most of the methods within lib/merb-core/dispatch/dispatcher.rb, notably handle and redirect, are actually part of Merb::Request but serve to dispatch requests from the work queue. As an application developer, you’ll use only the redirect method; however, in the chapter on controllers (Chapter 3) we’ll demonstrate the path by which a request comes to be handled by using Merb::Request.handle.

From the Library of Shirong Chen

34

Chapter 1: Fundamentals

1.6.6 Controllers Merb controllers are the classes that do the actual handling of requests and produce the responses to send out. Since we talk extensively about them in Chapter 3, we’ll defer our discussion until then.

1.6.7 Sessions Sessions allow for the stringing of otherwise independent requests into a user-specific interaction. We’ll use them heavily in crafting responses as well as in filtering access to controller actions. As we previously saw, Merb is capable of storing sessions in a number of different ways; thus much of the source is dedicated just to this. Fundamentally, though, session functionality is abstracted away from its means of storage and then mixed into both the controller and request classes.

1.6.8 Worker The Merb worker allows us to run code outside the standard request-to-response cycle. This is perfect for time-intensive tasks that would otherwise delay the sending of a response. We’ll go over the use of workers in more depth in Chapter 3, but the following excerpt from the merb-core source demystifies workers as containers for threads that maintain work queues: module Merb class Worker attr_accessor :thread def initialize @thread = Thread.new { loop { process_queue } } end def process_queue begin while blk = Merb::Dispatcher.work_queue.pop Thread.pass blk.call end # ... end end end

From the Library of Shirong Chen

1.7

Conclusion

35

1.7 Conclusion Merb’s architecture emphasizes modularity, both internally and through its plugin interface. Throughout this book we will encounter aspects of this design decision while examining how it has shaped the tools around it. Application developers should be pleased by Merb’s versatility, as it can provide them with as little or as much as they need. Along with the prospect of custom stacks, a plethora of possibilities are opened, making Merb suitable for whatever a web application may demand.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 2

Routing

If you’re new to MVC web frameworks in general, you may at first expect that each request path would correlate with a particular file of code. This would be similar to the way static assets and preprocessed scripts are most often served. However, organizing our application code by request path typically leads to a sprawl of files and immense challenges to sensible refactoring. Merb refuses to let this happen by adhering to the MVC paradigm and separating code by its abstract purpose. The only hitch, of course, is that we now need an application router to guide incoming requests to the code meant to respond to it. If this at first sounds a bit complicated, don’t worry. The Merb router is not only sophisticated enough to parse and direct requests based on complex conditions, it’s also easy to use and understand. In fact, if you’ve used the routers of other frameworks, chances are you’ll find Merb’s route definitions far cleaner and better organized than anything you’ve seen in the past. As an MVC framework, Merb routes each of its requests to a controller. More specifically, each request is routed to a particular controller method that in this context is called an action and is responsible for producing a response. Constructing Merb routes for use by the router is not an exercise of tediously mapping URLs to controller actions, however. Instead, we are able to match particular conditions in a nested fashion, consolidating the definition of related routes. Merb also sports the ability to parse conditions using regular expressions and is consequently incredibly versatile when you need it to be. Nonetheless, in many cases the best way of accomplishing routing is often the simplest, and as we’ll see with Merb’s resource routing, a single line in the router can set up all the routes you need to standardly interact with a resource. This routing is accomplished in adherence to REST standards (aka RESTfully) and makes it possible to sensibly double the use of your routes as a basis for web services. 37 From the Library of Shirong Chen

38

Chapter 2: Routing

Once defined, a list of routes plays a part not only in the recognition of request URLs, but also in their generation. This is because Merb can inversely map parameters to a URL, and thus it enables us to abstractly generate URLs needed for redirects, links, and elsewhere. This is important in both controllers and views as we’ll see in the chapters on those topics, but we’ll also briefly touch upon them at the end of this chapter. With all this is mind, let’s take a look at the internals of the Merb router to see how it works. You don’t need to remember all the classes we’ll describe from within the core, but again, familiarity with them will also bring substantial comfort, so a peek is well worth your time.

2.1 How Merb routing works Merb routing works by first matching conditions against a request’s method and path. It then looks to associate matches with a parameters hash, which specifies the relevant controller and action as well as additional query parameters that may be needed. Each of these pairings of conditions with parameters is called a route and is stored in an ordered list generated at boot-up. As we look at the classes that define routes, we find that each route is created as an instance of Merb::Router::Route and, if active, can be found as an element in the array Merb::Router.routes. If we start up interactive Merb outside any project, we’ll find the routes to be empty: > Merb::Router.routes => []

There is another class that serves as a precursor to routes, called a behavior. Router behaviors make it possible for us to specify routes in a nested manner that grow toward completeness through the layering of both route conditions and parameters. As an application developer, you do not need to know of the existence of route behaviors even though you’ll be interacting with them unknowingly. On the other hand, for those of you destined to become plugin developers or possibly core contributors, it’ll serve you well to know that route behaviors are instances of Merb::Router::Behavior and that each block inside a router configuration is evaluated within the context of a parent behavior. Nested blocks imply nested behaviors, and these are compiled down to a flat ordered list at boot-up in the previously mentioned array Merb::Router.routes. From either perspective, what matters most when specifying routes is an understanding of the two elements that make up each complete route. These are the route conditions and the route parameters. Let’s take a look at each before we put them to use.

From the Library of Shirong Chen

2.1

How Merb routing works

39

2.1.1 Route conditions Route conditions are what the Merb router matches incoming requests against. In general, there are two minimal conditions a route must have: a path and a method. Paths are specified using strings, whereas method matching may use strings, symbols, or arrays. Getting the most out of route regular expressions You can also use regular expressions when setting route conditions. Doing so, however, may make the router incapable of creating an inverse mapping of the route, which prevents it from using the route statement for URL generation. The more modest alternative that also allows for route generation is to use regular expressions against the symbolic path segments that we’ll talk about soon. Merb also translates these regular expression matches into additional constraints for your routes, so overall, using them can be the best option.

2.1.1.1 Route method Sometimes requests going to the same path have different intents. For example, a request for /users/1 may sometimes be used to show the profile of a user, but at other times the request may include data used to update the user’s details. However, instead of guessing what the intent of the request is, based on what data is received, it is standard to rely on the request’s HTTP method as the definitive indicator of intent. A number of HTTP methods exist, but four in particular are used with Merb. These are GET, POST, PUT, and DELETE. In the context of REST, these methods are often called verbs. RESTfully speaking, each one plays a particular role well defined by both the W3C HT TP standards and RESTful intent. However, if you feel the need to set up routes that deviate from these standards, you have the freedom to do so. Just be warned: Using HTTP methods and their RESTful interpretations is more and more becoming a shared best practice, and going against it may only serve to complicate your application for both internal developers as well as web service consumers. Here’s a list of the four most important HTTP methods: • GET—the most common HTTP verb, used to request data without explicitly af-

fecting it • POST—the default verb for form submission, used to push arbitrary data onto the

server • PUT—used when data sent is intended to replace the existing data corresponding

with a particular URL • DELETE—used to request the deletion of data related to a particular URL

From the Library of Shirong Chen

40

Chapter 2: Routing

The case of the missing HTTP methods Note that some browsers do not produce all four of these HTTP verbs and are limited to only GET and POST. To make up for this and imitate full HTTP method compatibility, Merb uses both X-HTTP_METHOD_OVERRIDE and a hidden query parameter to enable the translation of particular POSTs into PUTs or DELETEs. In Chapter 1 we saw the boot loader that enabled these overrides. The point is, you won’t have to worry about the details of method overriding as an application developer. Merb will take care of it for you.

In the conditions hash of a route, a route method is typically indicated by use of one of the symbols :get, :post, :put, or :delete. You may instead use strings or regular expressions, but symbols are preferred. In the following code, we begin to define a route by specifying a method: Merb::Router.prepare do match(:method => :get) do # ... end end

2.1.1.2 Route path The more recognizable part of an HTTP request is its path. This includes everything after the domain of the request and before the query string. For example, the path of the request URL http://merbdeveloper.com/users/1 is /users/1. What about the query string? An HTTP path does not include the query string, which is everything that follows the first question mark in a URL. In general, query strings are used to pass in request parameters that may be used by the application code. For example, a request to /users?first_name=Foy may pull up a list of users with that first name only. Strictly speaking, though, the request parameters found in a query string are used only to drill down to the specifics of the response desired and do not play an intrinsic role in route definition. Nonetheless, Merb routes do allow you to translate parts of a route path into request parameters. We’ll see this often with resources routes. For example, /users/foysavas may, in the process of getting routed, translate the second segment into the value of params[:username].

Route paths are segmented by Merb with the standard slash separator or, as needed, by the end of symbolic segments. The two types of segments are literal and symbolic.

From the Library of Shirong Chen

2.1

How Merb routing works

41

Table 2.1 Route paths Route Path

Matching Path

Extracted Parameters

/users

/users

/users/:id

/users/1

:id => 1

/posts/:year_:month

/posts/08/08

:year => 08, :month => 08

Literal segments match literally against themselves. For instance, /users/new matches the first segment of the route path '/users/:action', which is '/users'. Symbolic segments, on the other hand, match any string that does not include a slash separator. For example, in the last example, the new at the end is matched against :action. As a side note, since :action has a special meaning among symbols, this route path automatically associates itself with the controller action named new in practice. To whet your appetite, Table 2.1 shows a few more examples of route paths and their interpretations by the router. When it comes time to write out our route path conditions, they will appear either first in match statements or as values to the key path: Merb::Router.prepare do match("/users") do # ... end match(:path => "/session") do # ... end end

2.1.1.3 Other conditions There are a few other conditions we can match against in route conditions. Two of these are protocol and domain, and they allow us, for instance, to match requests coming from secure HTTP or requested from a particular subdomain: Merb::Router.prepare do match(:protocol => 'https', :domain => 'secure.merbdeveloper.com') do # ... end end

From the Library of Shirong Chen

42

Chapter 2: Routing

Other conditions aside from path, protocol, domain, and method are assumed to be for symbolic segments and can be used to add constraints to segments through regular expressions. Here, the ID of a path matches only if it’s a string of digits: Merb::Router.prepare do match("/users/:id", :id => %r{ˆ[0-9]+}) do # ... end end

2.1.2 Route parameters Route parameters specify where the route should go. They are described as hashes where a few keys are interpreted separately, and all the rest are considered part of the parameters of the request itself. Here’s a list of the special keys: • controller—the controller to which the request will be routed in snake case • action—the action to which the request will be routed; defaults to “index” • format—the format in which the response should be given

All other route parameters do not have special meaning and are passed on as parameters, appearing with or, if necessary, overriding any parameters from elsewhere in the request. Here’s an example that uses both the special and nonspecial parameters: Merb::Router.prepare do match('/:controller/:action/:id'). to(:controller => controller, :action => :action, :id => id) end

One thing to note about this example is that all of the route parameters are redundant, as the Merb router translates symbolic segments into route parameters automatically.

What’s with this word parameter? You may be feeling the pain from this wildly overloaded word parameter. To clarify, there are two types of parameters within the context of a request plus the more general use of the word in Ruby:

• Route parameters---parameters that define where a request should be directed, or are inversely used to abstractly generate a URL. For example, a line such as to(:controller => 'users', action => 'new') inside router.rb uses router parameters within the to.

From the Library of Shirong Chen

2.2

Router configuration

43

• Request parameters---the collective data parameters of a request. These include the parameters found in a query string or as part of post data, as well as the nonspecial route parameters Merb merges in. These are all accessible from either the controller or the view as part of the mash params.

• (Method) parameters---our veritable friends that serve as data passed into a method.

2.2 Router conﬁguration Though we’ve seen some examples, up until now we’ve spoken only conceptually of routes, so it’s time to create our own configurations and learn about all the available methods. Routes are specified within a configuration block passed to the router for interpretation. Depending on the layout of your application, this configuration block may be in different locations, but it’s important that it gets loaded at boot-up so the routes can be compiled.

2.2.1 The router file In a standard Merb layout, routes are specified in the file config/router.rb. Single-file Merb applications include a router configuration near the top of the file. Flat layouts put it in application.rb. With either of these, router configuration code looks just the same and works through the passing of a block to the class method Merb::Router.prepare. Here’s the content from a standardly generated config/router.rb file less comments: Merb.logger.info("Compiling routes...") Merb::Router.prepare do default_routes end

The first line, of course, is just a log message and is not critical to our routes. The next class method is the one we previously referenced, and in the default case of a generated standard application it has only default_routes. We’ll get into what this does soon.

2.2.2 The prepare block The prepare block works by evaluating each line in the context of a route behavior. Remember, route behaviors are basically nestable and are not necessarily complete

From the Library of Shirong Chen

44

Chapter 2: Routing

precursors to routes. For instance, the root behavior for the prepare block is internally defined as Behavior.new.defaults(:action => "index")

All deeper route behaviors are based on the behavior created by the method before the nesting of a block. This is demonstrated by the following prepare block: Merb::Router.prepare do to(:controller => 'home') do match('/') match('/preview').to(:action => :preview) end end

The two match lines are evaluted within the context of a new child behavior where the following route parameters have been set: :controller => 'home', :action => 'index'

Note that the second match statement overrides the action of the parent behavior, whereas the first relies on its parent entirely to specify its route parameters.

2.2.3 Route order All behaviors are compiled down into a flat list on boot-up, and when the router is used to recognize or generate a URL, it’ll work with the first possible route it finds. This often trips up first-timers, especially via the line default_routes: Merb::Router.prepare do default_routes match('/users/:id').action(:action => 'show') end

In this example, the default_routes will always take precedence, and therefore the match on the second line will never work. Be sure to pay attention to the order of your routes to avoid this problem.

2.2.4 Adding routes later on Typically, as an application developer you won’t need to add routes outside the prepare block, but it is still possible. To do this, you can use the two class methods

From the Library of Shirong Chen

2.3

Checking routes

45

Merb::Router.append and Merb::Router.prepend. Both of these work exactly like

the prepare block but insert their routes before or after all the others: Merb::Router.append do match('/info').to(:controller => 'info') end

2.3 Checking routes Sometimes you’ll want to check the routes of your application to make sure requests are routed properly. There are a number of ways to do this. So that you can use these methods to test the various router configurations we describe later and the router configurations of your own applications, we’ll describe them here. For all of this section’s examples we’ll use a standard Merb application with the following routes defined in config/router.rb: Merb::Router.prepare do # RESTful routes resources :posts # This is the default route for /:controller/:action/:id # This is fine for most cases. If you're heavily using resource-based # routes, you may want to comment/remove this line to prevent # clients from calling your create or destroy actions with a GET default_routes # Change this for your home page to be available at / match('/').to(:controller => 'whatever', :action =>'index') end

2.3.1 Listing routes Getting a simple list of the compiled routes can do wonders in determining why a request has gone astray. We’ll do this first using interactive Merb and then using a rake task.

2.3.1.1 Using interactive Merb To list routes in interactive Merb, simply start up the application and issue the command Merb::Router.route. Here we pull up a list of the routes in interactive Merb using the previously defined routes: > pp Merb::Router.routes [/posts(/index)(.:format), /posts(.:format), /posts/new(.:format),

From the Library of Shirong Chen

46

Chapter 2: Routing

/posts/:id(.:format), /posts/:id/edit(.:format), /posts/:id/delete(.:format), /posts/:id(.:format), /posts/:id(.:format), /:controller(/:action(/:id))(.:format), /] => nil

The first eight come from the resources route and are perfect examples of how effective resources routing can be in producing the routes you need. These routes come first because resources :posts does, too. Following those eight routes is the default_routes route. Notice that it translates to only one route, but given its complexity and versatility it has kept its name. Finally, the last route, the single /, matches a request for the root or empty path. Each of these items in the routes array appears as the path string above. However, don’t let that deceive you, since they’re all full routes that you can play around with. Below, we interact with the conditions and parameters for the default_routes route. > Merb::Router.routes[8].conditions => {:path=>/ˆ\/([ˆ\/.,;?]+)(?:\/([ˆ\/.,;?]+) (?:\/([ˆ\/.,;?]+))?)?(?:\.([ˆ\/.,;?]+))?$/} > Merb::Router.routes[8].params => {:controller=>"(path1)", :format=>"(path4)", :action=> "(path2 || \"index\")", :id=>"(path3)"}

As we’ll learn shortly, routes also come with names. These are either selected by you or they default to the name “default.” Below we use interactive Merb to list the named routes for us. > pp Merb::Router.named_routes {:new_post=>/posts/new(.:format), :posts=>/posts(/index)(.:format), :default=>/:controller(/:action(/:id))(.:format), :edit_post=>/posts/:id/edit(.:format), :delete_post=>/posts/:id/delete(.:format), :post=>/posts/:id(.:format)} => nil

Nearly all of these are for the resources route that was specified. Note that the inflector has been used to create these names, thus allowing us to naturally generate URLs for the various RESTful interactions. Also of importance is the precedence of the default_routes route over the specified root route. The former has become the route attached to the default name.

From the Library of Shirong Chen

2.3

Checking routes

47

Alternatively we can use the convenience method merb.show_routes to display all the routes in a significantly more verbose yet less interactive way. Here we pull up the same routes using this method: > merb.show_routes ==== Named routes Helper : new_post HTTP method: GET Route : /posts/new(.:format) Params : {:controller=>"\"posts\"", :format=>"(path1)", :action=>"\"new\""} Helper : posts HTTP method: GET Route : /posts(/index)(.:format) Params : {:controller=>"\"posts\"", :format=>"(path1)", :action=>"\"index\""} Helper : default HTTP method: GET Route : /:controller(/:action(/:id))(.:format) Params : {:controller=>"(path1)", :format=>"(path4)", :action=>"(path2 || \"index\")", :id=>"(path3)"} Helper : edit_post HTTP method: GET Route : /posts/:id/edit(.:format) Params : {:controller=>"\"posts\"", :format=>"(path2)", :action=>"\"edit\"", :id=>"(path1)"} Helper : delete_post HTTP method: GET Route : /posts/:id/delete(.:format) Params : {:controller=>"\"posts\"", :format=>"(path2)", :action=>"\"delete\"", :id=>"(path1)"} Helper : post HTTP method: GET Route : /posts/:id(.:format) Params : {:controller=>"\"posts\"", :format=>"(path2)", :action=>"\"show\"", :id=>"(path1)"} ==== Anonymous routes HTTP method: POST Route : /posts(.:format) Params : {:controller=>"\"posts\"", :format=>"(path1)", :action=>"\"create\""}

From the Library of Shirong Chen

48

Chapter 2: Routing

HTTP method: PUT Route : /posts/:id(.:format) Params : {:controller=>"\"posts\"", :format=>"(path2)", :action=>"\"update\"", :id=>"(path1)"} HTTP method: DELETE Route : /posts/:id(.:format) Params : {:controller=>"\"posts\"", :format=>"(path2)", :action=>"\"destroy\"", :id=>"(path1)"} HTTP method: GET Route : / Params : {:controller=>"\"whatever\"", :action=>"\"index\""} => nil

In this output, Helper signifies the name that should be used when we look to generate the URL. If you take a look at the penultimate and antepenultimate routes, it’s clear why two routes have appeared previously with the exact same path: One route is for PUT requests, which go to the update action, and the other is for DELETE requests, which go to the destroy action.

2.3.1.2 Using the audit routes rake task Standard applications are generated with a rake task that lists all routes for us without our having to use interactive Merb. To do this we can step into the Merb application’s root directory and issue the following command: $ rake audit:routes

Given the routes that were previously defined, the following routes are displayed: Named Routes delete_post: /posts/:id/delete(.:format) posts: /posts(/index)(.:format) edit_post: /posts/:id/edit(.:format) default: /:controller(/:action(/:id))(.:format) post: /posts/:id(.:format) new_post: /posts/new(.:format) Anonymous Routes /posts(.:format) /posts/:id(.:format) /posts/:id(.:format) /

From the Library of Shirong Chen

2.3

Checking routes

49

2.3.2 Trying the router Sometimes the only way to figure out what’s going on is to ask the router directly. Here we use interactive Merb to check both URL recognition and generation.

2.3.2.1 For URL recognition Using the Merb convenience methods, we can first put together a fake request and then see where the route will take it. The method merb.fake_request makes it easy for us to put together a request by just overriding default values. Here are the default settings that make up a merb.fake_request: > pp Merb::Test::RequestHelper::FakeRequest::DEFAULT_ENV {"SERVER_NAME"=>"localhost", "PATH_INFO"=>"/", "HTTP_ACCEPT_ENCODING"=>"gzip,deflate", "HTTP_USER_AGENT"=> "Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.8.0.1) Gecko/20060214 Camino/1.0", "SCRIPT_NAME"=>"/", "SERVER_PROTOCOL"=>"HTTP/1.1", "HTTP_CACHE_CONTROL"=>"max-age=0", "HTTP_ACCEPT_LANGUAGE"=> "en,ja;q=0.9,fr;q=0.9,de;q=0.8,es;q=0.7,it;q=0.7,nl; q=0.6,sv;q=0.5,nb;q=0.5,da;q=0.4,fi;q=0.3,pt;q=0.3,zh -Hans;q=0.2,zh-Hant;q=0.1,ko;q=0.1", "HTTP_HOST"=>"localhost", "REMOTE_ADDR"=>"127.0.0.1", "SERVER_SOFTWARE"=>"Mongrel 1.1", "HTTP_KEEP_ALIVE"=>"300", "HTTP_REFERER"=>"http://localhost/", "HTTP_ACCEPT_CHARSET"=>"ISO-8859-1,utf-8;q=0.7,*;q=0.7", "HTTP_VERSION"=>"HTTP/1.1", "REQUEST_URI"=>"/", "SERVER_PORT"=>"80", "GATEWAY_INTERFACE"=>"CGI/1.2", "HTTP_ACCEPT"=> "text/xml,application/xml,application/xhtml+xml,text/ html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5", "HTTP_CONNECTION"=>"keep-alive", "REQUEST_METHOD"=>"GET"} => nil

We can override the settings by passing in parameters. With the following, we modify the default fake request so as to imitate the deletion of a post: > fr = merb.fake_request('REQUEST_PATH'=>'/posts/1',' REQUEST_METHOD'=>'DELETE')

From the Library of Shirong Chen

50

Chapter 2: Routing

With our fake request ready, we can now use another convenience method to check if it routes to where it should. This method is merb.check_request_for_route and takes a request (fake or not) as its sole parameter: > merb.check_request_for_route(fr) => {:controller=>"posts", :format=>nil, :action=>"destroy", :id=>"1"}

The hash returned says that the request does in fact route to the destroy action of the posts controllers, so everything is in order.

2.3.2.2 For URL generation We can also test the generation of routes using another convenience method, merb.url. It takes a route name plus route parameters. Leaving out the route name sets it to default. Below we test the generation of the URL for editing the first post and then for an anonymous default route. > merb.url(:edit_post,:id => 1) => "/posts/1/edit" > merb.url(:controller => 'home', :action => 'login') => "/home/login"

2.4 Match rules Match rules are the basis for defining all route definitions. Let’s explore the various possibilities.

2.4.1 Literal matching Literal matching is quite simple. Using the route behavior method match within the block given to Merb::Router.prepare, we can match against literal strings: Merb::Router.prepare do match('/examples/routes') end

You can also nest literal match statements by passing in blocks. The following example demonstrates the same match as before: Merb::Router.prepare do match('/examples') do match('/routes') end end

From the Library of Shirong Chen

2.4

Match rules

51

Literal matches occur only if the string matches the entirety of the request path. For example, if a request comes in with the path /examples/controllers', it will not match against '/examples'. The exception, of course, is if a nested match completes the literal path. Remember that the route behaviors listed in the route are compiled before use, so nested literal matches are concatenated in their final form. Finally, an uncommon alternative to simply passing in the literal string is to instead pass in a hash with a value on the key :path. We provide this example so that you may recognize such usage if you spot it: Merb::Router.prepare do match(:path => '/examples') end

2.4.2 Symbolic matches Symbolic matches use symbols to more abstractly match request paths and associate these matches with parameters. These symbols appear as substrings within match path strings and can have additional rules set upon them using regular expressions. By default, a symbol matches all alphanumeric characters, the dash, and the underscore in a nongreedy fashion. Below is a simple example of a match rule that automatically sets the controller and action. Note that the colon is not allowed in URL paths, so there’s no need to worry about ambiguity. Merb::Router.prepare do match('/:controller/:action') end

Overall, the use of symbolic segments effectively extends the matches in three ways. Let’s go over these individually.

2.4.2.1 Automatic parameters Using symbolic match, we can tersely specify both route conditions and parameters. This works by mapping each symbolic match to an equivalent route parameter. Below, we redundantly route a symbolic match to where it was going even without the to statement. Merb::Router.prepare do match('/:controller').to(:controller => controller) end

From the Library of Shirong Chen

52

Chapter 2: Routing

2.4.2.2 Flexible segmentation Symbolic matches allow us to segment routes without relying on slash separators. Below we pull out a year, month, and day separated by dashes. Merb::Router.prepare do match('/dates/:year-:month-:day').to(:controller => 'dates') end

This match rule matches and segments request paths that look like this: /dates/2008-10-11 /dates/sorry-try-harder

In both of these examples, the three symbolic segments are translated into route parameters under the names :year, :month, and :day.

2.4.2.3 Segment-specific regular expressions We just saw an example where the match rule ended up matching possibly unwanted segments and translated them into route parameters. We can set further limits on specific segments by using regular expressions, which are compatible with both route recognition and generation and should be used when possible. Here we limit the previous example so that only strings of digits are allowed: Merb::Router.prepare do match('/dates/:year-:month-:day').to( :controller => 'dates', :year => /\d+/, :month => /\d{1,2}/, :day => /\d{1,2}/ ) end

2.4.3 Optional matches Using parentheses, we can tell the router that certain parts of a match are optional. This can significantly lessen the number of rules we need to write. We’ve seen this already with the case of the so-called default_routes, which are actually defined with just one match but using a number of parentheses: match("/:controller(/:action(/:id))(.:format)")

Note that some of the parentheticals are embedded within other parentheticals. The following routes match the preceding match rule: /users /posts/delete

From the Library of Shirong Chen

2.4

Match rules

53

/projects/edit/3 /groups.xml /users/new.txt /posts/update/6

2.4.4 Full regular expressions Though it’s not advisable because it may leave you unable to generate URLs from route parameters, you can directly use a regular expression to match the full path of a request: Merb::Router.prepare do match(%r[/account/([a-z]{4,6})]).to(:controller => "account", :action => "show", :id => "[1]") end

Using interactive Merb on an application where this is the only route, we can confirm that though the route is recognized and mapped to parameters, it cannot inversely be generated by those parameters: > merb.check_request_for_route(merb.fake_request( 'REQUEST_PATH'=>'/account/abcd')) => {:controller=>"account", :action=>"show", :id=>"abcd"} > merb.url(:controller => 'account', :action => 'show', : id => 'abcd') Merb::Router::GenerationError: Named route not found: default

2.4.5 Deferred routes Deferred routes allow you to incorporate more complex logic into your routes. Again, though, this comes at the cost of being unable to generate those routes via route parameters. Below we route requests to an Ajax controller if they are XML HTTP requests (aka Ajax requests). defer_to do |request, params| params.merge! :controller => 'ajax' if request.xhr? end

Note the block parameters that defer_to receives. These are the requests from the client and the parameters from the behavior context in which they are being evaluated. This may suggest that deferred routing may also appear nested within other route statements: Merb::Router.prepare do match('/').to(:controller => 'home') do defer_to do |request, params| if Time.now.hour < 6

From the Library of Shirong Chen

54

Chapter 2: Routing

params[:action] = 'night' else params[:action] = 'day' end end end end

Although this example demonstrates the nesting of defer_to, we definitely don’t recommend using it for such a purpose. In fact, we recommend that you stay away from using deferred routing as much as possible, leaving such logic for inside your controllers.

2.5 Registering routes In Merb, the process of assigning route parameters to matches is known as the route registration. This is a necessary step in assuring that behaviors are compiled down and put into the routes array. Merb uses three equivalent methods to do this. Each varies only in name but thus provides a better semantic feel in different contexts.

2.5.1 Using to The to method is the standard way of both setting route parameters and registering them. We’ve seen the to method in past examples, and though its usage may seem obvious enough, we’ll spend some time on the details. The to method takes one optional parameter, a hash representing route parameters that are merged into existing contextual route parameters. For instance, here’s the second to method that adds in an additional route parameter to what was established by the first: Merb::Router.prepare do match('/users').to(:controller => 'users') do match('/:id').to(:action => 'show') end end

This example also displays that the to method accepts a block. This block works similarly to a block passed to the match method. More specifically, the block is evaluated in a new context where the parent behavior has been extended through the parameters that were given. Formalities aside, you can also rely on the descriptive nature of methods themselves to understand that the previous example compiles down to the following route: ==== Anonymous routes HTTP method: GET Route : /users/:id

From the Library of Shirong Chen

2.5

Registering routes

55

Params : {:controller=>"\"users\"", :action=>"\"show \"", :id=>"(path1)"}

2.5.2 Using with The with method, which is just an alias of to, is semantically used in forming blocks around routes without being chained to a specific behavior. Here we wrap with around a set of matches that are passed in a block: Merb::Router.prepare do with(:controller => "users") do match("/signup").to(:action => "signup") match("/login").to(:action => "login") match("/logout").to(:action => "logout") end end

These, of course, all compile down to routes set to be handled by the Users controller but by different actions: ==== Anonymous routes HTTP method: GET Route : /signup Params : {:controller=>"\"users\"", :action=>"\"signup\""} HTTP method: GET Route : /login Params : {:controller=>"\"users\"", :action=>"\"login\""} HTTP method: GET Route : /logout Params : {:controller=>"\"users\"", :action=>"\"logout\""}

Note that either to or register, which we’re about to discuss, could have been used in place of with, but we use with because it reads well aloud.

2.5.3 Using register The most common use of register, which is once again an alias of to, is to assure that a behavior is registered into a route even when no other route parameters need to be set. The reason this exists is because often the match method will automatically have set all your parameters for you and an empty .to would look awkward. Below we register such a behavior into a route.

From the Library of Shirong Chen

56

Chapter 2: Routing

Merb::Router.prepare do match("/:controller(/:action(/:id))(.:format)").register end

Note again, however, that register could have been to or even with and have had the same effect.

2.5.4 Redirects You can redirect routes from inside the Merb router. This is useful in maintaining compatibility after you’ve changed routes on a production application and want to assure that the bookmarks of users still work. To register a redirect, simply use the redirect method on a behavior. Note that you may also specify whether the redirect is permanent or not. If it is, the redirect will be sent with a status code of 301 instead of 302. Merb::Router.prepare do match('/stories').redirect('/articles', :permanent => true) end

2.5.5 Using symbols As we’ve seen previously, symbolic matching implicitly sets route parameters for us. However, we can also manually do so ourselves. Symbolic segment values are available as symbols within the strings used on values of the hash given to a to or any of its aliases. The following example should make this clearer: Merb::Router.prepare do match("/users/:last_name/:first_name").to( :controller => 'users', :full_name => "#{first_name} #{last_name}") end

To check that it works, we can fire up interactive Merb and send a fake request to the path /users/savas/foy: > merb.check_request_for_route(merb.fake_request( 'REQUEST_PATH'=>'/users/savas/foy')) => {:controller=>"users", :full_name=>"foy savas", :last_name=>"savas", :action=>"index", :first_name=>"foy"}

2.5.6 Using other captures We can also use other match captures in the value strings of the to hash. Bracketed numbers allow us to pull up either regex captures or symbolic segment values in the

From the Library of Shirong Chen

2.6

Other route settings

57

order in which they were matched, starting with 1. In the following example, we match the first segment as the language, then use default routes nested within: Merb::Router.prepare do match(%r{/?(en|es|fr|be|nl)?}).to(:language => "[1]") do default_routes end end

2.6 Other route settings You can do a few more standard things with routes, including setting defaults for route parameters and naming routes for references during generation. Let’s take a look at both of these.

2.6.1 Setting defaults Default values allow you to set defaults for route parameters that have not been set. To do this, we apply the default method on a behavior. For instance, below we set the controller match segment to optional but default it for Users. Note that we have to end the line with register, because default does not register the route itself. Merb::Router.prepare do match("(/:controller)/:id", :controller => /users|groups/). default(:controller => 'users').register end

We can test the results of this route registration using interactive Merb. Here it behaves as intended: > merb.check_request_for_route(merb.fake_request(' REQUEST_PATH'=>'/groups/robots')) => {:controller=>"groups", :action=>"index", :id=>"robots"} > merb.check_request_for_route(merb.fake_request(' REQUEST_PATH'=>'/robot')) => {:controller=>"users", :action=>"index", :id=>"robot"} > merb.check_request_for_route(merb.fake_request(' REQUEST_PATH'=>'/machines/robots')) Merb::ControllerExceptions::BadRequest: No routes match the request. Request uri: /machines/robots

2.6.2 Named routes Merb can identify routes by “name.” These names are convenient identifiers often used in the generation of URLs. Most of the routes we’ve used so far have gone unnamed.

From the Library of Shirong Chen

58

Chapter 2: Routing

However, we can easily add names by passing in a symbol, the name method: Merb::Router.prepare do match('/').to(:controller => 'home').name(:home) end

In interactive Merb, we can generate the root URL by passing the symbol :name to merb.url: > merb.url(:home) => "/"

Wasted typing? Of course, using a name to generate the root path may seem unnecessarily lengthy, but in practice this is not true. Named routes allow us to abstractly identify routes, whether short or long, and thus separate our need to determine what a route should look like from our need to use it in links, redirects, and elsewhere. Consequently, if at one point we decide to redefine the paths associated with particular routes, we will need to make changes only in the router. Now that’s time saved.

Remember that the url method is also mixed into Merb::Controller, so we’ll be using it heavily within both controllers and views to generate URLs for links and set the paths of redirects.

2.6.3 Setting prefixes We can prefix both names and controllers using routes. In the case of names, this means prepending a string plus an underscore to the name; this is most commonly used to semantically group associated routes. With controllers, this entails that the controller is found within a module. Let’s go through how to accomplish both of these types of prefixes.

2.6.3.1 Name prefix There are two ways to add a name prefix. The first is by passing in an extra symbol parameter to the name method: Merb::Router.prepare do match('/admin').to(:controller => 'admin').name(:admin, :home) end

From the Library of Shirong Chen

2.6

Other route settings

59

Alternatively we can use the options method: Merb::Router.prepare do match('/admin').to(:controller => 'admin').name(:home). options(:name_prefix => :admin) end

2.6.3.2 Controller prefix Merb allows you to nest controllers within modules and thus bundle sets of controllers with a similar purpose. For instance, we may nest all admin functionality within a module named Admin. In the following example, we make the router aware of such a setup: Merb::Router.prepare do match('/admin').option(:controller_prefix => :admin) do match('/:controller(/:action)').register end end

Here, paths like /admin/users route to the controller Admin::Users.

2.6.3.3 Namespaces You can achieve the effect of both name and controller prefixes more easily by using the method namespace. This is perfect for an admin module where you also want to be able to use named routes like admin_users to point to /admin/users. Below we use namespace to set both the name and the controller prefix. Merb::Router.prepare do namespace(:admin) do match('/:controller(/:action)').register end end

2.6.4 Fixatable routes Sometimes you need a route to be able to include a session ID. This is known as session fixation and is considered insecure for most purposes. The reason is that when you allow a session ID to be included in a URL, one user could trick another user into following a link with a fixated session. Once this second user logs in, the first user will be able to hijack the second user’s account. Merb therefore does not allow for fixated sessions by default, but does allow for them in certain cases so that they can pass on session-related responses to clients (like Adobe

From the Library of Shirong Chen

60

Chapter 2: Routing

Flash Player when it’s used to upload files) that are unable to handle cookies. Here’s an example of a fixatable route: Merb::Router.prepare do match('/file_uploads').to(:controller => 'files', : action => 'upload').fixatable end

Please remember to use fixatable routes only when needed, and to assure session integrity, regenerate the session ID after use.

2.7 Resource routes Resource routes are RESTful routes that provide a standard way of interacting with resources. Let’s explain how resources work in terms of the router.

2.7.1 Standard resources routing The method resources sets up various routes that allow you to access a particular resource. These routes are similar to the default routes but do not match exactly. For instance, with a default route you might use /users/show/1 to see the profile of a user. With a resources route, however, you would use /users/1. Resources routes also set up various defaults for the creation, modification, and deletion of resources. They also name each of your routes, making it easy to generate URLs. Let’s take a look at the routes generated by the following prepare block: Merb::Router.prepare do resources :turtles end

In interactive Merb we can pull up the following list: > merb.show_routes ==== Named routes Helper : delete_turtle HTTP method: GET Route : /turtles/:id/delete(.:format) Params : {:format=>"(path2)", :controller=>"\"turtles\"", :action=>"\"delete\"", :id=>"(path1)"} Helper : new_turtle HTTP method: GET Route : /turtles/new(.:format) Params : {:format=>"(path1)", :controller=>"\"turtles\"", :action=>"\"new\""}

From the Library of Shirong Chen

2.7

Resource routes

61

Helper : turtles HTTP method: GET Route : /turtles(/index)(.:format) Params : {:format=>"(path1)", :controller=>"\"turtles\"", :action=>"\"index\""} Helper : turtle HTTP method: GET Route : /turtles/:id(.:format) Params : {:format=>"(path2)", :controller=>"\"turtles\"", :action=>"\"show\"", :id=>"(path1)"} Helper : edit_turtle HTTP method: GET Route : /turtles/:id/edit(.:format) Params : {:format=>"(path2)", :controller=>"\"turtles\"", :action=>"\"edit\"", :id=>"(path1)"} ==== Anonymous routes HTTP method: POST Route : /turtles(.:format) Params : {:format=>"(path1)", :controller=>"\"turtles\"", :action=>"\"create\""} HTTP method: PUT Route : /turtles/:id(.:format) Params : {:format=>"(path2)", :controller=>"\"turtles\"", :action=>"\"update\"", :id=>"(path1)"} HTTP method: DELETE Route : /turtles/:id(.:format) Params : {:format=>"(path2)", :controller=>"\"turtles\"", :action=>"\"destroy\"", :id=>"(path1)"}

Note that all resources go to the same controller, but that there are seven standard actions: index, new, create, edit, update, destroy, and show. We’ll learn about these seven actions and their purpose in depth when we cover REST, but for now, it should suffice to know which routes go to which action. Here’s a list of examples with a brief explanation of intent:

2.7.1.1 Index • /users—retrieves a list of users • /turtles.xml—retrieves a list of turtles as XML

From the Library of Shirong Chen

62

Chapter 2: Routing

2.7.1.2 New • /users/new—requests the form needed to create a new user account

2.7.1.3 Create • /users with POST—creates a new user from POST data • /turtles.txt—creates a new turtle with POST data with confirmation in a text

format

2.7.1.4 Edit • /users/1/edit—requests the form needed to create a new user account

2.7.1.5 Update • /users/1 with PUT—updates the user with an ID equal to 1 with the POST data • /turtles/1.json with PUT—updates the turtle with an ID equal to 1 with the

POST data with confirmation in JSON

2.7.1.6 Destroy • /users/1 with DELETE—deletes the user with an ID of 1 • /turtle/1/delete with GET—deletes the turtle with an ID of 1

2.7.1.7 Show • /users/1—shows the profile of the user with an ID of 1 • /turtle/1.xml with GET—shows the details of the turtle with an ID of 1 in XML

2.7.2 Singular resource routing Sometimes a resource is all alone. In other cases the user’s interaction with that class of resources should be limited to only the one that belongs to that user. In both cases, a singular resource route is best. Here we use a singular resource route for our application’s overall admin settings (stored as one row in a table) and to set up routes for our user’s account, both times using the resource method: Merb::Router.prepare do namespace :admin do resource :settings end

From the Library of Shirong Chen

2.7

Resource routes

63

resource :account end

This creates routes similar to those created by resources but without IDs. The singularity of the resource also rules out the need for an index action. Thus the only actions routed to are show, new, create, edit, update, and destroy.

2.7.3 Using identify Sometimes a route like /users/1 is unpleasant. In fact, there are at least four reasons why such a URL may be unwanted: • You don’t want to have to remember ID numbers to see a resource’s page. • Search engines often optimize for keywords in URLs, so ID numbers are bad search

engine optimization. • ID numbers can give away how many of a resource you have. • ID numbers make scraping your data from the web easy to do.

To get around these issues, the Merb router has a method identify. By using it you can change how a resource is turned into a string in routes. Here we use identify to opt for the use of username instead of id: Merb::Router.prepare do identify User => :username do resources :users end end

Thus, routes generated with a user object use the username method for identification. url(:users, user) # => ex. '/users/foysavas'

We can also provide custom methods within our models to stringify our identifier. This method has to be defined in your model class. For those using the ActiveRecord ORM, the method to_params is supposed to serve this purpose. Consequently, the ActiveRecord plugin saves you from even having to include identify blocks in your router by automatically wrapping the router in an identify ActiveRecord::Base => :to_params.

From the Library of Shirong Chen

64

Chapter 2: Routing

2.8 Conclusion Routing is critical to an MVC web framework. Merb applications enjoy simple-to-use, semantically well-defined route definition that boosts comprehensive bidirectional route recognition and generation. We’ve also gotten a taste of what it means to be RESTful and why adherence to such standards can simplify both an application’s internals and its API. Finally, we even peered into the Merb routing internals to understand how the behavior class is used as an intermediate step toward route definition.

From the Library of Shirong Chen

C HAPTER 3

Controllers

In Merb, controllers are what tie all of your application code together. They are the C in MVC and have been built to assemble responses to the requests received from users. On occasion, a controller’s response is entirely produced by code in the controller itself. More often, though, responses are complex composites that incorporate the pulling of data through models and the rendering of views through templates. Controllers also handle the more subtle aspects of responses, including response format, MIME type, and status code. We’ll also craft within them behind-the-scenes logic that uses sessions, filters, and exceptions. When users request unavailable or impermissible data, controllers can redirect those users to more appropriate locations. Finally, Merb controllers come with the built-in ability to queue up background processes and run them outside the standard request-to-response cycle. In this chapter we will go over each of these topics as well as controller internals. While doing this, we’ll emphasize controllers themselves and defer examples involving models and views to later chapters. This may seem unconventional, but separating these concerns will, if nothing else, make this chapter an invaluable reference when all you need to do is cut to the chase. That said, there will be some blurring of focus near the end of this chapter as it weaves into the next and we discuss the rendering of views through controllers. If you’re completely new to MVC, controllers are definitely the most natural and best place to start, because they let you dig right in and produce responses from the get-go. To keep things simple, nearly all the examples in this chapter are going to be single-file Merb applications that can be run easily alongside a default set of routes.

3.1 From request to controller Since we previously went over the Merb router, it’s a good time to walk through how requests get to controllers and how controllers set up actions to handle those requests. 65 From the Library of Shirong Chen

66

Chapter 3: Controllers

3.1.1 A simple application While Merb controller actions are just standard methods of classes you can initialize and use, a Merb application itself does not call these actions. Instead, Merb initializes controllers based upon requests and then uses the controller method _dispatch to call the appropriate action. Notice that _dispatch starts with an underscore. As an application developer you don’t really need to know about it, but by using it you will avoid conflicts in the namespace of application-specific controller methods. However, we mention it here because of its central role in how controller instances deal with requests. That said, a basic understanding of both Merb::Request and _dispatch is desirable. So let’s fire up interactive Merb with the following application and imitate a request from the browser: class HelloFriend < Merb::Controller def index if params[:name] "hi #{params[:name]}" else "hi" end end end

3.1.2 How requests get dispatched When a Merb::Request is initialized, it requires at least two options to make sure it gets routed correctly: REQUEST_PATH and REQUEST_METHOD. True to their names, these two options represent the path and the method of the request. Let’s make a series of requests and observe their responses. To do this, we’ll use the Merb::Request#handle, which uses the router to first determine the appropriate controller and its action and then dispatch the request. Because we’re interested only in the body of the response, we’ll tack that onto our statement. $ merb -i -I home.rb > request = Merb::Request.new({'REQUEST_PATH'=>'/ hello_friend', 'REQUEST_METHOD'=>'GET'}) > request.handle.body => 'hi' > request = Merb::Request.new({'REQUEST_PATH'=>'/ hello_friend', 'REQUEST_METHOD'=>'GET', QUERY_STRING=> 'name=you'}) > request.handle.body => 'hi you'

From the Library of Shirong Chen

3.1

From request to controller

67

The second request we created used QUERY_STRING. Again, as an application developer, it’s not essential for you to know about the options that define a request, but QUERY_STRING, had it come from a browser, would be the text that follows the question mark in a URL such as http://localhost:4000/hello_friend?name=you. The end effect, with respect to the controller, is the setting of params[:name] equal to 'you'.

3.1.3 The controller’s perspective Let’s imitate another aspect of request handling by creating the controller ourselves instead of using Merb::Request#handle. We won’t need REQUEST_PATH and REQUEST_METHOD, since in this example we’ll be doing the job of the dispatcher and router ourselves when we choose and initialize the appropriate controller and then invoke the right action: > request = Merb::Request.new({'QUERY_STRING'=>'name=friend'}) > controller = HelloFriend.new(request) > controller.index => "hi friend"

Notice that this does not return a full response as in the previous examples but instead simply the body. This is because the job of each controller action is simply to return the body for the response. As we’ll discuss later on, the body can be more complex than a string and may use view template rendering through the method Merb::Controller#render. Aside from the body, the remainder of the response is typically set through various side effects of the controller code. To replicate the full response in interactive mode, we can more closely follow the path that the dispatcher takes and invoke the handling of a request with the Merb::AbstractController#_dispatch method we spoke of earlier: > request = Merb::Request.new({'QUERY_STRING'=>'name=there'}) > controller = HelloFriend.new(request) > controller._dispatch(:index).body => "hi there"

The second line initializes the HelloFriend controller. Notice how it requires a request as part of initialization. This is essential, as it allows the controller object to be aware of the request it is handling and interpret its parameters. Finally, we use _dispatch(:index) to indirectly perform the index action, and body to give us only the body of the return. There are two other major concerns that _dispatch takes care of, sessions and filters, both of which we will discuss later on.

From the Library of Shirong Chen

68

Chapter 3: Controllers

3.2 The controller classes All controllers in Merb inherit from the class Merb::AbstractController. This class was designed to allow the Merb core to be as extensible as possible. This is because, despite the fact that MVC and web frameworks now seemingly go hand in hand, the concept of the controller can apply well outside the web request controller. For example, sometimes you’ll want a controller class to manage the sending of emails. Other times, reminiscent of the original inspiration for the MVC design pattern, you’ll want a controller to determine the behavior of a particular widget embedded in the context of a response’s larger view template. Both of these are possible thanks to Merb’s abstract controller. At this point, if you feel a bit lost with regard to abstract controllers, don’t worry. What’s important to know right now is that all Merb controllers are actually subclasses of either Merb::AbstractController or one of its descendants. Within the Merb core, these descendants are Merb::Controller, Application, and Exception. Interestingly enough, these three classes, in the order in which they were just listed, form a descending chain of subclasses. In other words, Exception is a subclass of Application, which is a subclass of Merb::Controller, which itself is a subclass of Merb::AbstractController. We’ll go over each of these in this section and then describe how to use them in the rest of the chapter. In later chapters we’ll also see two more subclasses of Merb::AbstractController—MailController and PartController—both of which exemplify the ability of Merb::Abstract Controller to be subclassed in different ways for extremely practical purposes. However, before we get into these specific controller classes and their methods, it’s important to know that many of the methods you’ll find in the source of each of these classes begin with an underscore. This is because Merb controller classes seek to avoid populating themselves with method names you may otherwise want to use. Additionally, methods that start with underscores are understood to be outside the scope of the Merb public API and therefore don’t really need the attention of the application developer. With all this in mind, please note that we are simply enriching your understanding of the framework internals. Finally, you should know that some controller instance methods are called actions. This is because they are responsible for the act of responding to requests. In general, if you’re wondering whether a method is available as an action or not, you should first check if it is a public instance method. If it is, then it’s probably an action. There is, however, one exception, and that’s if the method has been added to the list of nonaction methods. This list is maintained so that you can prevent users of your application from sending requests directly to these methods. Not so surprisingly, most public instance methods in the core controller class appear in this list.

From the Library of Shirong Chen

3.2

The controller classes

69

Table 3.1 General methods Method

Use

controller_name

Returns the controller’s name in snake case with a / separating module namespaces

inherited

Adds a subclasses controller name to subclasses_list

subclasses_list

Holds a list of subclasses

3.2.1 The abstract controller Despite being the eldest parent class of all controllers, Merb::AbstractController makes very few specific demands on its descendants, leaving most of its methods as nothing more than stubs. Ultimately this means that Merb::AbstractController, true to its name, acts more as an ideal form of what a controller should look like than anything else. Let’s go over the prototypical methods that have been included in Merb:: AbstractController. First we’ll look at class methods and then instance methods.

3.2.1.1 Class methods There aren’t many API class methods in Merb::AbstractController, but those that do exist well characterize what a controller is all about. They also give you an idea of what sort of attributes and logic can be applied throughout a controller class and across actions. In Tables 3.1, 3.2, and 3.3, we’ve divided the class methods into general methods, filter methods, and render methods. Table 3.2 Filter methods Method

Use

add_filter

Adds a filter to a filter chain (typically not used directly)

after

Adds a filter to the after filter chain

before

Adds a filter to the before filter chain

skip_after

Skips a filter in the after filter chain

skip_before

Skips a filter in the before filter chain

skip_filter

Skips a filter previously added in a filter chain

normalize_filters!

Ensures that filter option values are arrays (typically not used directly)

From the Library of Shirong Chen

70

Chapter 3: Controllers

Table 3.3 Render methods Method

Use

default_layout

Resets layout options

layout

Sets the layout to be used or disables layouts when nil or false is given

render_options

Sets class-level layout options

template_roots

The root location of the templates the controller uses

template_roots=

Sets the root location of the templates the controller uses

3.2.1.2 Instance methods There are more API instance methods than class methods when it comes to Merb::AbstractController. Here we’ve divided them into general methods, URL methods, and view methods, as shown in Tables 3.4, 3.5, and 3.6. We’ve spoken before of using Merb outside web development, but the inclusion of URL methods in the abstract controller really pivots Merb use toward the web framework.

3.2.2 The Merb controller All Merb controllers inherit from the class Merb::Controller. This controller fully implements the web functionality for controllers. Therefore, it’s here that we’ll find the inclusion of request, parameter, and header methods. The API methods are broken down into class methods and instance methods; let’s go over these newly added methods.

3.2.2.1 Class methods The Merb::Controller class methods mainly serve to define what methods are available as actions and what formats are provided by those actions. Consequently, we’ve divided the methods introduced by the Merb::Controller into general and format methods, shown in Tables 3.7 and 3.8.

Table 3.4 General methods Method

Use

action_name

The action name associated with the controller instance

action_name=

Sets the action name associated with the controller instance

controller_name

Equivalent to the same class method

From the Library of Shirong Chen

3.2

The controller classes

71

Table 3.5 URL methods Method

Use

absolute_url

Returns the absolute URL of a route, including host and protocol

relative_url

Returns the relative URL of a route by route name or route parameters

url

Same as relative_url

Table 3.6 View methods Method

Use

body

Returns the body of the response being created

body=

Sets the body of the response being created

capture

Calls the capture method of the appropriate template engine

capture_erb

Captures an ERB template block, returning a string

catch_content

Returns the content “thrown” with a particular symbol

clear_content

Clears rendered content so another template can be rendered

concat

Calls the concat method on the appropriate template engine

concat_erb

Concats an ERB template block to the buffer

content_type

Gets the content type for the controller response

content_type=

Sets the content type for the controller response

partial

Used within templates for the embedding of templates

render

Renders a view with options, returning a full response with body

render_all

Calls render without any transformation

render_html

Calls render with the HTML MIME set

render_js

Calls render with the JS MIME set

render_json

Calls render with the JSON MIME set

render_text

Calls render with the text MIME set

render_xml

Calls render with the XML MIME set

render_yaml

Calls render with the YAML MIME set

template_roots

Equivalent to the class method with the same name

template_roots=

Equivalent to the class method with the same name

throw_content

Evaluates a template and stores it as a string for later use

thrown_content?

Checks whether content has been thrown

From the Library of Shirong Chen

72

Chapter 3: Controllers

Table 3.7 General methods Method

Use

callable_actions

Returns a set of all callable actions

hide_action

Hides an action, removing it from the set of callable actions

show_action

Adds an action to the set of callable actions

3.2.2.2 Instance methods The instance methods of Merb::Controller serve a number of purposes, most notably the need to make request and session data accessible to the action code. Other methods exist simply to aid in formatting. Tables 3.9 through 3.13 cover the most common API methods.

3.2.3 The application controller If you create a standard Merb application with merb-gen, you will find two files in app/controllers/. The first of these, Application, is meant to serve the parent class of all the application’s other controllers. This allows you to centralize shared code that would otherwise be found across your application’s controllers. For instance, here we have placed a filter that ensures that all web requests come from logged-in users: class Application < Merb::Controller before :ensure_authenticated end

Table 3.8 Format methods Method

Use

class_provided_formats

An array of formats the controller provides in responses

class_provided_formats=

Sets the array of formats the controller provides in responses

clear_provides

Clears the array of provided formats

does_not_provide

Asserts that an array is not provided

only_provides

Limits the array of provided formats to what is listed

provides

Appends an array of formats to the existing array of provided formats

reset_provides

Resets the array of provides

From the Library of Shirong Chen

3.2

The controller classes

73

Table 3.9 General methods Method

Use

headers

A hash containing the headers from the request

params

A mash containing the parameters from the request

status

The status code that will be sent

status=

Sets the status code for the response

request

The request object that got routed to the controller

rack_response

The rack response that will be delivered

redirect

Causes a redirect to a URL (note: will not exit from the action logic!)

message

The message that was included in the request

Table 3.10 Session methods Method

Use

cookies

The cookies from the request

delete_cookie

Deletes a cookie

set_cookie

Sets a cookie variable

session

Accesses the abstracted session store

Table 3.11 Format methods Method

Use

class_provided_formats

Proxy method for the class method

class_provided_formats=

Sets the proxy method for the class method

does_not_provide

Sets the formats not provided by an action

only_provides

Limits the formats provided by an action

provides

Describes the formats provided by an action

From the Library of Shirong Chen

74

Chapter 3: Controllers

Table 3.12 Escaping methods Method

Use

escape_xml

Escapes XML entities for use within XML

h

Escapes HTML entities for use within HTML

html_escape

Same as h

3.2.4 The exceptions controller The other controller generated as part of a Merb application is the exceptions controller. It is subclassed from Application and is used to craft error responses you may have already encountered during development. Note that it is common to extend or override the default responses. So, for instance, below we have created a new controller action that handles unauthenticated users. class Exceptions < Merb::Controller def unauthenticated render :format => :html end end

3.2.5 Other controllers As previously mentioned, Merb::Controller is not the only subclass of Merb:: AbstractController. In later chapters we’ll see the Merb::MailController and Table 3.13 Other methods Method

Use

nginx_send_file

Sends files through nginx

render_chunked

Renders the response in chunks

render_deferred

Mongrel-only method that defers rendering, allowing for other responses to be sent

render_then_call

Renders its parameter and then runs the block

run_later

Places a block in the worker queue

send_chunk

Sends a chunk

send_data

Sends binary data

send_file

Sends a file

stream_file

Streams a file

From the Library of Shirong Chen

3.3

Custom controller classes

75

Merb::PartController, each of which controls the flow of logic with actions without directly handling web requests.

3.3 Custom controller classes Now that we have described the various core controller classes as well as followed the pathway through which a request is handled, this is a good time to create our own controllers.

3.3.1 Controller location In the standard Merb application layout, all web controllers are located within the directory app/controllers/. We say all web controllers because the other controllers, MailController and PartController, tend to live elsewhere in other directories. However, if you’re using the flat layout, you’ll find that all of your controllers are kept in one file, application.rb. Also, in the case of the very flat layout, your controllers basically have nowhere else to live but as part of a single file. Note that both the flat and very flat layouts are generated with a custom controller subclassed directly from Merb::Controller instead of Application. This seems to be based on the assumption that you’ll be making an application small enough that it does not need a parent class for all controllers. However, don’t let that restrict you—if you’re using the flatter layouts and need Application or Exception, by all means, code them in. Even though it’s extremely rare to see someone deviate from the default locations, you can change the location of your controllers if you want. To do this, you can define a framework hash for Merb::Config inside the file config/framework.rb. This alters the default framework locations at Merb boot-up, but make sure you mention all locations you want to be set, because framework.rb doesn’t merge with the default settings. The following snippet shows, among other things, how to set the location of controllers to controllers/ as opposed to app/controllers: Merb::Config[:framework] = { :controller => Merb.root / "controllers", :view => Merb.root / "views", :model => Merb.root / "models", :lib => Merb.root / "lib", :public => [Merb.root / "public", nil], :router => [Merb.root / "config", "router.rb"] }

From the Library of Shirong Chen

76

Chapter 3: Controllers

To check that this has had an effect or just to find out where your application thinks controllers should be, you can always fire up interactive Merb and have it evaluate the following: $ merb -i > Merb.dir_for(:controller) => "/home/foysavas/src/the-merb-way/code/framework_changes/ controllers"

3.3.2 Naming controllers By convention, the filename of a controller file should be the snake case of the contained controller’s class name. For example, a controller named OrderTransactions would be contained in a file named order_transactions.rb. This isn’t strictly necessary, but it’s good practice and a convention that others can recognize. As long as your controllers are located within the controller directory or one of its subdirectories, they will be loaded at boot. Feel free to name each controller whatever you’d like, but keep in mind that the names of controllers could collide with other class names in the global namespace. This specifically becomes a problem with models. Consequently, the convention is to name controllers that have corresponding models in the plural form. For example, you’ll often find a controller named Users when there’s a model named User. If there is no corresponding model, don’t worry; just name your controller whatever makes the most sense. Welcome and Home are good examples of names for a controller that would handle the landing page of your application.

3.3.3 Organizing controller methods The organization of a controller’s methods is critical to how a controller responds to requests. In general, you should define one public instance method for each type of request a controller will handle. If you need other methods that won’t handle requests directly, you should leave them for near the end of your controller and mark them either private or protected. Both private and protected, in the context of Merb controllers, have the same effect, as it would be odd to have two Merb controller instances working together during a single request. Typically, you use private or protected methods in your controller classes because they allow you to • Share a nonaction method among controller actions • Make methods available to all controller subclasses • Increase the readability of code within your controller

From the Library of Shirong Chen

3.3

Custom controller classes

77

3.3.3.1 Sharing a nonaction method In this fabricated example we use a private method as a means of accessing data: class ColorTriad < Merb::Controller def index get_all_colors.join end def show get_all_colors[params[:id]] end private def get_all_colors ['red','blue','green'] end end

In our model-less world of controller-only applications this makes sense. However, more realistically, such a method would most likely encapsulate several lines of data, retrieving code that would otherwise appear in multiple controller actions. A perfect example of this is the case of the show and edit methods of a RESTful resource.

3.3.3.2 Making methods available to subclasses Sometimes you want to make a method available to more than one controller. The most typical way of doing this is to make it a private method within the Application class: class Application < Merb::Controller private def users_in_groups { 'me' => ['Merb Developers','Likes Durian'], 'you' => ['Merb Developers','Durian Stinks!'] } end end class Users < Application def index users_in_groups.map do |u, g| u + ' is in ' + g.join(',') end.join("\n") end end

From the Library of Shirong Chen

78

Chapter 3: Controllers

class Groups < Application def index groups = [] users_in_groups.each do |u, g| groups[:g] << u end groups.map do |g, u| g + ": " + u.join(',') end.join("\n") end end

This highly contrived example shows us using a private method in Application to retrieve a hash of information. After we go over more Merb functionality like models and filters, the practical use of parent private methods will become clearer. For now, recognize that it is a clean way to organize controller code.

3.3.3.3 Increasing readability of an action Often a controller action can get lengthy and hard to read. But by moving lines of code into private methods, we can increase readability with clear names. The following example shows how an action can be arranged in an understandable way even if all functionality is not in place: class Users < Merb::Application def show find_user hide_private_information render end private def find_user # ... end def hide_private_information # ... end end

From the Library of Shirong Chen

3.4

Filters

79

3.3.4 Setting callable actions Merb::Controller and its descendants were created to directly handle requests. Thus

by convention, all public instance methods are callable actions, but if you’re constructing your own variant of the Merb controller, you may need a public method that isn’t available to be called as an action. For example, the Merb::Controller class has the following public methods but has hidden them from being called as actions: request, headers, status, and rack_response. This is because all of these methods are used to manipulate a controller instance in the larger context of sending back a response and thus must be made public.

3.3.4.1 Hiding an action In case you too want to come up with a public method that’s best to hide, you can easily do so by using the hide_action class method within your controller class: class SpecialController < Merb::Controller hide_action :special def special # ... end end

3.3.4.2 Showing an action Likewise, you can show an action that was previously hidden using the show_action class method. This applies to subclasses of controllers with hidden actions. class SuperSpecialController < SpecialController show_action :special end

3.4 Filters Often you want to call a method before or after the performance of a controller action. Filters allow you to do so for multiple actions without having to explicitly evoke the relevant method in each action. Typical examples of filters include authentication, resource checking, and application auditing. Filters conventionally appear at the top of a controller and take either a method name or a Proc. An optional hash can specify to which actions the filter should apply. Multiple filters can apply to a single action and are executed as part of a filter chain. It’s good to know that filters are available to all

From the Library of Shirong Chen

80

Chapter 3: Controllers

controller classes descending from AbstractController, including MailController and PartController.

3.4.1 Before filters Before filters are called before any of the action code has been executed. They are created using the before class method, which is available to all descendants of AbstractController. The first parameter of before can be either a method name or a Proc. Method names may be in the form of strings but are typically symbols. Thus, all of the following filters are equivalent: before :authorize before "authorize" before Proc.new{ authorize }

Note, however, that a before filter specified by the same method name overrides previous before filters in the before filter chain. Consequently, if you actually used the code shown above in a controller, authorize would be called only twice. The method called by a before filter is typically a private or protected method of the controller, and you will often see filters appearing as follows: class Home < Merb::Controller before :set_favorites def index @favorite_framework end private def set_favorites @favorite_framework = 'Merb' end end

You should know that Merb filters are evaluated in the context of the controller object. Thus, when your before filter is in the form of a Proc, you are able to set instance variables to be used later on: class Home < Merb::Controller before Proc.new { @favorite_framework = 'Merb' } def index @favorite_framework end end

From the Library of Shirong Chen

3.4

Filters

81

Before filters are also able to catch :halt exceptions, which is useful for redirecting or diverting unauthorized or incorrect requests: class WhoseHome < Merb::Controller before :check_last_name, def index "welcome home" end private def check_last_name unless params[:last_name].downcase.in?(['savas','chou']) throw :halt, "sorry, this isn't your home" end end end

3.4.2 After filters An after filter can be created using the after class method of AbstractController. Similarly to before, it takes either a method name or a Proc, but it is evaluated after the performance of the action. The most typical use of an after filter is either to log the use of your application or to do cleanup or postperformance processing on resources: class LogVisits < Merb::Controller after :log_visit def index "hi" end def logout "bye" end private def log_visit case action_name when 'index' Merb.logger.info("Someone's here.") when 'logout' Merb.logger.info("Someone's leaving.") end end end

From the Library of Shirong Chen

82

Chapter 3: Controllers

You can make last-minute alterations to the response by accessing the @body attribute: class FrameworkSwitcher < Merb::Controller after Proc.new{ @body.gsub!("Rails","Merb") } def index "Rails Rocks!" end end

One thing to note with after filters is that the client does not receive a response until the after filter chain is complete. If you run the example below, you’ll end up waiting a random number of seconds for the actual response. If client response time is an issue, consider using Merb’s deferred instead, which is discussed near the end of this chapter. class SlowWakeUp < Merb::Controller before :alarm_and_time after :keep_sleeping def index "Good morning!" end private def alarm_and_time Merb.logger.info "*alarm clock sounds*" @start = Time.now end def keep_sleeping sleep(rand(7)) @body << " Woke up in #{Time.now - @start} seconds." end end

3.4.3 Filter options When you want a filter to be applied only to particular actions of a controller, you can do so by specifying them as an array of symbols keyed to :only in the option hash: before :read_file, :only => { :show, :edit }

From the Library of Shirong Chen

3.4

Filters

83

If instead you want a filter to not apply to particular actions of a controller, you can specify them as an array of symbols keyed to :exclude in the option hash: before :authorize, :exclude => { :login }

Sometimes you want to have filters applied only in the case of more complex conditions. The :if and :unless options allow you to do this with either a method name or Proc: class RoomService < Merb::Controller before :automate_response, :if => Proc.new { Time.now.hour < 6 } def index "Room service - may I help you?" end private def automate_response throw :halt, "Sorry, room service is unavailable at the moment." end end

You can also pass parameters to filters by using :with, but when doing so you’ll have to make sure that the arity of the filter matches the size of the :with array: before :has_role, :with => ['Admin']

3.4.4 Skipping filters On occasion you’ll want to skip a filter that was defined in a superclass. To do this, you can use the skip_before and skip_after class methods from AbstractController: class Application < Merb::Controller before :login_required private def login_required unless session[:user_id] throw :halt, Proc.new { |c| c.redirect url(:controller => 'sessions', : method => 'new') } end end

From the Library of Shirong Chen

84

Chapter 3: Controllers

end class Sessions < Application skip_before :login_required, :only => %w{ new create } end

3.5 Redirects There are many cases when a user has sent a request that should ultimately get redirected. You can make this happen by using the controller method redirect. The redirect method accepts a string for a URL as its first parameter and also takes an optional hash. This optional hash may include a Boolean setting of :permanent and a :message to pass on: redirect "/login" redirect "http://www.merbivore.com", :permanent => true redirect "/", :message => 'Please, sign up or log in to continue."

3.5.1 A redirect caveat One important point to remember when using redirects is that they do not stop the execution of the controller action, and whatever code is left to evaluate will run before the redirect is sent. The controller action, however, will not get the chance to return a value. The following example should make this clear: Merb::Router.prepare do to(:controller => 'recruiters_dilemma') do match('/').to(:action =>'index') match('/show_prize').to(:action => 'show_prize') match('/apologize').to(:action => 'apologize') end end class RecruitersDilemma < Merb::Controller def index if params[:people].to_i >= 10 redirect '/show_prize' else 'How many people have you recruited? Append it as a number after "?people=" to this URL.' end end

From the Library of Shirong Chen

3.5

Redirects

85

def show_prize redirect '/apologize', :permanent => true Merb.logger.warn "Here comes another winner!" "Your brand-new Ferrari F355!" end def apologize "Our apologies." end end

In the previous example, "Here comes another winner!" is logged, but because of the redirect, which is essentially a change in management for the final response, none of us gets our F355. This example is harmless enough for both user and developer, but you should be cautious when using redirects and make sure that unnecessary business logic does not run. Another thing to note in this example is the use of :permanent in the second redirect. This effectively changes the status code of the response from 301 to 302 and from the browser’s perspective assures that '/show_prize' should always point to '/apologize'.

3.5.2 Redirects after POST requests The most common use of redirects in practice is to redirect users after they have posted content. You may not be familiar enough with Merb to completely understand the following example, but here a user has posted what looks like a new entry of some sort, and if it saves without error, the user is redirected to the list of entries: class Entries < Application # ... def create @entry = params[:entry] if @entry.save redirect '/entries' else render :new end end # ... end

From the Library of Shirong Chen

86

Chapter 3: Controllers

3.5.3 Redirecting in before filters At other times, controllers redirect users before the action ever starts. This most likely occurs because a particular resource doesn’t exist or because a user has yet to log in. Before filters are a great place for this kind of logic because these cases tend to apply to multiple controller actions and are simplified logistically by gaining access to the throwing of halts. Let’s take a look at an example: Merb::Router.prepare do to(:controller => 'users_names') do match('/').to(:action =>'index') match('/:username').to(:action => 'show') end end DATA = { :users => { :foysavas => 'Foy Savas', :sophiachou => 'Sophia Chou' } }

class UsersNames < Merb::Controller before :get_by_username, :only => 'show' def index message || "Welcome" end def show "#{params[:username]} => #{@user}" end private def get_by_username if (@user = DATA[:users][params[:username].to_sym]).nil? throw :halt, Proc.new{ redirect '/', :message => "#{params[:username]} not found" } end end end

An important takeaway from this example is how the redirect was accomplished. Before filters are able to catch thrown halts that can also take Procs. These Procs are

From the Library of Shirong Chen

3.6

Exceptions

87

evaluated using instance_eval. By putting a redirect in this Proc, we are able to redirect the controller without having to worry about more of the controller code being evaluated. Though it may seem redundant to mention, throw :halt does not work anywhere but inside the before filter chain, so don’t try to use it anywhere else or you’ll just get an uncaught exception and an error that looks like this: ˜ uncaught throw ‘halt' in thread 0xd6bad0 - (ThreadError)

3.6 Exceptions If you’re looking for something similar to throw :halt that you can use outside before filters, raising exceptions may be your answer. By raising particular controller exceptions, you can halt controller execution midway and internally reroute the request to the Exceptions controller. There’s one important thing to note, though: Unlike redirects, using Exceptions means it’s the end of the line for your user and an error page will be displayed. Yes, you’ll be able to make this error page pleasing and include a cute mascot, but ultimately it is an error page, so if you’re going to use it, make sure that’s what you intend and not a more subtle redirect.

3.6.1 Raising an exception Many exceptions have already been defined for you within the Merb core. Let’s go through an example using one of the predefined exceptions to get a basic feel for how they are used: Merb::Router.prepare do match('/').to(:controller => 'exceptional', :action =>'index') end class Exceptional < Merb::Controller def index raise NotFound end end

Here, when we request the index, a Not Found error appears along with a 404 status code in the response.

3.6.2 Controller exceptions When you raise an exception somewhere in your controller code, it is rescued by the dispatcher and redispatched to be handled as a controller exception. These exceptions

From the Library of Shirong Chen

88

Chapter 3: Controllers

are defined in the module Merb::ControllerExceptions and offer an exception for each of the W3C standard HTTP status codes. If the error raised is not among these existing controller exceptions, Merb interprets it as an internal exception and uses the class InternalServerError to handle it. This is the error page you’ve seen in the past when something has gone wrong with your code.

3.6.3 The exceptions controller The exceptions controller is one of the core controller classes we talked about earlier. Its purpose is to translate an exception into a response. Merb handles the routing behind the scenes, but what’s important to know is that each exception class name is snake-cased and then called as an action method name in Exceptions. Below we see a custom controller exception that, with the help of the exceptions controller, responds with a string. Merb::Router.prepare do match('/').to(:controller => 'sad_hacking', :action =>'index') match('/root').to(:controller => 'sad_hacking', :action =>'root') end class SadHacking < Merb::Controller def index "hack me" end def root raise BadHacker end end class BadHacker < Merb::ControllerExceptions::Unauthorized; end class Application < Merb::Controller ; end class Exceptions < Application def bad_hacker "that was pathetic..." end end

If you request /root, the BadHacker exception will be handled in the same way as an unauthorized user. The only difference, of course, is the custom response found in the exceptions controller.

From the Library of Shirong Chen

3.7

Rendering templates

89

3.7 Rendering templates Rendering templates is one of the most common actions you’ll find at the end of a controller. Consequently, there are a number of methods found in the Merb::Controller class that deserve our consideration now before the chapter on views (Chapter 4). We’ll go over each of these methods, but before we do, we’ll need to get comfortable with how Merb brings together controllers and templates.

3.7.1 How templates are compiled Templates typically exist as files stored in app/views, all of which Merb opens up and inlines into a template method. These template methods are then accessible by original filename to any of the subclasses of Merb::AbstractController. Typically, a controller associates itself with a particular path, and then the action that calls render appends its name as a file followed by a response format extension and then a template format. For example, the action Users#index associates itself by default with the template at app/views/users/index.html.erb. The .html is there since HTML is the default format that Merb uses for responses. The .erb is for ERB, which is the default template format. ERB is a versatile template type that has the potential to render HTML, XML, JSON, or really any textual format. However, there are other template engines that may be more suitable for particular responses. These alternatives include Haml, which excels in structuring HTML and XML with extreme brevity. For now, though, since we’re currently considering templates only in the context of controller logic and not in that of the view, we’ll use only ERB. In fact, in order to keep with our desire to produce single-file Merb applications, we’re going to do something completely unconventional: We’re going to include our templates as virtual files. You will probably never do such a thing, but getting a good feel for how templates are compiled through imitation will definitely demystify what otherwise may seem like magic. Let’s start off with a simple example: Merb::Config.use { |c| c[:framework] ] }, c[:session_store] c[:exception_details] }

= { :public => [Merb.root / "public", nil = 'none', = true

Merb::Router.prepare do match('/').to(:controller => 'weird', :action =>'index') end

From the Library of Shirong Chen

90

Chapter 3: Controllers

Merb::BootLoader.after_app_loads do vf = VirtualFile.new("hi <%= @var %>",'app/views/weird/ index.html.erb') Merb::Template.inline_template(vf) end class Weird < Merb::Controller def index @var = 'friend' render end end

If you run the code above as a single-file application and check http://localhost: 4000, you’ll find a friendly 'hi'. You’ll recognize that pulling this off wasn’t as easy as it was in the past. The first thing we did was add a Merb::BootLoader. after_app_loads block. As we saw in Chapter 1, this block runs after our application code has been loaded. Here we use it to first create a fake template using a virtual file and then inline that virtual file using inline_template. Notice that the virtual file takes two parameters for initialization. The first is what would have been the actual content of the file. The second is a fake file path. Here we’ve matched it to what the Weird#index method would naturally associate itself with. Now let’s take a look at the content of the virtual file. You’ll notice some text, some odd bracketing, and a class method inside. We’ll go over these odd brackets in the next chapter, but suffice it to say that they designate sections of an ERB template that should be interpreted in Ruby, and in this case also appended to the template. But why a class variable? Remember that all templates are included as methods of the abstract controller. Consequently, class methods from the controller instance are also available to the template itself.

Speed through common sense or just contentious? Merb has always emphasized speed, but oddly enough it achieves this most often through common sense. We saw that Merb inlines its templates and includes them as methods. Not only is this fast, but given the nature of template variables, it also makes good sense. Not everyone is pleased, though. Many believe that Merb’s inlining of templates makes it only quasi-MVC because it effectively squeezes together the controllers and views. In this respect, Rails 3 will notably not stay with the Merb way of doing things.

From the Library of Shirong Chen

3.7

Rendering templates

91

3.7.2 Basic rendering In order to render a template, we use the controller method render. Note that render isn’t some magical method that takes control of your action. Instead it simply evaluates a template returning a string. Thus, it must be the final evaluation step on your controller action to have any effect. In the following modification of our first example, the rendered template is mistakenly not the final step of the action, and 'bye' ends up being the response instead: Merb::BootLoader.after_app_loads do vf = VirtualFile.new( "hi <%= @var %>", 'app/views/weird/index.html.erb') Merb::Template.inline_template(vf) end class Weird < Merb::Controller def index @var = 'friend' render 'bye' end end

The render method can take various parameters. The simplest of these is a string. When you render a string, the render method embeds the string within the layout (more on this later) or, if no layout is available, simply returns the string itself. Here is an example: class Example < Merb::Controller def index render "hello world" end end

3.7.3 Template The render method may alternatively take a symbol as one of its parameters. This switches the template to be rendered from the action name to a stringified version of the symbol. This is most commonly used to render a form when form submission has failed. We’ll see an example of this in Chapter 6 on helpers, but for now, here’s a simpler example based upon the first. Note how the template’s name has been changed. Merb::BootLoader.after_app_loads do vf = VirtualFile.new( "hi <%= @var %>",

From the Library of Shirong Chen

92

Chapter 3: Controllers

'app/views/weird/not_index.html.erb') Merb::Template.inline_template(vf) end class Weird < Merb::Controller def index @var = 'friend' render :not_index end end

Another way of specifying the template is to pass in an optional hash with :template with the template’s name as its value: class Weird < Merb::Controller def index @var = 'friend' render :template => :not_index end end

3.7.4 Formats We can also specify the format with which an action will be rendered. By default this format is HTML, but we can override this by using the hash key :format. Be aware that this requires that a template with that filename exists. Merb::BootLoader.after_app_loads do vf = VirtualFile.new( "{'response': 'hi <%= @var %>'}", 'app/views/weird/not_index.json.erb') Merb::Template.inline_template(vf) end class Weird < Merb::Controller def index @var = 'friend' render :format => :json end end

We can accomplish the same thing in two other ways. The first is setting the content_type, which may have been automatically set by the router from the value for

the route parameter format: class Weird < Merb::Controller def index

From the Library of Shirong Chen

3.7

Rendering templates

93

@var = 'friend' format_type = :json render end end

The second is using the method render_json. Merb adds a render_ prefixed method for each of the MIME types to which it can respond. Here we use it in our action: class Weird < Merb::Controller def index @var = 'friend' render_json end end

Occasionally there are several ways to do the same thing. Our recommendation is to stick with the simplest. Of course, deciding what that is, is a matter of opinion. We can also specify the formats provided by a controller when we want to be explicit. These can then be automatically specified as the formats in request parameters. The two methods that open up this possibility are provides and does_not_provide. Both of these are available as class and instance methods. The example below demonstrates both methods. Merb::Router.prepare do default_routes end Merb::BootLoader.after_app_loads do templates = [ VirtualFile.new( "{'response': 'hi <%= @var %>'}", 'app/views/weird/index.json.erb'), VirtualFile.new( "hi <%= @var %>", 'app/views/weird/index.html.erb'), VirtualFile.new( "Only in HTML", 'app/views/weird/extra.html.erb') ] templates.each do |t| Merb::Template.inline_template(t) end

From the Library of Shirong Chen

94

Chapter 3: Controllers

end class Weird < Merb::Controller provides :html, :json def index @var = 'friend' render end def extra does_not_provide :json render end end

3.7.5 Status You can also set the status code used in the response through render by setting :status to some integer. This, however, doesn’t actually affect the render itself but instead only incidentally sets the value of status used later by the Merb server in crafting the headers for the response. class Missing < Merb::Controller def index @var = 'friend - are you lost?' render :status => 404 end end

3.7.6 Layout A layout is a parent template in which a rendered template can be embedded. Layouts typically reside in app/views/layouts/. The default layout in a controller without a specified layout is app/views/layout/:controller.html.*, where :controller is the controller’s name in snake case. If that is not found, the controller looks for app/views/layouts/application.html.*. Either way, this also requires that we indicate where the render content should be placed. To do this we must use the method catch_content :for_layout. Below we put all of this together to produce the output "START hi friend FINISH": Merb::BootLoader.after_app_loads do vf = VirtualFile.new(

From the Library of Shirong Chen

3.7

Rendering templates

95

"START <%= catch_content :for_layout %> FINISH", 'app/views/layout/weird.html.erb') Merb::Template.inline_template(vf) vf = VirtualFile.new( "hi <%= @var %>", 'app/views/weird/index.html.erb') Merb::Template.inline_template(vf) end class Weird < Merb::Controller def index @var = 'friend' render end end

We can specify an alternative layout in various ways. We can do this controller-wide using the layout method. Alternatively, we can set it as the value of the :layout key in the render hash. Note that if we use the value nil, no layout will be used and the template will be rendered alone: class Example < Merb::Controller layout :elsewhere def index render :layout => nil end end

3.7.7 display An alternative way to render a template is to use the method display. In scenarios where there is an object that essentially forms the entirety of the response, this method may be a better fit than render, as it falls back on serialization of that object when an appropriate template isn’t found. We’ll use this effectively to handle multiple MIME templates, including XML and JSON, in Chapter 6. For now, the following contrived example shows the gist of the intent: Merb::BootLoader.after_app_loads do vf = VirtualFile.new( "hi", 'app/views/example/index.html.erb') Merb::Template.inline_template(vf) end

From the Library of Shirong Chen

96

Chapter 3: Controllers

class Example < Merb::Controller provides :html, :json, :xml def index obj = {:first => [1,2,3]} diplay obj end end

3.7.8 render_chunked Occasionally we may want to send data chunked to save on memory usage. This would make sense especially if we were going to send over a large log file that we were reading from a private location. In this example taken from the API, we pass the method render_chunked a block that contains looped calls to send_chunk: def stream prefix = '

' suffix = "

\r\n" render_chunked do IO.popen("cat /tmp/test.log") do |io| done = false until done sleep 0.3 line = io.gets.chomp if line == 'EOF' done = true else send_chunk(prefix + line + suffix) end end end end

3.7.9 render_deferred If we are using the Mongrel web server, then another method available to us is render_deferred. When we use it in place of render, we can pass in a block that is executed before the final rendering. Nonetheless, the Merb thread is not locked during its evaluation of the block and is capable of handling other requests. class Example < Merb::Controller def index render_deferred do

From the Library of Shirong Chen

3.9 Sending and streaming

97

sleep 10 end end end

3.7.10 render_then_call Another method available to us is render_then_call. This method renders normally, but the block it is given is called after the response is sent. Thus, this block is evaluated outside the request-to-response cycle, making it a great place to put responseindependent, time-intensive instructions: class Example < Merb::Controller def index render_then_call "hi there" do sleep 10 end end end

We hope that sleeping on the job isn’t actually part of your application’s specifications.

3.8 run_later A better way of calling a block later on is to use the web-server-agnostic run_later method. This method places the block into the worker queue and has it run at some point after the response is handled. We can use this extensively once again for timeintensive instructions that are not necessary for the controller response. Also, because run_later is essentially just a means of pushing blocks into a queue, we can have as many of them as we like. class Example < Merb::Controller def index run_later do sleep 10 end "hi" end

3.9 Sending and streaming Sending and streaming allow us to programmatically deliver data from inside controller actions. This may seem odd at first when you could simply serve a static resource, but there are scenarios when you’ll find this helpful. For sending, this may be when you want to

From the Library of Shirong Chen

98

Chapter 3: Controllers

protect a file behind filters that among other things authorizes users. In the case of streaming, it may be because files are large and serving them a chunk at a time saves memory.

3.9.1 Sending files The method for sending a file is simply send_file. It requires only a single parameter, the path to the file, but you can explicitly set the filename, disposition, and file type through an options hash. Below we send a file only if the request comes from an authenticated user. class Files < Merb::Controller before :ensure_authenticated def book send_file('/data/books/the_merb_way.pdf', :filename => 'understanding_merb.pdf') end end

3.9.2 Streaming files Streaming is the process of sending information to the client in chunks, which saves on memory when we’re dealing with large files. The Merb method stream_file offers this benefit. In the example below, we stream data from Amazon S3 containing a user’s video intro stream_file. class Users < Merb::Controller before :find_user, :only => %w{ video_intro } def video_intro stream_file({ :filename => filename, :type => content_type, :content_length => content_length }) do |response| AWS::S3::S3Object.stream(@user.login, bucket_name) do |chunk| response.write chunk end end end # ... end

From the Library of Shirong Chen

3.10

Conclusion

99

3.10 Conclusion Controllers are an essential part of any Merb application. In this chapter we exhibited their central importance by almost exclusively coding all the examples using only controllers. Our tour of features such as filters, exceptions, and rendering should already enable many application developers to get a head start on building Merb applications. As we move on to the next chapter on views, remember that controllers and views are internally tightly coupled within the framework; the next chapter is more a discussion of Merb’s interaction with templating engines than anything else.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 4

Views

While web services may need to serialize data only when sending responses, users typically interpret websites visually through HTML. Consequently, in order to better separate the formatting of data from its composition, the MVC paradigm pushes us toward the convenience of views. Within a Merb application, these concretely translate to using templates from which application responses are built. Not all templates are formatted in the same way, though, and some are better suited than others for particular work. Consequently, Merb has since its beginnings been able to hook into different templating engines. Working off the Erubis and Haml engines, Merb enables the two most common template formats, ERB and Haml. We will cover both of these in this chapter as well as more specifically how to use them within Merb itself. As we’ll discover, Merb also enhances these templates in various ways, sometimes fundamentally as in the case of the BlockAwareEnhancer but most of the time more mildly through the inclusion of helpers and local variables. Ultimately, views are a critical part of nearly every web application, but the Merb way of building applications has always been to minimize the amount of logic within them. While it’s easy to start employing Ruby to its full extent within views, we strongly advise considerable restraint while crafting views. Try pushing off relevant logic to helpers, controllers, or, better yet, models.

4.1 ERB ERB, more properly known as eRuby, is the default templating system used by Merb. Because it does not make any requirements on the structure of the templates, ERB is amazingly versatile and can produce any textual format you may need for output, including, among other formats, HTML and XML. It is worthwhile to mention that nearly all the files produced by merb-gen are created using ERB templates. 101 From the Library of Shirong Chen

102

Chapter 4: Views

Merb compiles ERB using the Erubis templating engine, an extremely fast implementation of ERB. You can use Erubis by itself outside Merb, and in order to introduce the basics of ERB, we’ll do just that.

4.1.1 Basic delimiters The are two principal delimiters used within ERB: <% %> and <%= %>. If you have experience with JSP or ASP, you’ll find that their use is identical. Of the two, the first executes code, and the second executes and then inserts the result into the template ouput. The following template exhibits both: <% if @name %> <%= "Hello #{@name}!" %> <% else %> <%= "Hey you!" %> <% end %>

We can excute the file using the command erubis. Here’s the result: $ erubis hello.erb Hey you!

We are also able to pass in values for the variables from the command line using -c: $ erubis -c "@name = 'Sophia'" hello.erb Hello Sophia!

4.1.2 Removing whitespace Unlike other ERB implementations, Erubis automatically trims whitespace from its execution-only delimiters. Output delimiters, however, include both leading and trailing whitespace. If necessary you can eliminate trailing newlines using the modified delimiter <%= -%>. This may not matter for an HTML file, but if you’re using ERB to format plain text or code, you’ll definitely appreciate its existence. As an example, the following script outputs the numbers 1 through 10 all on the same line. Note that we’ve included a final line break to compensate for its final suppression. <% (1..10).each do |i| %> <%= i -%> <% end %>

From the Library of Shirong Chen

4.1

ERB

103

4.1.3 Comments If you need to quickly cancel the effect of a line of ERB in a noncommittal way, the pound sign will do the trick. Because ERB interprets text delimited by <% %> as Ruby, squeezing in a # effectively puts a stop to both execution-only and output-delimited code: <%#= "Foiled again!" %>

4.1.4 Merb’s block-aware enhancer Unfortunately, standard ERB lacks the ability to execute multiline Ruby code split among multiple delimiters. In other words, the following simply will not work: <%= "Hey " + %> <% "there" %>

This may not seem problematic at first (who would ever need to do this?), but template helper methods often take blocks that sometimes cannot reasonably fit in one delimiter. Here’s a somewhat less contrived example of a helper using a block just to get the point across. Note that it does not work in standard ERB. <% def quote(&block) ''+block.call.to_s+'' end %> <%= quote do %> <% "HEY!" %> <% end %>

The work-around used by Rails (and most likely to be abandoned in the merge) has been to overload the use of execution-only delimiters through the inclusion of code in helper methods. This code first checks if the template being used is ERB or not and then forcefully outputs the result after interpreting the block. The Merb team turned away from this solution unsatisfied, and Yehuda Katz instead crafted an Erubis enhancer as an alternative solution. The BlockAwareEnhancer found in the Merb core does precisely what it says it does, enhancing ERB so that it can spot and use multiline blocks. This does come with one slight inconvenience, though: The ending line of a block must use a special tail character on its directive, <% =%>. With this in mind, let’s rewrite the previous nonworking example to make it suitable for use in Merb: <% def quote(&block) ''+block.call.to_s+''

From the Library of Shirong Chen

104

Chapter 4: Views

end %> <%= quote do %> <% "HEY!" %> <% end =%>

Note that no alteration of the helper method was needed. Let’s take a look at the source code behind the enhancer to get a better feel for how it was accomplished: module Erubis module BlockAwareEnhancer # :api: private def add_preamble(src) src << "_old_buf, @_erb_buf = @_erb_buf, ''; " src << "@_engine = 'erb'; " end # :api: private def add_postamble(src) src << "\n" unless src[-1] == ?\n src << "_ret = @_erb_buf; @_erb_buf = _old_buf; _ret.to_s;\n" end # ... # :api: private def add_stmt2(src, code, tailch) src << code src << " ).to_s; " if tailch == "=" src << ';' unless code[-1] == ?\n end # :api: private def add_expr_literal(src, code) if code =˜ /(do|\{)(\s*\|[ˆ|]*\|)?\s*\Z/ src << ' @_erb_buf.concat( ' << code << "; " else src << ' @_erb_buf.concat((' << code << ').to_s);' end end end class BlockAwareEruby < Eruby include BlockAwareEnhancer end end

From the Library of Shirong Chen

4.2

Haml

105

The final method, add_expr_literal, is where the hard work starts. Erubis calls this method while converting input when it finds a Ruby expression that should be outputted. In other words, lines of ERB surrounded with <%= ... %> are handled by this method. You’ll notice that the if statement in this method checks to see if the code ends with the beginning of a block. If it does, then it withholds the closing of the concat parameter. The add_stmt2 method is then used to recognize the added delimiter <% =%> and will close the concat parameter if it spots one. This method is unfortunately not a part of Erubis, and some monkey patching of the method convert_input can be found elsewhere in the Merb source.

4.2 Haml Haml is an alternative Ruby-infused templating language best suited for HTML and XML. Its focus is on terseness. If you are a web developer typically tortured with the verbosity of HTML and XML, this should come as a relief. Originally developed by Hampton Catlin, Haml is more recently maintained by Nathan Weizenbaum. A man is not always his work... As awesome as both Haml and Hampton Catlin are, if you run into Hampton, do not accidentally call him ‘‘Haml.” Others have done so, and he hates it.

As with ERB, you can create Haml files outside Merb and compile them into output. As we go through some examples, you may want to use haml from the command line to do just that.

4.2.1 Tags Tags in Haml are preceded by the percentage sign, %. You can use any of the standard HTML tags or dabble with your own creations as you please. Each Haml tag produces both open and close directives. For instance, the following: %div %span

produces the HTML output

<span>

From the Library of Shirong Chen

106

Chapter 4: Views

The content of a Haml tag can appear directly after it on the same line, separated by some whitespace. Content not belonging to any tag can also appear simply by itself. Obviously this is not valid HTML, but Haml sets no limitation upon it. Below we demonstrate a first header tag with content inline and then some content on a second line belonging to no tag. %h1 Welcome to Z----Com! Anything is possible.

This compiles to

Welcome to Z----Com!

Anything is possible.

4.2.2 Indentation Haml uses two-space indentation in order to indicate nesting. Any other form of indentation causes compilation errors, so watch out. Below we have nested a few common tags. Note that we can also choose to include tag content as if it were nested. %div %h1 AYB Are Belong to Us %span For Great Justice

This compiles to

AYB Are Belong to Us

<span>For Great Justice

4.2.3 IDs and classes Elements can also easily be given ID and class names. Prepend a # for IDs and a . for classes. Multiple classes can appear on a single element. Note that it is possible to use IDs and classes without explicitly specifying a tag, in which case a

tag is used. The lines #header %h1#logo YourSite! %table.users.full

translate to

From the Library of Shirong Chen

4.2

Haml

107

4.2.4 Attributes If you need to add nonclass, non-ID attributes to tags, you can do so in Haml using curly braces immediately following the IDs and class names of an element: %img{ :src => '/logo.png' }

This compiles down to

4.2.5 Interpreting lines Lines that begin with - are interpreted as code. Their results are not outputted and are thus perfectly suited for the conditional appearance of markup or content. Because of the significance of indentation in Haml, the - is also used to represent the encapsulation of code. Consequently, no end keywords are needed or should be used. Below we set the content of an element based upon the time of day. .message - if Time.now.hour > 6 Good Evening - else Good Day

4.2.6 Outputting lines Haml outputs the results of executed Ruby code when a = is used in place of -. The following example outputs the sum of two numbers: .quiz .question What is 2+2? .answer= 2+2

What is 2+2?

From the Library of Shirong Chen

108

Chapter 4: Views

Note that it is possible to simply append the = at the end of the tag specification. This is unlike the usage of the execution-only -.

4.2.7 Outputting string lines Though the = automatically converts all objects to strings before outputting them to the template buffer, you’ll indubitably find yourself needing to format the content of some elements. The easiest way to do this is to use a string replacement like this: - name = 'Sophia' = "Hi #{name}"

For brevity, we can even drop the quotation marks and use a double equals sign, ==: - name = 'Sophia' == Hi #{name}

This also frees up the usage of both single and double quote marks, allowing us to use both without the need for escaping.

4.2.8 Sanitized lines Haml has built-in support for sanitizing lines containing HTML-sensitive characters. This can prevent malicious (or accidental) HTML injections by mapping < and > to < and >. To do so, prepend either = or == with a &: &= "<script>alert('FIRE!');" &== Don't shout fire in a <script> tag.

4.2.9 Preserving whitespace You can use the tilde, ~, in place of the equals sign to preserve whitespace within elements where it’s needed. In particular, this applies to <pre> and "

Note that the output below preserves this whitespace through the special character .

From the Library of Shirong Chen

4.3

Merb view templates

109

4.2.10 Filters Haml is also able to support different template formats embedded within its usage. We can start a line (properly indented, of course) with a filter’s name in symbol form: %div :plain - Important Points - Listed One By One :erb <%= session.user.id %> :markdown #{@blog_entry.content} :textile #{comment.text}

Notice how we used Ruby code interpolation in the final two filters to pass in instance variables for use with filters. Haml versus inline styles Chances are you’ve run into HTML like the following at one point or another and wondered how you could accomplish the same thing in Haml: <strong>Don't forget: inline styles are <em>not good for your health. Well, there are a couple of ways of pulling it off. The first is to simply include the tags as part of the unsanitized content of some element. For instance, here we set the lines above as the value of a span: %span <strong>Don't forget: inline styles are <em>not good for your health. The second is to use a filter as a work-around. We use a plain filter below, but an ERB filter would work equally well. :plain <strong>Don't forget: inline styles are <em>not good for your health.

4.3 Merb view templates The view templates of a Merb application are stored within the directory app/views/. Conventionally, each controller associates with a subdirectory, and each of its actions

From the Library of Shirong Chen

110

Chapter 4: Views

is handled by templates contained within. So, for example, the controller Users has its view templates located within app/views/users/, which may contain files like index.html.haml or show.html.erb. Such templates are used when we call the method render or display inside of the controller action: class Users < Application def index @users = User.all render end def show(id) @user = User.get!(id) display @user end end

Remembering that the controller and view code are tightly coupled within Merb, we can find the private method within the controller render mixin that when called by render looks for these template files. It’s called _template_for: module Merb::RenderMixin::ClassMethods def _template_for(context, content_type, controller=nil, template=nil, locals=[]) tmp = self.class._templates_for[[context, content_type, controller, template, locals]] return tmp if tmp template_method, template_location = nil, nil if template.is_a?(String) && template =˜ %r{ˆ/} template_location = self._absolute_template_location( template, content_type) return [ _template_method_for(template_location, locals), template_location ] end self.class._template_roots.reverse_each do |root, template_meth| # :template => "foo/bar.html" where

From the Library of Shirong Chen

4.4

Partials

111

# root / "foo/bar.html.*" exists if template template_location = root / self.send( template_meth, template, content_type, nil) # :layout => "foo" where # root / "layouts" / "#{controller}.html.*" exists else template_location = root / self.send( template_meth, context, content_type, controller) end break if template_method = _template_method_for( template_location.to_s, locals) end # template_location is a Pathname ret = [template_method, template_location.to_s] unless Merb::Config[:reload_templates] self.class._templates_for[[context, content_type, controller, template, locals]] = ret end ret end end

Note that this code first checks from a memoized list to see if a matching template has previously been found. If not, it proceeds to look for one in each of the template roots (of which there is typically only a full path to "app/views"), finding what it can. You may also spot the use of the pathname method /. Many of the methods shown above have been defined elsewhere, and the interested reader can discover a layering of AbstractController and Controller methods in that mixin method.

4.4 Partials Partials are subtemplates used within view templates. To incorporate them, we can use the method partial within a view. Here we do so in both ERB and then in Haml: # app/views/users/index.html.erb <% @user.each do |u| %> <%= partial 'users/preview', :user => u %> <% end %>

From the Library of Shirong Chen

112

Chapter 4: Views

# app/views/users/index.html.haml - @users.each do |u| = partial 'users/preview', :user => u

The partial method takes as a first argument the path to the template. For example, above the path is 'users/preview'. There is one subtlety, however: Actual partial template files begin with an underscore. Thus, the path of the preview template is actually app/views/user/_preview.html.haml, possibly varying in template extension. The hash that forms the second and optional parameter on partial represents the local variables that are inserted and available to the partial.

4.5 Conclusion It’s our recommendation that all Ruby web developers become comfortable with both ERB and Haml. While ERB’s versatility makes it a tool capable of every job, Haml’s brevity outshines ERB when targeting HTML and XML. As far as Merb is concerned, either works well, and as we’ve seen through the creation of the Erubis BlockAwareEnhancer, little of the core’s rendering code has to be aware of which templating engine is being used.

From the Library of Shirong Chen

C HAPTER 5

Models

Models are related data and algorithms that respectively represent the properties and behaviors of domain objects used within an application. Models are used in nearly every decently complex object-oriented application because they organize application data in object form. Within the scope of a typical Merb application, examples of modeled objects may include users, posts, entries, or comments. These objects are most often persisted in a database through the use of an Object Relational Mapper, or ORM. As agnosticism has been central to Merb’s design, application developers are free to integrate whatever Ruby ORM they may need. Nonetheless, the default ORM included as part of the standard Merb stack is DataMapper, an ActiveRecord-like ORM that aims to push the boundaries of object-data interaction even more significantly toward the object side. Given its acceptance as part of the standard Merb stack, we will cover the use of only DataMapper in this chapter. However, don’t let that stop you from using ActiveRecord, Sequel, or any of the other options, since each of these ORMs is capable of creating, retrieving, updating, and deleting persisted data and is fully supported by the Merb core.

5.1 Conﬁguration Prior to being able to use the DataMapper ORM within your Merb application, you will have to make sure that you have done three things: • Included the DataMapper dependencies within config/dependencies.rb • Selected DataMapper as the ORM in init.rb • Configured your database connection in config/database.yml

113 From the Library of Shirong Chen

114

Chapter 5: Models

However, if you used merb-gen to generate a standard application and have SQLite3 installed, then you’ll find that all of these are already covered for you. If your application was generated in some other manner, you may want to see Chapter 1 to figure out how your configuration files should be laid out. Other standard dependencies The standard Merb generator inserts several other DataMapper dependencies into the file config/dependencies.rb. These commonly used DataMapper plugins provide functionality such as migrations, automatic timestamping, validations, and record aggregation. You are free to comment out or remove any of these dependencies, but as we’ll see through examples, even the most basic application models tend to want them to be available.

DataMapper works with several different database back ends. Support for MySQL, PostgreSQL, and SQLite3 are all included via the DataMapper core. If you’re using another database application, you may be able to find an appropriate adapter in the dm-more or dm-adapters gems. Alternatively, if your computer has the memory for it, there’s a DataMapper adapter that will store your model records completely in memory. Not just databases When you use DataMapper, you aren’t limited to interacting only with conventional databases. Instead, the DataMapper concept of a repository applies equally well to just about any data source composed of records. This includes numerous web service APIs where CRUD-like operations are available. A great example of such an adapter is the Salesforce adapter Yehuda Katz has written. In just under 300 lines of code, the adapter provides full DataMapper interaction via the Salesforce API. You’ll find that these adapters can also be used to augment models through secondary repositories, which is commonly the case when using Bernerd Schaefer’s full-text-search Ferret adapter.

Repository configuration is done in a YAML file named config/database.yml. The standardly generated config/database.yml file is broken into four environments—development, test, production, and rake—corresponding to the environments that are standardly used by a Merb application. If you have another environment—for instance, a staging environment—it, too, can be listed in this file.

From the Library of Shirong Chen

5.2

Model classes

115

Typically there is overlap in the configuration of environments, so YAML node anchors and aliases are used to reduce redundancy. What’s a YAML node? YAML nodes are named blocks of content in a YAML file. You can set up an anchor to the content of a node by using an ampersand and word after the naming of the node. Below we connect the content of development with the anchor &default. development: &default adapter: mysql database: example_development We can reference this anchor by using the alias *default later on. If we use this alias as the value on a merge key, <<, it will include the previously defined content. Here we merge in the defaults from before and then override the value for the database: test: <<: *default database: example_test

5.2 Model classes Model classes exist in the directory app/models. These classes typically have singular names and exist one class per file. Examples that may appear in a Merb blog application are Post in the file app/models/post.rb and FavoriteLink in app/models/ favorite_link.rb. Organizing model classes in this way isn’t strictly necessary, though, since Merb by default includes everything inside app/models by recursive glob. In other words, so long as you make sure that your model class is somewhere in app/ models, it will be available at boot. Nonetheless, our recommendation is that you do arrange your model classes in a reasonable way, so that both you and others can easily find them. While various DataMapper modules can incorporate different functionality within your model class, the fundamental module that must be included in order for your class to work with DataMapper is DataMapper::Resource. Below we include this module and effectively set up our User class as a DataMapper model. class User include DataMapper::Resource end

From the Library of Shirong Chen

116

Chapter 5: Models

Design decision: resource module versus base class DataMapper model classes are not created through inheritance from an abstract base class. If you’ve used ActiveRecord, which does do so, you may wonder why this alternate design decision has been made. Interestingly enough, early versions of DataMapper did actually use a parent class called DataMapper::Base. With time, however, the developers of DataMapper grew concerned that this was conceptually coupling application logic with DataMapper’s own. In other words, application models are more reasonably thought of as being enhanced through database persistence rather than as stemming off a library’s base class that provides such functionality. In some ways, this design decision can be seen as an application of the Principle of Substitutability, which insists that subtypes are capable of replacing their parents without affecting the correctness of the program. While this principle doesn’t exactly translate well when using Ruby (proving correctness through types isn’t anywhere near Ruby’s slant), we can learn from the principle by recognizing that inheritance is best used when a subclass makes no behavioral constraining modifications on the parent.

Let’s take a look at the source behind the Resource module to get a feel for how it affects the class in which it is included: module DataMapper module Resource # ... # @api public def self.append_inclusions(*inclusions) extra_inclusions.concat inclusions true end def self.extra_inclusions @extra_inclusions ||= [] end # When Resource is included in a class this # method makes sure it gets all the methods # # # @api private def self.included(model) model.extend Model model.extend ClassMethods

From the Library of Shirong Chen

5.2

Model classes

117

if defined?(ClassMethods) model.const_set('Resource', self) unless model.const_defined?('Resource') extra_inclusions.each { |inclusion| model.send(:include, inclusion) } descendants << model class << model @_valid_model = false attr_reader :_valid_model end end # ... end end

Focusing on the last method listed above, we can see that the Resource module extends the class in which it is included (above called model). In the process, it principally extends it with the Model module, which contains the logic for property persistence and object retrieval. As we come to these methods later on, we’ll open up the Model class source as well. For now, however, take note of Resource’s ability to include extra modules through the class method append_inclusions. This method is used extensively by DataMapper plugins that need to extend the functionality of all DataMapper models. For instance, below is some of the source for dm-timestamps, which automatically sets timestamps on properties of particular names. module DataMapper module Timestamp Resource.append_inclusions self # ... def self.included(model) model.before :create, :set_timestamps model.before :update, :set_timestamps model.extend ClassMethods end end end

The first line appends the module to all DataMapper models. Later on, using its own self.included, the module includes its own logic into the model. This cascading of modules is thus particularly effective for code as modular as DataMapper.

From the Library of Shirong Chen

118

Chapter 5: Models

5.3 Properties Each DataMapper model is able to persist its data. The kind of data it is able to store is defined through its properties. If you’re using a typical database, these properties correlate with the columns of the model’s corresponding table. Below is an example of a DataMapper model with three properties. class TastyAnimal include DataMapper::Resource property :id, Serial property :name, String property :endangered, TrueClass end

In many ways, you can think of properties as persistent accessors. In fact, taking a look into the source of the property method (found in the Model resource we spoke about earlier), we find that a dynamic getter and setter are created using class_eval: def property(name, type, options = {}) property = Property.new(self, name, type, options) create_property_getter(property) create_property_setter(property) # ... end # ... # defines the getter for the property def create_property_getter(property) class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ #{property.reader_visibility} def #{property.getter} attribute_get(#{property.name.inspect}) end EOS # ... end # defines the setter for the property def create_property_setter(property) unless instance_methods.include?("#{property.name}=")

From the Library of Shirong Chen

5.3

Properties

119

class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ #{property.writer_visibility} def #{property.name}=(value) attribute_set(#{property.name.inspect}, value) end EOS end end

The most important thing to learn from the source shown above is that properties dynamically create getter and setter methods. Additionally, these methods can end up protected or private through visibility attributes. Finally, the getters and setters produced are not exactly equivalent to attr_reader and attr_writer because of their internal use of the methods attribute_get and attribute_set. Going back to the Resource source, we can find these two methods manipulating the values of model properties, once again located in Model. You’ll have to excuse this volleying back and forth, but the point of the Resource and Model modules is to separate individual resource methods from those related to the model as a whole. # @api semiplugin def attribute_get(name) properties[name].get(self) end # @api semipublic def attribute_set(name, value) properties[name].set(self, value) end protected def properties model.properties(repository.name) end

You may have noticed the @api semipublic comment above the getter and setter methods. This is because application developers should not ordinarily need to use these methods. Plugin developers, on the other hand, may need to use them as the easiest way to get and set properties while making sure they are persisted. For application developers, however, this does bring up one important point: Do not use instance variables to set property values. The reason is that while this will set the object’s value, it will unfortunately short-circuit the model code that is used to track whether a property is dirty. In other words, the property value may not persist later upon

From the Library of Shirong Chen

120

Chapter 5: Models

save. Instead, you should use the actual property method. Below you’ll find an example with comments that should get the point across. class Fruit include DataMapper::Resource property :id, Serial property :name, String property :eaten, TrueClass def eat unless eaten? # will not persist upon save @eaten = true # will persist upon save eaten = true end end end

Before we describe the extended use of properties, let’s take a look at the database side to understand how persistence works.

5.3.1 Database storage In order to persist the data of model objects, we need to set up our database for that data to be stored. The default-generated configuration files use a SQLite3 database file called sample_development.db. This setup is perfect for most development scenarios given its quickness to get up and running. With that in mind, we’d say stick with it whenever possible, leaving the alteration of config/database.yml for production or staging environments. Create your database with rake If you are using MySQL or PostgreSQL for development, though, it may be useful to know that there is a Merb DataMapper rake task that can create your database for you. After making sure your config/database.yml file contains the appropriate username and password, rake db:create issues the database admin command you may have otherwise forgotten.

From the Library of Shirong Chen

5.3

Properties

121

5.3.1.1 Automigrating the DB schema Databases typically need to be prepped for the data they will store during application development. The process by which DataMapper does this is called automigration, because DataMapper uses the properties listed in your models to automatically create your database schema for you. Using the provided Merb DataMapper rake task, we can automigrate the model that we created earlier and then take a peek inside the database to see what was done: $ rake db:automigrate $ sqlite3 sample_development.db sqlite> .tables tasty_animals sqlite> .schema CREATE TABLE "tasty_animals" ("id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, "name" VARCHAR(50), " is_endangered" BOOLEAN);

As you can see, a table with a pluralized and snake-cased name was created for our model, TastyAnimal. Remembering the various properties of the model class, we can also spot corresponding columns inside the schema’s CREATE statement. Note that while Ruby classes were used on the property lines, standard SQL types appear in the database. Design decision: emphasize the model as an object DataMapper has notably chosen to include properties within the model files. Those familiar with ActiveRecord may find this odd, having been accustomed to distributing schema information across migration files. There are, however, a number of benefits to the DataMapper way of handling properties, including

• An explicitness that helps developers understand how a model is used • An ability to work around legacy systems far more easily due to the lack of schema dependence

• The possibility of distributing model property persistence across multiple databases or repositories

• The time-saving nature of automigrations These benefits may take a while to appreciate given their subtleness, but there is a more general paradigm shift going on that we should mention: The inclusion and use of properties in DataMapper model classes essentially pushes the ORM concept even further object-side, where the resulting combination of less magic and less maintenance is a total win.

From the Library of Shirong Chen

122

Chapter 5: Models

The code behind automigration is definitely worth studying, so let’s take a look at the module AutoMigrations, which includes itself within the Model module: module DataMapper module AutoMigrations def auto_migrate!(repository_name = self.repository_name) auto_migrate_down!(repository_name) auto_migrate_up!(repository_name) end # @api private def auto_migrate_down!(repository_name = self.repository_name) # repository_name ||= default_repository_name repository(repository_name) do |r| r.adapter.destroy_model_storage(r, self.base_model) end end # @api private def auto_migrate_up!(repository_name = self.repository_name) repository(repository_name) do |r| r.adapter.create_model_storage(r, self.base_model) end end def auto_upgrade!(repository_name = self.repository_name) repository(repository_name) do |r| r.adapter.upgrade_model_storage(r, self) end end Model.send(:include, self) end # module AutoMigrations end # module DataMapper

From the Library of Shirong Chen

5.3

Properties

123

As you can see, there are two API public class methods you can use with models, auto_migrate! and auto_upgrade!. These effectively call the three adapter methods destroy_model_storage, create_model_storage, and upgrade_model_ storage. Let’s go deep into the source and see how these three methods do the heavy lifting: class DataMapper::Adapters::AbstractAdapter module Migration def upgrade_model_storage(repository, model) table_name = model.storage_name(repository.name) if success = create_model_storage(repository, model) return model.properties(repository.name) end properties = [] model.properties(repository.name). each do |property| schema_hash = property_schema_hash(repository, property) next if field_exists?(table_name, schema_hash[:name]) statement = alter_table_add_column_statement( table_name, schema_hash) execute(statement) properties << property end properties end def create_model_storage(repository, model) return false if storage_exists?( model.storage_name(repository.name)) execute(create_table_statement(repository, model))

From the Library of Shirong Chen

124

Chapter 5: Models # ... create indexes true end def destroy_model_storage(repository, model) execute(drop_table_statement(repository, model)) true end

end end

The simplest of these, destroy_model_storage, executes a drop table statement. The create_model_storage method, on the other hand, first checks to see if the model storage already exists, returning false if it does or true if it does not, and consequently has the chance to create it. Finally, upgrade_model_storage is the most complicated of the three. It first attempts to create the storage (effectively testing whether it exists or not) and then attempts to add new columns for new properties. This leaves existing data in place and is perfect if you have simply added properties to a column. Lest this appear to be no more than hand waving, let’s dig even deeper into the methods that the AbstractAdapter uses to create the SQL for these statements: class DataMapper::Adapters::AbstractAdapter # immediately following the previous code module SQL private def alter_table_add_column_statement(table_name, schema_hash) "ALTER TABLE "+ quote_table_name(table_name)+ "ADD COLUMN "+ property_schema_statement(schema_hash) end def create_table_statement(repository, model) repository_name = repository.name statement = <<-EOS.compress_lines CREATE TABLE #{quote_table_name(

From the Library of Shirong Chen

5.3

Properties

125

model.storage_name(repository_name))} (#{model.properties_with_subclasses( repository_name).map { |p| property_schema_statement( property_schema_hash(repository, p)) } * ', '} EOS if (key = model.key(repository_name)).any? statement << ", PRIMARY KEY(#{ key.map { |p| quote_column_name(p.field(repository_name)) } * ', '})" end statement << ')' statement end def drop_table_statement(repository, model) "DROP TABLE IF EXISTS "+ quote_table_name(model.storage_name( repository.name)) end def property_schema_hash(repository, property) schema = self.class.type_map[property.type]. merge(:name => property.field(repository.name)) if property.primitive == String && schema[:primitive] != 'TEXT' schema[:size] = property.length elsif property.primitive == BigDecimal || property.primitive == Float schema[:precision] = property.precision schema[:scale] = property.scale end schema[:nullable?] = property.nullable? schema[:serial?] = property.serial? if property.default.nil? || property.default.respond_to?(:call) schema.delete(:default) unless property.nullable?

From the Library of Shirong Chen

126

Chapter 5: Models else if property.type.respond_to?(:dump) schema[:default] = property.type.dump( property.default, property) else schema[:default] = property.default end end schema end def property_schema_statement(schema) statement = quote_column_name(schema[:name]) statement << " #{schema[:primitive]}" if schema[:precision] && schema[:scale] statement << "(#{[ :precision, :scale ].map { |k| quote_column_value(schema[k]) } * ','})" elsif schema[:size] statement << "("+ quote_column_value(schema[:size])}+")" end

statement << ' NOT NULL' unless schema[:nullable?] statement << " DEFAULT " + quote_column_value(schema[:default]) if schema.has_key?(:default) statement end end include SQL end

The first thing you may notice is that the methods are included within a module called SQL and that the module is included immediately after it is closed. The reason for this is that within DataMapper adapters, code is often organized by use, and thus the encapsulation of private methods into a module easily allows for alternating regions of public and then private methods. Now, turning to the actual methods, we can see that some of them—for instance, drop_table_statement—are just a line of simple SQL. Likewise, alter_ table_column_statement is just a single line that outputs add column statements.

From the Library of Shirong Chen

5.3

Properties

127

The create_table_statement, however, is far more complex, relying on various other methods to get its work done. One of these, properties_with_subclasses, pulls up all model properties, including those that are simply keys used with relationships. We’ll go further into properties_with_subclasses later on when we examine model relationships, but for now let’s take a look at the method property_schema_statement, which quotes the property as a column name and then appends its type. It also adds the appropriate SQL for decimals, non-nullables, and default values. We hope this has brought you deep enough into the inner workings of automigration to both appreciate its design and get a feel for how adapter code handles the production of SQL more generally. But it would also be nice to be able to use some of it practically, and thankfully you can do so. For instance, if you’re in mid-development, you may fire up interactive Merb and use auto_upgrade! on a model to which you’ve added properties: > Fruit.auto_upgrade!

Likewise, you may want to refresh the data of a model using auto_migrate! in the middle of a test file. Here’s an example we’ve spotted in the wild: before :each do Invite.auto_migrate! end

5.3.2 Defining properties Let’s now take a more rigorous look at properties as well as the options we have while defining them. As we’ve seen, each property is defined on its own line by using the method property. This class method is mixed in via the inclusion of DataMapper::Resource. It takes a minimum of two arguments, the first being a symbol that effectively names the property and the second being a class that defines what type of data is to be stored. As we will see soon, an optional hash of arguments may also be passed in.

5.3.2.1 Property types While abstracting away the differences across database column types, DataMapper has chosen to stay true as much as possible to using Ruby to describe properties types. Below is a list of the various classes supported by the DataMapper core. Note that the inclusion of DataMapper::Resource will include DM in your model class, and that when defining properties, you will not have to use the module prefix DM:: before those that use it.

From the Library of Shirong Chen

128

Chapter 5: Models

• Class—stores a Ruby Class name as a string. Intended for use with inheritance,

primarily through the property type DM::Discriminator. • String—stores a Ruby String. Default maximum length is 50 characters. Length

can be defined by the optional hash key :length. • Integer—stores a Ruby Integer. Length can be defined by the optional hash key :length.

• BigDecimal—stores a Ruby BigDecimal, intended for numbers where decimal

exactitude is necessary. Can use the option hash keys :precision and :scale. • Float—stores a Ruby Float. Primarily intended for numbers where decimal

exactitude is not critical. Can use the two options hash keys :precision and :scale. • Date—stores a Ruby Date. • DateTime—stores a Ruby DateTime. • Time—stores a Ruby Time. • Object—allows for the marshaling of a full object into a record. It is serialized into

text upon storage and when retrieved is available as the original object. • TrueClass—a Boolean that works with any of the values in the array [0, 1, 't', 'f', true, false]. In MySQL it translates down to a tinyint, in PostgreSQL a

bool, and in SQLite a boolean. • DM::Boolean—an alias of TrueClass. This is around for legacy DataMapper

support, simply to provide a more commonly recognized name for the type. • Discriminator—stores the model class name as a string. Used for single-table

inheritance. • DM::Serial—used on the serial ID of a model. Serial IDs are auto-incremented

integers that uniquely apply to single records. Alternatively, a property can use the Integer class and set :serial to true. You will nearly always see this type applied

to the id property. • DM::Text—stores larger textual data and is notably lazy-loaded by default.

You may be interested in knowing how the casting in and out of property values works. For the primitive types, values coming out of the database are cast using the method Property#typecast. Below we see how this methods prunes results, modifying them into what we want in Ruby.

From the Library of Shirong Chen

5.3

Properties

129

def typecast(value) return type.typecast(value, self) if type.respond_to?(:typecast) return value if value.kind_of?(primitive) || value.nil? begin if primitive == TrueClass %w[ true 1 t ].include?(value.to_s.downcase) elsif primitive == String value.to_s elsif primitive == Float value.to_f elsif primitive == Integer value_to_i = value.to_i if value_to_i == 0 value.to_s =˜ /ˆ(0x|0b)?0+/ ? 0 : nil else value_to_i end elsif primitive == BigDecimal BigDecimal(value.to_s) elsif primitive == DateTime typecast_to_datetime(value) elsif primitive == Date typecast_to_date(value) elsif primitive == Time typecast_to_time(value) elsif primitive == Class self.class.find_const(value) else value end rescue value end end

Custom types, however, are handled by subclasses of an abstract type class called DataMapper::Type. These load and dump data in whatever way they are programmed

to do. We’ll see custom types later on when we examine some DataMapper-type plugins, but for now let’s take a look at one of the custom types from the DataMapper core, Serial: module DataMapper module Types class Serial < DataMapper::Type primitive Integer

From the Library of Shirong Chen

130

Chapter 5: Models

serial true end # class Text end # module Types end # module DataMapper

Note its use of the methods primitive and serial, which are defined in the class DataMapper::Type: class DataMapper:Type PROPERTY_OPTIONS = [ :accessor, :reader, :writer, :lazy, :default, :nullable, :key, :serial, :field, :size, :length, :format, :index, :unique_index, :check, :ordinal, :auto_validation, :validates, :unique, :track, :precision, :scale ] # ... class << self PROPERTY_OPTIONS.each do |property_option| self.class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ def #{property_option}(arg = nil) return @#{property_option} if arg.nil? @#{property_option} = arg end EOS end def primitive(primitive = nil) return @primitive if primitive.nil? @primitive = primitive end # ... end end

From this we can first see that the primitive method sets the type to which the property value should be dumped. The serial method, on the other hand, is an example of the property option, which we’re about to address.

From the Library of Shirong Chen

5.3

Properties

131

5.3.2.2 Option hash The third argument that the property method can take is an option hash, which affects various behavioral aspects of the property. For instance, below we’ve specified that a property should default to some value. class Website include DataMapper::Resource property :id, Serial property :domain, String property :color_scheme, String, :default => 'blue' end

Here’s a list of the various property options and their uses: • :accessor—takes the value :private, :protected, or :public. Sets the access

privileges of the property as both a reader and a writer. Defaults to :public. • :reader—takes the value :private, :protected, or :public. Sets the access

privileges of the property as a reader. Defaults to :public. • :writer—takes the value :private, :protected, or :public. Sets the access

privileges of the property as a writer. Defaults to :public. • :lazy—determines whether the property should be lazy-loaded or not. Lazy-loaded

properties are not read from the repository unless they are used. Defaults to false on most properties, but is notably true on DM::Text. • :default—sets the default value of the property. Can take any value appropriate

for the type. • :nullable—if set to true it will disallow a null value for the property. When dm-validations is used this invalidates a model.

• :key—defines a property as the table key. This allows for natural keys in place of

a serial ID. This key can be used as the index on the model class in order to access the record. • :serial—sets the property to be auto-incremented as well as to serve as the table

key. • :field—manually overrides the field name. Best used for legacy repositories. • :size—sets the size of the property type. • :length—alias of :size.

From the Library of Shirong Chen

132

Chapter 5: Models

• :format—used with the String property type. When used with a dmvalidations format can set a regular expression against which strings must validate.

• :index—sets the property to be indexed for faster retrieval. If set to a symbol instead

of to true, it can be used to create multicolumn indexes. • :unique_index—defines a unique index for the property. When used with dmvalidations, new records with nonunique property values are marked invalid. If

set to a symbol instead of true, it can be used to create multicolumn indexes. • :auto_validation—when used with dm-validations, can be used to turn off

autovalidations by using the value true. • :track—determines when a property should be tracked for dirtiness. Takes the

values :get, :set, :load, and :hash. • :precision—sets the number of decimal places allowed for BigDecimal and Float type properties.

• :scale—sets the number of decimal places after the decimal point for BigDecimal

and Float type properties.

5.4 Associations DataMapper also supports the defining of associations between models. If you’ve used ActiveRecord before, these are nearly the same. Otherwise, know that associations allow you to define the relationships between models (one-to-one, one-to-many, etc.), automatically creating database keys where necessary while also making it possible to conveniently pull up related model objects from associates. Let’s survey the various relationships possible with DataMapper. Design decision: generalized association methods The largest distinction between DataMapper and ActiveRecord associations is DataMapper’s use of only two methods, has and belongs_to. This differs from ActiveRecord’s one method per association type and has benefited DataMapper through simplicity of both internal design and interface. We’ll see the elegance of the internal design later on, but know that these two generalizations allow application developers to simplify the cognitive steps needed to arrive at the appropriate associations. That is, to determine if an association should use has or belongs_to, you only need to ask whether a related model key should maintain a property for the ID of the other model. Moving from here, you can then define the cardinality and pathway of the

From the Library of Shirong Chen

5.4

Associations

133

relationship if necessary. This may not seem like anything special to an experienced developer, but we’ve found that this easing of an interface’s learning curve tends to be indicative of cleaner design, making it a win-win situation for everyone.

5.4.1 Belongs to In general, you should know that a belongs-to association is meant to help you quickly retrieve an associated resource by defining a one-to-something association between two models (specifically, a child and its parent), where the child class should store its parent’s key as a property. So, for instance, the following associates a comment with a user: class Comment include DataMapper::Resource property :id, Serial property :body, Text belongs_to :user end

Note that upon automigration the belongs-to association automatically creates the column user_id within the comments table. This means that any model object now has two new methods accessible, user_id and user. The first is simply the ID of the associated user, but the second actually retrieves the user resource for you. These defaults may not always fit your domain logic, however, so they can be altered. class Paper include DataMapper::Resource property :id, Serial property :body, Text belongs_to :author, :class_name => "User", :child_key => [:author_id] belongs_to :reviewer, :class_name => "User", :child_key => [:reviewer_id] end

Here we have two user objects parenting our paper object. To handle ambiguity, we use the hash keys class_name and child_key. The first is a string representation of the parent class name, and the second is an array indicating how the key should be stored within our child. At the end this produces the methods author_id, reviewer_id,

From the Library of Shirong Chen

134

Chapter 5: Models

author, and reviewer on papers, where the first two are essentially association prop-

erties and the second two are means of retrieving the associated objects. Let’s take a look at how the belongs_to magic is performed: module DataMapper::Associations def belongs_to(name, options={}) @_valid_relations = false if options.key?(:class_name) && !options.key?(:child_key) warn "..." # must set both end relationship = ManyToOne.setup(name, self, options) end end module DataMapper::Associations::ManyToOne # Set up many-to-one relationship between two models # # @api private def self.setup(name, model, options = {}) assert_kind_of 'name', name, Symbol assert_kind_of 'model', model, Model assert_kind_of 'options', options, Hash repository_name = model.repository.name model.class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ def #{name} #{name}_association.nil? ? nil : #{name}_association end def #{name}=(parent) #{name}_association.replace(parent) end private def #{name}_association @#{name}_association ||= begin unless relationship = model.relationships( #{repository_name.inspect})[:#{name}]

From the Library of Shirong Chen

5.4

Associations

135

raise ArgumentError, "Relationship #{name.inspect} "+ "does not exist in \#{model}" end association = Proxy.new(relationship, self) child_associations << association association end end EOS model.relationships(repository_name)[name] = Relationship.new( name, repository_name, model, options.fetch(:class_name, Extlib::Inflection.classify(name)), options ) end end

Starting with the Associations module, we can see that belongs_to fires off the creation of a many-to-one association. Moving on to ManyToOne.setup, we find extensive class evaluation where new methods for the association are defined. These allow us to get or set the association. Note that the reader method essentially proxies to the parent model (using a Proxy class later defined within ManyToOne). It also employs the Relationship class, DataMapper’s most generalized way of storing information on associations within model classes. Finally, note that the use of ManyToOne does not strictly indicate that the relationship between the two models needs to be many-to-one. It may indeed be one-to-one (as determined within the other model), but from the perspective of the child model the more generalized ManyToOne class is appropriate for handling both possibilities.

5.4.2 Has At this point you may be wondering about the flip side of the relationship, that is, the parent. Has associations are meant to handle this. The characteristics of has associations, however, differ in that they are meant to associate varying numbers of related model resources without storing information within the model object itself.

From the Library of Shirong Chen

136

Chapter 5: Models

Let’s create the counterpoint of the comment model we created in the previous section: class User include DataMapper::Resource property :id, Serial property :login, String, :nullable => false has n, :comments end

Note that the has method takes a minimum of two parameters. The first of these is the cardinality, which may be specified by a number, series, or n, and the second is the symbolized name of the associated class. If you’re scratching your head over n, just know that it is equivalent to 1.0/0 and that it allows an indefinite number of associates. If you’re coming from the ActiveRecord world, you can think of this as the “many” in has_many. As we did before, we can tweak our relationship for the sake of the domain logic: class User include DataMapper::Resource property :id, Serial property :login, String, :nullable => false has 1, :authored_papers, :class_name => "Paper", :child_key => [:author_id], :remote_name => :author has n, :reviewed_papers, :class_name => "Paper, :child_key => [:reviewer_id], :remote_name => :reviewer end

There are plenty of things to notice this time. Once again, we’ve specified the associated class name along with the child_key, but we’ve also set remote_name, which is the symbolized name of the relationship in our other model. Last, note that we set the cardinality of the first to 1, which limits users to authoring only one paper, effectively making the relationship one-to-one. Having now seen the use of has, let’s go into the source to understand how it works: module DataMapper::Associations def has(cardinality, name, options = {})

From the Library of Shirong Chen

5.4

Associations

137

if name.kind_of?(Hash) name_through, through = name.keys.first, name.values.first end options = options.merge( extract_min_max(cardinality)) options = options.merge( extract_throughness(name)) # ... some warnings klass = options[:max] == 1 ? OneToOne : OneToMany # ... we'll show you later relationship = klass.setup( options.delete(:name), self, options) end private def extract_min_max(constraints) assert_kind_of 'constraints', constraints, Integer, Range unless constraints == n case constraints when Integer { :min => constraints, :max => constraints } when Range if constraints.first > constraints.last raise ArgumentError, "..." end { :min => constraints.first, :max => constraints.last } when n { :min => 0, :max => n } end end end

From this we can see that has_many, like belongs_to, creates an association, but that it may be OneToOne or OneToMany based upon the max cardinality. Because we’ve already looked inside one of these associations and because the others are set up in similar ways, we’ll leave it up to you to explore further if you like.

From the Library of Shirong Chen

138

Chapter 5: Models

5.4.3 Has through You may need to work with one-to-many-through or many-to-many relationships. To handle these, DataMapper uses through. Let’s tackle one-to-many-through first and then take a look at many-to-many relationships: class Post include DataMapper::Resource has n, :taggings has n, :tags, :through => :taggings end class Tagging include DataMapper::Resource belongs_to :post belongs_to :tag end class Tag include DataMapper::Resource property :id, Serial property :value, String has n, :taggings has n, :posts, :through => :taggings end

These examples show us three associated models where the Tagging class acts like a join table bridging the one-to-many relationships from both sides. Sometimes, though, you don’t want to explicitly define this middle table. DataMapper lets you do this by setting through to Resource: class Post include DataMapper::Resource has n, :post has n, :tags, :through => Resource end class Tag include DataMapper::Resource property :id, Serial property :value, String

From the Library of Shirong Chen

5.4

Associations

139

has n, :posts, :through => Resource end

This automatically creates the bridging model for us dynamically. But this isn’t magic; remember the line from the def has snippet of source code that we didn’t show you? Here it is: klass = ManyToMany if options[:through] == DataMapper::Resource

With that inside the previous snippet, it’s easy to see that the use of the through option with Resource changes the association setup to a ManyToMany. This special association is used to create a join table model for you. Here’s part of the setup method showing just that: module DataMapper::Associations::ManyToMany def self.setup # ... the usual unless Object.const_defined?(model_name) model = DataMapper::Model.new(storage_name) model.class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ def self.name; #{model_name.inspect} end def self.default_repository_name #{repository_name.inspect} end def self.many_to_many; true end EOS names.each do |n| model.belongs_to( Extlib::Inflection.underscore(n).gsub( '/', '_').to_sym) end Object.const_set(model_name, model) end relationship end

Note the particularly unique creation of a model through Model.new as opposed to a standard class definition. This is meant only for dynamically defined models like the one above.

From the Library of Shirong Chen

140

Chapter 5: Models

5.5 CRUD basics DataMapper as an ORM is intended to create, retrieve, update, and delete records from a repository through interactions with Ruby objects. This means that we don’t have to write SQL statements through the normal course of usage. In fact, DataMapper’s versatility, intelligence, and performance will probably leave you never needing to write a single SQL statement in your entire application. Throughout this section, we will assume the existence of the following model: class BlogEntry include DataMapper::Resource property property property property end

:id, Serial :live, TrueClass :title, String :text, Text

5.5.1 Creating records The creation of DataMapper records is a two-step process. The first step is the creation of a new model object. This is as simple as initializing with the new method. This method can also take an attributes hash that will set the model object’s properties. The second step of this process is the saving of the object’s data into the database as a record. This is done via the save method. Below we create a new blog entry and then save it immediately after. blog_entry = BlogEntry.new(:title => "Model Magic!", :text => "Persistently cool.") blog_entry.save

At the end, this issues a SQL insert command, saving the data in our database. However, let’s take a look first at the most superficial methods inside the DataMapper that make this work: module DataMapper::Resource def save # ... association related saved = new_record? ? create : update if saved original_values.clear

From the Library of Shirong Chen

5.5

CRUD basics

141

end # ... association related (saved | associations_saved) == true end def new_record? !defined?(@new_record) || @new_record end protected def create return false if new_record? && !dirty? && !model.key.any? { |p| p.serial? } # set defaults for new resource properties.each do |property| next if attribute_loaded?(property.name) property.set(self, property.default_for(self)) end return false unless repository.create([ self ]) == 1 @repository = repository @new_record = false # ... IdentityMap related true end private def initialize(attributes = {}) assert_valid_model self.attributes = attributes end end

As you can see, the default initialize has been overridden so that it can set attributes. You’ll also spot a method assert_valid_model, but it isn’t of much interest since all it does is confirm that the model class does in fact have properties defined. Moving on to the save method, you’ll find that it first checks to see if the model object

From the Library of Shirong Chen

142

Chapter 5: Models

should be a new record. To do this it uses the public method new_record?, which is also available to you should you need it as an application or plugin developer. Then, given that our record is new, it invokes the protected method create. This method effectively cascades through the resource’s repository object down to an adapter, where a SQL create statement is executed. Alternatively, you can shorten this process to a single step by using the class method create defined within the Model module. Here we use it just as we did before: blog_entry = BlogEntry.create(:title => 'Models Rule!', :text => 'Persistently cool.')

Taking a peek at the source code, we find that the class method create does exactly what we did ourselves before but returns the model object for our convenience: module DataMapper::Model def create(attributes = {}) resource = new(attributes) resource.save resource end end

5.5.2 Retrieving records The retrieval of model records is principally done through the two methods all and first. These two methods pull up a collection of records or access a single record, respectively. They can easily be chained, allowing for the refining of the data to be retrieved. Let’s take a look at some basic examples: user = User.first(:login => 'foysavas') groups = Group.all(:name => '%Ruby%') admin_groups = groups.all(:user => user)

The first line looks up a user by login, the second retrieves all groups with the word Ruby in them, and the third refines the collection of the second to only those where the user is the admin. Let’s look at the source behind the methods first and all to get an understanding of how they work: module DataMapper::Model def all(query = {}) query = scoped_query(query) query.repository.read_many(query)

From the Library of Shirong Chen

5.5

CRUD basics

143

end def first(*args) query = args.last.respond_to?(:merge) ? args.pop : {} query = scoped_query( query.merge(:limit => args.first || 1)) if args.any? query.repository.read_many(query) else query.repository.read_one(query) end end end

Both all and first use the method scoped_query to integrate new query parameters with any preexisting ones that may exist higher up on a collection on which the method may be acting: module DataMapper::Model private def scoped_query(query = self.query) assert_kind_of 'query', query, Query, Hash return self.query if query == self.query query = if query.kind_of?(Hash) Query.new(query.has_key?(:repository) ? query.delete(:repository) : self.repository, self, query) else query end if self.query self.query.merge(query) else merge_with_default_scope(query) end end end

From the Library of Shirong Chen

144

Chapter 5: Models

DataMapper uses the method assert_kind_of as a way of enforcing types and throws errors when types do not match. Thus, above, we see that scoped_query accepts only queries and hashes. The hashes are really just cases of yet-to-be-initiated queries coming from the parameters of some method like all or first. If both new query parameters and an existing query exist, the two are merged. The model’s default scope (typically having no conditions and all non-lazy model fields) is used to merge in further conditions. Design decision: query object algebra If there was ever something to be excited about with regard to DataMapper, this is it. Under the hood, the reason why DataMapper can do things like chain retrieval methods and use strategic eager loading is that it essentially handles queries as elements of an algebraic structure. This is completely unlike most ORMs, which simply treat queries as undesirable SQL remnants to be executed. We recommend letting this subtlety take its time to soak in. However, the essence of it all is that with each call of a retrieve method, DataMapper creates a new query by operating on two other queries (one of them possibly empty). With this fresh perspective on DataMapper, we recommend visiting the code behind the method Query#update, which we’re just about to do.

The method Query#merge duplicates the query and then seeks to update it. Below we see this method as it leads into Query#update. class DataMapper::Query def update(other) assert_kind_of 'other', other, self.class, Hash assert_valid_other(other) if other.kind_of?(Hash) return self if other.empty? other = self.class.new(@repository, model, other) end return self if self == other @reload unless @unique unless @offset

= other.reload? other.reload? == false = other.unique? other.unique? == false = other.offset

From the Library of Shirong Chen

5.5

CRUD basics

145

if other.reload? || other.offset != 0 @limit = other.limit unless other.limit == nil @order = other.order unless other.order == model.default_order @add_reversed = other.add_reversed? unless other.add_reversed? == false @fields = other.fields unless other.fields == @properties.defaults @links = other.links unless other.links == [] @includes = other.includes unless other.includes == [] update_conditions(other) self end def merge(other) dup.update(other) end end

Note that the method update picks out special query parameters before updating the conditions and finally returning itself.

5.5.2.1 Special query parameters The parameters passed into all and first are mostly understood simply as conditions upon parameters. However, certain keys are understood as special query parameters that shape the query in other ways. The following list should make the use of each of these clear: • add_reversed—reverses the order in which objects are added to the collection.

Defaults to false. • conditions—allows SQL conditions to be set directly using an array of strings.

Conditions are appended to conditions specified elsewhere. • fields—sets the fields to fetch as an array of symbols or properties. Defaults to all

of a model’s non-lazy properties. • includes—includes other model data specified as a list of DataMapper property

paths.

From the Library of Shirong Chen

146

Chapter 5: Models

• limit—limits the number of records returned. Defaults to 1 in the case of first

and is otherwise not set. • links—links in related model data specified by an array of symbols, strings, or

associations. • offset—the offset of the query, essential for paging. Defaults to 0. • order—the query order specified as an array or properties (or symbols) modified

by the two direction methods desc and asc. • reload—causes the reloading of the entire data set. Defaults to false. • unique—groups by the fields specified, resulting in a unique collection. Defaults

to false.

5.5.2.2 Lazy loading of collections DataMapper does not load collections or issue database queries until the data is absolutely needed. The major benefit here is that application developers can worry less about the database side of things once again, knowing that unless they actually use the data of a resource, no database query will be executed. With Merb, we’ve also found that this means simpler controller code, since we can use chained relationships or pagination inside the view. With any other ORM, this may be extremely bad form, given that it implies littering the view with lines of supporting code as well as incurring performance penalties based on the retrieval of possibly unused data. Below we present the practical application of collection lazy loading. # Posts Controller # app/controllers/posts.rb class Posts before :set_page def index @posts = Post.all render end private def set_page @p = params[:page] > 0 ? params[:page] : 1 end end

From the Library of Shirong Chen

5.5

CRUD basics

147

# Posts Index View # app/views/posts/index.html.haml - @posts.all(:limit => 10, :offset => 10*@p).each do |i| .post = @posts.name

Note that this executes only one database query, specifically at the each. To see how and why this works, we need to take a look at some of the code in the parent class of Collection, LazyArray: class LazyArray # borrowed partially from StrokeDB instance_methods.each { |m| undef_method m unless %w[ _ _id_ _ _ _send_ _ send class dup object_id kind_of? respond_to? equal? assert_kind_of should should_not instance_variable_set instance_variable_get extend ].include?(m.to_s) } # add proxies for all Array and Enumerable methods ((Array.instance_methods(false) | Enumerable.instance_methods(false)).map { |m| m.to_s } - %w[ taguri= ]).each do |method| class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ def #{method}(*args, &block) lazy_load results = @array.#{method}(*args, &block) results.equal?(@array) ? self : results end EOS end

def load_with(&block) @load_with_proc = block self end # ... private def lazy_load return if loaded?

From the Library of Shirong Chen

148

Chapter 5: Models

mark_loaded @load_with_proc[self] @array.unshift(*@head) @array.concat(@tail) @head = @tail = nil @reapers.each { |r| @array.delete_if(&r) } if @reapers @array.freeze if frozen? end # ... end

Starting at the top, we can see that all but the quintessence methods are undefined. This is because LazyArray is meant to emulate the primitive Array class, and starting off with a slate that is as blank as possible helps us get there. The next few lines define various instance methods from both Array and Enumerable, essentially making LazyArray a proxy to a real array but prefacing the call of any array method with lazy_load. The lazy_load method itself either simply returns true if already loaded, or uses a Proc defined through the load_with method to populate the array. All in all, the lazy loading of LazyArray has a profound impact on the DataMapper API, arguably serving as the foundation for the elegance and straightforwardness of the query algebra.

5.5.2.3 Lazy loading of properties Some property data is not automatically retrieved when a model object is loaded. For instance, by default, text properties are not loaded unless you specifically request them. This form of lazy loading is facilitated by code with the Resource module and PropertySet class. Let’s see it in action before taking an in-depth look at how it has been put together: # app/models/post.rb class Post include DataMapper::Resource property :id, Serial property :title, String property :body, Text end # Example Merb Interaction > post = Post.first

From the Library of Shirong Chen

5.5

CRUD basics

149

˜ SELECT "id", "title", "is_basic" FROM "posts" ORDER BY "id" LIMIT 1 => #> > post.body ˜ SELECT "body", "id" FROM "posts" WHERE ("id" = 1) ORDER BY "id" => "Nothing to see here"

Note that if we had multiple text properties, they would all have been loaded by the second line of interaction. To prevent this from happening, you can define lazy contexts on properties, thus segmenting the retrieval of lazy property data: # app/models/post.rb class Article include DataMapper::Resource property property property property end

:id, Serial :title, String, :lazy => true :abstract, Text, :lazy => [:summary, :full] :body, Text, :lazy => [:full]

It’s time to see how this is done. We’ll have to open up Resource and PropertySet, with the insight that a property when either get or set calls the method Resource#lazy_load: module DataMapper::Resource def lazy_load(name) reload_attributes( *properties.lazy_load_context(name) loaded_attributes) end end class DataMapper::PropertySet # ... def property_contexts(name) contexts = [] lazy_contexts.each do |context,property_names| contexts << context if property_names.include?(name) end contexts end

From the Library of Shirong Chen

150

Chapter 5: Models

def lazy_load_context(names) if names.kind_of?(Array) && names.empty? raise ArgumentError, '+names+ cannot be empty', caller end result = [] Array(names).each do |name| contexts = property_contexts(name) if contexts.empty? result << name # not lazy else result |= lazy_contexts.values_at(*contexts). flatten.uniq end end result end end

The methods of PropertySet aren’t anything special, but seeing how they work certainly clears up any ambiguity that may have existed within the concept of lazy load contexts.

5.5.2.4 Strategic eager loading If you’ve used ActiveRecord before, you’ve probably trained yourself to avoid N+1 queries. These come up frequently in ActiveRecord since iteration over the associates of a model object usually forces you to make a query for each associate. Add in the original query for the model itself, and you have N+1 queries in total. However, DataMapper prevents this from happening and instead issues only two queries. Let’s take a look at an example in a view to make this more concrete: <% Post.all.each do |post| %>

<%= post.title >

by <%= post.author.name %>

<% end %>

With the code above, all posts and the names of their authors are outputted using only two queries: the first to get the posts and the second to get their authors. This kind of elimination of N+1 queries is called strategic eager loading and is possible thanks to a combination of many different DataMapper implementation decisions. To get an

From the Library of Shirong Chen

5.5

CRUD basics

151

idea of how strategic eager loading works, let’s take a look at some code inside the Relationship class that would have been used in the previous example: class DataMapper::Associations::Relationship # ... # @api private def get_parent(child, parent = nil) child_value = child_key.get(child) return nil if child_value.any? { |v| v.nil? } with_repository(parent || parent_model) do parent_identity_map = (parent || parent_model). repository.identity_map(parent_model.base_model) child_identity_map = child. repository.identity_map(child_model.base_model) if parent = parent_identity_map[child_value] return parent end children = child_identity_map.values children << child unless child_identity_map[child.key] bind_values = children.map { |c| child_key.get(c) }.uniq query_values = bind_values.reject { |k| parent_identity_map[k] } bind_values = query_values unless query_values.empty? query = parent_key.zip(bind_values.transpose). to_hash association_accessor = "#{self.name}_association" collection = parent_model.send(:all, query) unless collection.empty? collection.send(:lazy_load) children.each do |c| c.send(association_accessor). instance_variable_set( :@parent, collection.get(*child_key.get(c))) end

From the Library of Shirong Chen

152

Chapter 5: Models

child.send(association_accessor). instance_variable_get(:@parent) end end end end

From this we learn that in the process of getting a parent resource, DataMapper pulls up the identity map of the parent model and child model to see if the resource has already been loaded. If it has, DataMapper short-circuits any retrieval and simply returns the appropriate parent. Most important, if the resource is not already loaded, DataMapper uses the parent keys from all the relevant children within a collection query. The results are then loaded immediately, and after all children are connected with their parents, the parent requested is returned.

5.5.3 Updating records Resources can be updated by using the save method similarly to how it was used with record creation. However, for saving to have any effect, it is necessary that at least one property value be recently set. This causes DataMapper to mark certain properties as dirty and use them during the creation of an update statement. Below we display the two ways of setting a property value and causing it to be marked as dirty. post = Post.first post.title = "New Title" post.attribute_set(:body, "New Body") post.save

However, note that the second method attribute_set is typically reserved for use inside override writer methods. Note that save, in the case of non-new records, cascades to the calling of update. Thus we have the option of using that method directly if we want: post.update

5.5.3.1 Using update_attributes There is one other way to invoke the updating of attributes. This is to use the method update_attributes, which accepts an arbitrary hash and then an optional constraining property array. Consequently, it works well with form parameters a user may have passed in: class Users def update

From the Library of Shirong Chen

5.5

CRUD basics

153

if @user.update_attributes(params[:user], [:name, :email, :description]) redirect resource(@user) else render :edit end end end

Here we have constrained the user to being able to update only name, email, and description.

5.5.3.2 Original and dirty attribute values You may at some point want to enhance model logic through the comparison of original and dirty attribute values. Here we do so within the method update_speed: class Position property :id, Serial property :vertical_position, Integer property :horizontal_position, Integer property :speed, Float belongs_to :player before :save, :update_speed private def update_speed dy = 0 dx = 0 if original_values[:vertical_position] dy = vertical_position original_values[:vertical_position] end if original_values[:horizontal_position] dx = horizontal_position original_values[:horizontal_position] end v = Math.sqrt(dx*dx + dy*dy) attribute_set(:speed, v) end end

You may notice that we use a before hook here. We’ll cover hooks in the next section.

From the Library of Shirong Chen

154

Chapter 5: Models

5.5.4 Destroying records Records can be deleted by using the destroy method. Alternatively, if you’re looking to delete a full collection of resources, you can use the method destroy!: User.first(:id => 2).destroy Post.all(:user_id => 2).destroy!

5.6 Hooks DataMapper hooks differ from those used in Merb controllers. This is because controller filter chains require a decently specific form of logic. DataMapper models, on the other hand, have the benefit of using the more generic Hook class of Extlib.

Design decision: explicit hooks over aliasing of methods DataMapper could have left it up to application developers to fend for themselves when it comes to hooks. After all, Ruby is an extremely versatile language, and the alias method could be used to chain model methods like create and save. However, DataMapper developers, like Merb developers, shared a distaste for the aliased decoration of methods for, among other reasons, its confusing implications on stacktraces. Therefore, Extlib::Hook was created to enable application developers to easily decorate both instance and class methods without doing any aliasing.

From the application developer’s perspective, the two methods used to create hooks are before and after. DataMapper registers specific hooks for the methods save, create, update, and destroy. Each of these can be used with before and after. module DataMapper module Hook def self.included(model) model.class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _ include Extlib::Hook register_instance_hooks :save, :create, :update, :destroy EOS end end DataMapper::Resource.append_inclusions Hook end # module DataMapper

From the Library of Shirong Chen

5.7

Plugins

155

5.7 Plugins Modularity has been a central objective of DataMapper. Thus, many of the features that you might otherwise expect within a standard ORM are with DataMapper found as plugins. This includes timestamping, aggregation, validations, and various data structures. In this section we’ll go over the most fundamental of these plugins, understanding not only how they’re used but also how they work.

5.7.1 Extra property types The package dm-types provides numerous additional property types. Here’s a list of those included: • BCryptHash—encrypts a string using the bcrypt library • Csv—parses strings as CSVs using FasterCSV • Enum—stores an enumerated value as an integer • EpochTime—converts Time and DateTime to EpochTime, that is, the number of

seconds since the beginning of UNIX time • FilePath—stores paths as strings using Pathname • Flag—binary flags stored as integers • IpAddress—IP address stored as a string • Json—JSON stored as a string • Regexp—regular expressions stored as strings • Serial—an auto-incrementing integer type • Slug—escapes a stored string, making it suitable to be used as part of a URL • URI—stores an Addressable::URI as a string • UUID—creates a UUID stored as a string • Yaml—stores YAML as a string

Let’s take a look at the source to one of these for a better understanding of how to create our own types: require 'yaml' module DataMapper module Types class Yaml < DataMapper::Type primitive String

From the Library of Shirong Chen

156

Chapter 5: Models size 65535 lazy true def self.load(value, property) if value.nil? nil elsif value.is_a?(String) ::YAML.load(value) else raise ArgumentError.new( "+value+ must be nil or a String") end end def self.dump(value, property) if value.nil? nil elsif value.is_a?(String) && value =˜ /ˆ---/ value else ::YAML.dump(value) end end

def self.typecast(value, property) # Leave values exactly as they're provided. value end end # class Yaml end # module Types end # module DataMapper

As you can see, new DataMapper types can be created by subclass off of DataMapper::Type. You will then have to set the primitive type, and this can be done using

the class method primitive. You may additionally have to set attributes like size and laziness as was done in the case above. Finally, the two methods that do the hard work are the class methods load and dump. These need to be defined only if the custom type needs to override them from simply returning the value. With the Yaml type, strings are converted into YAML when loaded from the database and are converted to strings when they need to be dumped into the database.

5.7.2 Timestamps The gem dm-timestamps is one of the most commonly used DataMapper plugins. It saves you from having to code timestamping into your models. Note that once the gem is included, it applies to all DataMapper models. Thus we can set the following

From the Library of Shirong Chen

5.7

Plugins

157

four properties in any Merb stack model, knowing they will automatically be set when needed: class User property property property property end

:created_at, :created_on, :updated_at, :updated_on,

DateTime Date DateTime Date

Because dm-timestamps is a decently simple plugin but also reveals the foundation of resource extension plugins, let’s take a quick look: module DataMapper module Timestamp Resource.append_inclusions self TIMESTAMP_PROPERTIES = { :updated_at => [ DateTime, lambda { |r, p| DateTime.now } ], :updated_on => [ Date, lambda { |r, p| Date.today } ], :created_at => [ DateTime, lambda { |r, p| r.created_at || (DateTime.now if r.new_record?) } ], :created_on => [ Date, lambda { |r, p| r.created_on || (Date.today if r.new_record?) } ], }.freeze def self.included(model) model.before :create, :set_timestamps model.before :update, :set_timestamps model.extend ClassMethods end private def set_timestamps return unless dirty? TIMESTAMP_PROPERTIES.each do |name,(_type,proc)| if model.properties.has_property?(name) model.properties[name].set(self, proc.call(self,

From the Library of Shirong Chen

158

Chapter 5: Models model.properties[name])) unless attribute_dirty?(name) end end end module ClassMethods def timestamps(*names) raise ArgumentError, '...' if names.empty? names.each do |name| case name when *TIMESTAMP_PROPERTIES.keys type, proc = TIMESTAMP_PROPERTIES[name] property name, type when :at timestamps(:created_at, :updated_at) when :on timestamps(:created_on, :updated_on) else raise InvalidTimestampName, "Invalid timestamp property name '#{name}'" end end end end # module ClassMethods

class InvalidTimestampName < RuntimeError; end end # module Timestamp end # module DataMapper

The first line to notice is the third one. Here the module appends itself to Resource. As we saw earlier in this chapter, this gets the Timestamp module automatically included in all classes that include DataMapper::Resource. Moving on, we see the definition of a number of lambdas to be used in setting the four basic timestamps. This is followed by the class method included, which sets up before hooks to apply the timestamps. It all extends our model classes with a timestamps class method. This is a convenience method for defining the various timestamp properties tersely.

5.7.3 Aggregates The DataMapper core has been designed to limit its use as a reporting tool and simply act as an ORM. The plugin dm-aggregates consequently adds in some of the most common aggregating methods used by SQL databases:

From the Library of Shirong Chen

5.7

Plugins

159

• count—finds the number of records in a collection by directly using a count SQL

statement and not the Ruby size method • min—finds the minimum value of a numerical property using SQL • max—finds the maximum value of a numerical property using SQL • avg—finds the average value of a numerical property using SQL • sum—totals the values of a numerical property using SQL

Chances are you will use dm-aggregates at some point. However, before we look into the source, it’s best to recognize that the plugin essentially extends DataMapper’s capability to what it was not really meant to do. module DataMapper class Collection include AggregateFunctions private def property_by_name(property_name) properties[property_name] end end module Model include AggregateFunctions private def property_by_name(property_name) properties(repository.name)[property_name] end end module AggregateFunctions def count(*args) query = args.last.kind_of?(Hash) ? args.pop : {} property_name = args.first if property_name assert_kind_of 'property', property_by_name(property_name), Property end

From the Library of Shirong Chen

160

Chapter 5: Models

aggregate(query.merge(:fields => [ property_name ? property_name.count : :all.count ])) end end module Adapters class DataObjectsAdapter def aggregate(query) with_reader(read_statement(query), query.bind_values) do |reader| results = [] while(reader.next!) do row = query.fields.zip( reader.values).map do |field,value| if field.respond_to?(:operator) send(field.operator, field.target, value) else field.typecast(value) end end results << (query.fields.size > 1 ? row : row[0]) end results end end private def count(property, value) value.to_i end module SQL private alias original_property_to_column_name property_to_column_name def property_to_column_name(repository, property, qualify)

From the Library of Shirong Chen

5.7

Plugins

161

case property when Query::Operator aggregate_field_statement(repository, property.operator, property.target, qualify) when Property, Query::Path original_property_to_column_name(repository, property, qualify) else raise ArgumentError, "..." end end def aggregate_field_statement(repository, aggregate_function, property, qualify) column_name = if aggregate_function == :count && property == :all ' *' else property_to_column_name(repository, property, qualify) end function_name = case aggregate_function when :count then 'COUNT' # ... else raise "Invalid ... " end "#{function_name}(#{column_name})" end end # module SQL include SQL end end end

Above we have included only the code covering the count method. However, it’s easy to recognize the substantial monkey patching going on, particularly in the case of the SQL methods. Otherwise, though, this is a great example of the trickling down of method calls from collections and models into the adapter where SQL statements are formed.

From the Library of Shirong Chen

162

Chapter 5: Models

5.7.4 Validations The plugin dm-validations validates the property values of model objects before saving them. This means that if a model object returns false upon save, you can most likely interpret it as having been caused by undesirable values on properties. Another way to check if a particular model is valid is to directly use the valid? method that is squeezed in before create or update. Before we go any further, here’s a list of the validation methods available within your models through dm-validations: • validates_present—validates the presence of an attribute value. • validates_absent—validates the absence of an attribute value. • validates_is_accepted—validates that an attribute is true or optionally not false

through :allow_nil => true. It can also work with a custom set of acceptance values using :accept => [values]. • validates_is_confirmed—validates the confirmation of an attribute with an-

other attribute, for instance, matching password and password_confirmation. The default confirmation attribute is the original attribute ending in _confirmation, but :confirm can be used to set it to anything else. • validates_format—validates the format of an attribute value against a regular

expression or Proc associated by :with. Alternatively, it can be used with predefined formats such as Email and Url through :as. The :allow_nil key is also available. • validates_length—validates the value of a numeric against a :min or :max value.

Alternatively, a range can be used along with :within. • validates_with_method—validates either the model as a whole or a specific

property through a method. If only one parameter is given, it is the symbolic form of the method to check the entire model. If two are given, they are the attribute and the method used to check that attribute. Error messages can be passed as true by returning an array where false is the first element and a string for an error message is the second from the validating method. • validates_with_block—like validates_with_method but uses blocks. You

can validate either against the whole model or a specific attribute as well as pass in error messages. • validates_is_number—validates that the value of an attribute is a number, ap-

propriate for use in checking the precision and scale of floats. • validates_is_unique—validates that the attribute value is unique, either within

the scope of the attribute value of all other model objects or some other scope specified

From the Library of Shirong Chen

5.7

Plugins

163

by an array of property symbols through :scope. Also accepts :allow_nil to be set. • validates_within—validates that an attribute value is within a set of values

specified by :set. Alternatively, instead of directly using the validations methods, you can include particular hash key-and-values on property definitions. Here’s a list of what keys automatically create appropriate validations: • :nullable—when set to false, automatically creates a presence validator • :length or :size—automatically creates a length validator • :format—creates a format validator • :set—creates a within validator

Additionally, numerical properties are automatically validated using validates_ is_number. To turn off autovalidation on this or any other property type, use :auto_validation => false.

5.7.4.1 Conditions Validation methods are also capable of generally accepting conditions as Procs assigned to :if or :unless. The single block parameter for these Procs is the resource itself. Thus we can do the following: class Experiment include DataMapper::Resource property property property property property property property property property

:id, Serial :name, String :impetus, Text :question, Text :hypothesis, Text :description, Text :conclusion, Text :completed, TrueClass :result, TrueClass

validates_present :conclusion, :if => proc { |r| r.completed? && r.result? } end

From the Library of Shirong Chen

164

Chapter 5: Models

For terseness, DataMapper validations also allow us to specify a method as a symbol instead of a full Proc. Here we require only that an experiment be complete for it to have a conclusion: validates_present :conclusion, :if => :completed?

5.7.4.2 Contexts Contexts allow us to do validations with similar conditions, but specified at the point of validation. For instance, assuming we have the same Experiment model from before, we may set different contexts on particular property validations specifying that they must be validated together: validates_present :impetus, :when => [:proposal] validates_present :question, :when => [:proposal] validates_absent :completed, :when => [:proposal]

The array assigned to when is an array of contexts. The default context is known as :default. We can now use these contexts by including them as a parameter with valid?: exp = Experiment.new( :name => 'Great Subjective Experiment', :impetus => 'Thoughts on physicalism and the mind', :question => 'Is it possible to subjectively test '+ 'the consciousness of other modes of thought '+ 'through their integration with your own?' :completed => true) exp.valid?(:proposal) # => false

5.7.4.3 Errors Every time a model object is validated, it populates (or empties) a hash of errors accessible through the resource instance method errors. These errors can be used to indicate to a user that something went wrong or otherwise recognize what particular attributes are invalid: resource.errors.each do |e| puts e # => [[:attr_name, ["Error!"]]] end resource.errors.on(:attr_name) # => ["Error!"] resource.errors.on(:another_attr) # => nil

Notice how errors.on returns nil when there are no errors. Consequently it can be used to test if an error is present on a property. Also note that error messages are

From the Library of Shirong Chen

5.8

Conclusion

165

given as arrays. This is because multiple validation errors may have occurred on a single attribute.

5.8 Conclusion DataMapper is an undeniably excellent ORM. It offers application developers the chance to stay as far away from database work as possible by streamlining development migrations and placing model properties within the model. It also lets us treat ORM objects even more casually by virtue of its eager and lazy loading of data sets. Inside the Merb stack or not, the highly modular DataMapper will serve you well.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 6

Helpers

Helpers are methods that are widely available throughout your application. They are primarily used within templates but are also available within controllers, given the tight coupling of controllers and views in Merb. The use of helpers greatly simplifies the most common tasks application developers face. Consequently, their structure exhibits some of the best refactoring that web application developers typically run into. That said, we’re going through the helper source extensively, so that you will be comfortable with the methods you use all the time but also with designing your own. Before continuing, it is worthwhile to mention that most active helpers exist in the module Merb::GlobalHelpers, which is included at boot within all controllers. You can add your own helper methods to this module within the file app/helpers/ global_helpers.rb. Alternatively, particular controllers may have their own helpers. These should be placed in the file app/helpers/#controller_name_helpers.rb. The rest of this chapter goes through the helpers found within the module merbhelpers.

6.1 Truncate helper One of the most commonly used helpers included in the Merb helpers is truncate. It truncates a string at a point and then appends a suffix, making it perfect for the display of preview allotments of text on views: # app/views/messages/index.html.haml - @messages.each do |m| .message_preview %a{:href => resource(m)} m.text.truncate(25)

167 From the Library of Shirong Chen

168

Chapter 6: Helpers

The default suffix is '...', but by passing in a second parameter we can override this. Here’s the source to the method. Note that this helper is essentially a core class extension, which very rarely happens within helpers. class String def truncate(length = 30, truncate_string = "...") return self unless self.length > length length = length - truncate_string.split(//).length self[0...length] + truncate_string end end

6.2 Numeric helpers The numeric helpers have been included with the Merb helpers to add in some of the most common conversions applications make between numbers and strings. All of these helpers exist as utility methods of the module Numeric::Transformer and are made accessible through same-name instance methods in the Numeric class itself. Keep this in mind as we display the source to each of them.

6.2.1 Two digits The two_digits helper does exactly what it says it does: adds a single leading zero to numbers under 10. This can be useful for displaying dates and is used in other helpers for just that: 8.two_digits # => "08"

The source behind two_digits is divided into two methods, one API private and the other public: class Numeric module Transformer # @private def self.two_digits(number) (0..9).include?(number) ? "0#{number}" : number.to_s end end # @public def two_digits Transformer.two_digits(self) end end

From the Library of Shirong Chen

6.2

Numeric helpers

169

6.2.2 Minutes to hours The helper minutes_to_hours builds on the two_digits helper, allowing us to conveniently convert minutes to hours: 345.minutes_to_hours # => "05:55"

Here’s the utility method where everything interesting happens: def self.minutes_to_hours(minutes) hours = (minutes/60).ceil minutes = (minutes - (hours * 60)).to_i "#{two_digits(hours)}:#{two_digits(minutes)}" end

6.2.3 Currency strings The helper method to_currency converts a numeric into a standard currency string like "$1.99". We accomplish this with the following: 1.99.to_currency # => "$1.99"

We can also use other currencies by specifying a locale. This automatically modifies the unit, format, precision, delimiter, and separator: 20.to_currency(:uk) # => "£20.00"

The predefined formats are US, UK, AU, FR, and RU. However, you can easily add more formats using the method add_format: Numeric::Transformer.add_format(:hyperboria => { :number => { :precision => 0, :delimiter => '.', :separator => '' }, :currency => { :unit => '*', :format => '%n%u', :precision => 0 } }); 99.99.to_currency(:hyperboria) # => "100*" Numeric::Transformer.change_default_format(:hyperboria) 1000000.to_currency # => "1.000.000*"

Note that in the last two lines we also changed the default currency.

From the Library of Shirong Chen

170

Chapter 6: Helpers

There are also two methods used by to_currency that are available to the application developer. Let’s take a look at their source, once again noting that a public instance method in Numeric makes them accessible: # @private def self.with_delimiter(number, format_name = nil, options = {}) format = (formats[format_name] || default_format)[:number].merge(options) begin parts = number.to_s.split('.') parts[0].gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{format[:delimiter]}") parts.join(format[:separator]) rescue number end end

# @private def self.with_precision(number, format_name = nil, options={}) format = (formats[format_name] || default_format)[:number].merge(options) begin rounded_number = (Float(number) * (10 ** format[:precision])).round.to_f / 10 ** format[:precision] with_delimiter("%01.#{format[:precision]}f" % rounded_number, format_name, :delimiter => format[:delimiter], :separator => format[:separator]) rescue number end end

From this we can easily determine how to pass in options for delimiter, separator, and precision that override the defaults. Though the methods above are pretty standard fare for Rubyists writing helpers, you may be interested in studying them if you haven’t done extensive string formatting before.

From the Library of Shirong Chen

6.3

Date and time helpers

171

6.3 Date and time helpers The module DateAndTimeFormatting mixes a number of helper methods into the DateTime, Date, and Time classes. It also stores a number of predefined formats and gives you the opportunity to add your own.

6.3.1 Formats Let’s first take a look at the list of provided formats. These can be accessed as a hash by invoking the class method formats on any of the data and time classes. • db—formats a time as databases typically store it • time—outputs just the time in 24-hour format • date—outputs just the date as year, month, and day • short—displays only the day, month (abbreviated), and time • long—displays the full date, written out • rfc822—formats the time to match RFC 822

We can use these directly by passing one in as the parameter of the method formatted on an instance of any date or time class: Time.now.formatted(:date) # => "2009-02-14"

Adding new formats for your application to use is simply a matter of using the add_format method on any date or time class: > Time.add_format(:year,'%Y') => {:db=>"%Y-%m-%d %H:%M:%S", :short=>"%d %b %H:%M", :rfc822=>"%a, %d %b %Y %H:%M:%S %z", :year=>"%Y", :long=>"%B %d, %Y %H:%M", :time=>"%H:%M", :date=>"%Y-%m-%d"} > Date.formats => {:db=>"%Y-%m-%d %H:%M:%S", :short=>"%d %b %H:%M", :rfc822=>"%a, %d %b %Y %H:%M:%S %z", :year=>"%Y", :long=>"%B %d, %Y %H:%M", :time=>"%H:%M", :date=>"%Y-%m-%d"}

Note that when you add a format, it is added not only to the class on which you used add_format but to all date and time classes. Let’s peek at the source for this method to

understand how this is done: module DateAndTimeFormatting def self.included(base) base.class_eval do

From the Library of Shirong Chen

172

Chapter 6: Helpers

include DateAndTimeFormatting::InstanceMethods include OrdinalizedFormatting extend DateAndTimeFormatting::ClassMethods end end module InstanceMethods # @public def formatted(format = :default) self.strftime(Date.formats[format]) end end module ClassMethods @@formats = { :db :time :date :short :long :rfc822 }

=> => => => => =>

"%Y-%m-%d %H:%M:%S", "%H:%M", # 21:12 "%Y-%m-%d", # 2008-12-04 "%d %b %H:%M", # 01 Sep 21:12 "%B %d, %Y %H:%M", "%a, %d %b %Y %H:%M:%S %z"

# @public def formats @@formats end # @public def add_format(key, format) formats.merge!({key => format}) end end end class Date include DateAndTimeFormatting # ... end

From the Library of Shirong Chen

6.3

Date and time helpers

173

class Time include DateAndTimeFormatting # ... end

The formats are all stored within a module called DateAndTimeFormatting. This module is included within both Date and Time, and whenever either is used to add a format, it affects the module itself. It is noteworthy that this helper is consequently not thread-safe. This is because when you add a format in one thread it does not affect the other. To overcome this, we recommend that you put a mutex around any dynamically created formats, or simply define new formats in a boot loader before the application loads.

6.3.2 Ordinals The module Ordinalize is used extensively by the date and time helpers and therefore is included there. Nonetheless, it is essentially an extension of the Integer class. You can use it directly on any integer by calling the method ordinalize: > 1.ordinalize => "1st" > 1023.ordinalize => "1023rd"

The method for ordinalize is expectedly simple, using only modular arithmetic and one if statement to create the result: module Ordinalize def ordinalize if (11..13).include?(self % 100) "#{self}th" else case self % 10 when 1; "#{self}st" when 2; "#{self}nd" when 3; "#{self}rd" else "#{self}th" end end end end Integer.send :include, Ordinalize

From the Library of Shirong Chen

174

Chapter 6: Helpers

6.3.3 Time DSL The Merb helpers also include a Time DSL similar to the one found with Rails. This allows us to go from numeric to number of seconds using methods that mimic natural language. For example: > 1.hour => 3600 > 10.minutes => 600

There are also a couple of DSL methods that generate time objects: > 10.days.ago => Tue Feb 03 14:10:20 -0500 2009

Rather then present a comprehensive list of the methods, we present the extremely simple source code to these methods, including their aliasing: module TimeDSL def second self * 1 end alias_method :seconds, :second def minute self * 60 end alias_method :minutes, :minute def hour self * 3600 end alias_method :hours, :hour def day self * 86400 end alias_method :days, :day def week self * 604800 end alias_method :weeks, :week def month self * 2592000 end

From the Library of Shirong Chen

6.3

Date and time helpers

175

alias_method :months, :month def year self * 31471200 end alias_method :years, :year # Reads best without arguments: 10.minutes.ago def ago(time = ::Time.now) time - self end alias :until :ago # Reads best with argument: 10.minutes.since(time) def since(time = ::Time.now) time + self end alias :from_now :since end Numeric.send :include, TimeDSL

6.3.4 Relative time To make the output of dates more relevant to the moment, relative time can be used. For example, instead of giving yesterday’s day, we simply say “yesterday.” There are Merb helpers that can help translate date and time objects to relative time strings. These utility methods are relative_date, relative_date_span, relative_time_span, time_lost_in_words, and prettier_time. Here we use them within a view: # app/views/comments/show.html.haml .comment .text= @c.text .date %span== Posted #{relative_date(@c.created_on)} %span== or #{time_lost_in_words(@c.created_at)} ago

As you may have guessed, these methods are included within the module Merb::GlobalHelpers and are available within views. This also makes them a great

template for structuring your own reusable global helpers. Here we present the source to the prettier_time method but demonstrate the organization of the helpers: module Merb module Helpers module DateAndTime # ...

From the Library of Shirong Chen

176

Chapter 6: Helpers

def prettier_time(time, ampm=true, locale=nil) time.strftime("%I:%M#{" %p" if ampm}"). sub(/ˆ0/, '') end end end end module Merb::GlobalHelpers include Merb::Helpers::DateAndTime end

6.4 Cycle helper The cycle helper may at first seem to be a peculiarity among helpers, but it can be put to extensive use. Inside the module Merb::helpers::Text, it is, like the relative time helpers, included within the GlobalHelpers and thus available to all views. It can be used to continuously step through a list of values, outputting them as necessary. Here we put this to use to alternate the class names on rows of a table: %table - @user.each do |u| %tr{:class => "row#{cycle(0,1)}"}

Cycles can also be reset, so if we had one table followed by another, we might reset the cycle before outputting the second table: %table - @user.each do |u| %tr{:class => "row#{cycle(0,1)}"} - reset_cycle %table - @groups.each do |g| %tr{:class => "row#{cycle(0,1)}"}

Alternatively, in order to make the positions of cycles independent from one another, we can name each of the cycles we use by passing in a hash as the final parameter. This could be important among cycles that reset within cycles. %table - @user.each do |u| %tr{:class => "row#{cycle(0,1)}"} %table - @groups.each do |g| %tr{:class => "row#{cycle(0,1), :name => :groups}"} - reset_cycle(:groups)

From the Library of Shirong Chen

6.5

Tag helpers

177

Here’s the source behind the cycle method: def cycle(*values) options = extract_options_from_args!(values) || {} key = (options[:name] || :default).to_sym (@cycle_positions ||= {})[key] ||= {:position => -1, :values => values} unless values == @cycle_positions[key][:values] @cycle_positions[key] = {:position => -1, :values => values} end current = @cycle_positions[key][:position] @cycle_positions[key][:position] = current + 1 values.at( (current + 1) % values.length).to_s end

Note that the default cycle name is :default and that it is extracted from the values using the method extract_options_from_args!, which is an extension the Merb core makes to Kernel: class Kernel # :api: public def extract_options_from_args!(args) args.pop if Hash === args.last end end

6.5 Tag helpers The tag helpers, of which there are only four, are fundamental to the creation of HTML and XML entities. Let’s go through the code that pulls these together: module Merb module Helpers module Tag def tag(name, contents = nil, attrs = {}, &block) attrs, contents = contents, nil if contents.is_a?(Hash) contents = capture(&block) if block_given? open_tag(name, attrs) + contents.to_s + close_tag(name) end

From the Library of Shirong Chen

178

Chapter 6: Helpers def open_tag(name, attrs = nil) "<#{name}#{' '+ attrs.to_html_attributes unless attrs.blank?}>" end # Creates a closing tag def close_tag(name) "" end def self_closing_tag(name, attrs = nil) "<#{name}#{' '+ attrs.to_html_attributes if attrs && !attrs.empty?}/>" end

end end end module Merb::GlobalHelpers include Merb::Helpers::Tag end

We find that the tag helpers, like other helpers, are contained within a module and then included within the module Merb::GlobalHelpers. Remember that this module is included within the Merb::Controller, and consequently these methods are available to all controllers and all views. The first method, tag, can take three arguments: name, contents, and attrs. Thus we can create HTML entities as follows: tag("div","Hello There", :class => "message")

It also takes an optional block that we can use to place in nested entities: tag(:h3) do tag(:div,"Hello There", :class => "message") end

Most of the hard work is done through the other helper methods and to_ html_attributes. Chances are you will not use these helpers within templates themselves, because their real target is within other helpers, allowing for the construction of HTML entities in an abstract, template-agnostic way. In the next section, we’ll see just that.

From the Library of Shirong Chen

6.6

Form helpers

179

6.6 Form helpers The design of the form helpers is more complex than that of any of the other helpers described in this chapter. With that in mind, we will not cover the API of helpers entirely in this section and aim only to fundamentally understand the design of helpers by picking apart its quintessential parts. Let’s start off with the underlying builder class upon which the actual helpers rely.

6.6.1 Builders The Form::Builder module holds module Merb::Helpers::Form::Builder class Base include Merb::Helpers::Tag def initialize(obj, name, origin) @obj, @origin = obj, origin @name = name || @obj.class.name.snake_case. split("/").last end

Note the class Base. It has access to the tag helpers previously described, so we can expect them to be littered throughout the rest of the code. It’s also the class that will be used under the hood by the form helpers themselves. As such, it must maintain three instance variables, two of which may simply end up being nil. The first of these, obj, is meant as a reference to the model object with which the form may be associated and may be nil. The second, name, holds the name of the form context, which again is related to the model object and most of the time derived from it. This parameter can also be nil without causing issues. Finally, the parameter origin links us back to the actual form helper making use of the base. This parameter is strictly necessary. def form(attrs = {}, &blk) captured = @origin.capture(&blk) fake_method_tag = process_form_attrs(attrs) tag(:form, fake_method_tag + captured, attrs) end def fieldset(attrs, &blk) legend = (l_attr = attrs.delete(:legend)) ? tag(:legend, l_attr) : "" tag(:fieldset, legend + @origin.capture(&blk), attrs) end

From the Library of Shirong Chen

180

Chapter 6: Helpers

The two methods form and fieldset are used indirectly in the production of form and fieldset elements. We have grouped them together for you because they both make use of blocks passed to them. It’s worthwhile to point out that the capture method is employed in handling these blocks, which ultimately means that they will be handled by the template engine. You may also have spotted the use of process_form_attrs: private def process_form_attrs(attrs) method = attrs[:method] attrs[:method] = :post unless attrs[:method] == :get method ||= (@obj.respond_to?(:new_record?) && [email protected]_record?) || (@obj.respond_to?(:new?) && [email protected]?) ? :put : :post attrs[:enctype] = "multipart/form-data" if attrs.delete(:multipart) || @multipart method == :post || method == :get ? "" : fake_out_method(attrs, method) end def fake_out_method(attrs, method) self_closing_tag(:input, :type => "hidden", :name => "_method", :value => method) end

The processing of form attributes does three things. First, it checks to see if we’ve set the form to use the GET method. If so, it leaves it alone. Otherwise it will use POST. In general, all forms should use POST, unless the form is meant simply as an interface to some complex set of data. The best example of this would be a search form leading to a filtered index. Second, irrespective of the actual method used on the form, the method figures out what the best REST verb is. This later comes into play as a hidden form element that, as we saw very early on while studying the Merb fundamentals, overrides the actual request method used from the perspective of the router. This again is meant to compensate for the lack of availability of all HTTP methods among browsers. Third, the method allows us to use :multipart => true as shorthand for specifying that the form should accept uploads.

From the Library of Shirong Chen

6.6

Form helpers

181

public %w(text password hidden file).each do |kind| self.class_eval <<-RUBY, _ _FILE_ _, _ _LINE_ _ + 1 def bound_#{kind}_field(method, attrs = {}) name = control_name(method) update_bound_controls(method, attrs, "#{kind}") unbound_#{kind}_field({ :name => name, :value => control_value(method) }.merge(attrs)) end def unbound_#{kind}_field(attrs) update_unbound_controls(attrs, "#{kind}") self_closing_tag(:input, {:type => "#{kind}"}. merge(attrs)) end RUBY end

Note that the methods for several fields are dynamically generated. This is because there is inherently nothing special about them. The biggest difference between bound and unbound variants is that the bound variants automatically set a name and value based upon the object of the form context before invoking the unbound method. Below we see the private methods used to generate the name and value attributes. private def control_name(method) @obj ? "#{@name}[#{method}]" : method end def control_value(method) value = @obj ? @obj.send(method) : @origin.params[method] if Merb.disabled?(:merb_helper_escaping) value.to_s else Merb::Parse.escape_xml(value.to_s) end end

You may also wonder what the method update_*_controls is for, but before we get to that let’s analyze at least one of the more complicated form element fields:

From the Library of Shirong Chen

182

Chapter 6: Helpers public def bound_check_box(method, attrs = {}) name = control_name(method) update_bound_controls(method, attrs, "checkbox") unbound_check_box({:name => name}.merge(attrs)) end def unbound_check_box(attrs) update_unbound_controls(attrs, "checkbox") if attrs.delete(:boolean) on, off = attrs.delete(:on), attrs.delete(:off) unbound_hidden_field(:name => attrs[:name], :value => off) << self_closing_tag(:input, {:type => "checkbox", :value => on}.merge(attrs)) else self_closing_tag(:input, {:type => "checkbox"}. merge(attrs)) end end

The checkbox control is more complicated than those we have seen before, or at least the unbound variant is. Notice how the method bound_check_box doesn’t set a field value. Where is this work being done? private def update_bound_controls(method, attrs, type) case type when "checkbox" update_bound_check_box(method, attrs) when "select" update_bound_select(method, attrs) end end def update_bound_check_box(method, attrs) raise ArgumentError, ":value can't be used" if attrs.has_key?(:value) attrs[:boolean] = attrs.fetch(:boolean, true) val = control_value(method) attrs[:checked] = attrs.key?(:on) ? val == attrs[:on] : considered_true?(val)

From the Library of Shirong Chen

6.6

Form helpers

183

end # ... def considered_true?(value) value && value != "false" && value != "0" && value != 0 end

Inside the cascaded call to update_bound_check_box we find that the checked attribute is set to true or false based upon either the matching of the control value with the on value or otherwise when some value generically considered true has been used. Ignoring the specifics for a moment, the method update_bound_check_box exemplifies the extension of form field behavior. This technique is used not only with many of the bound controls but also with many of the unbound ones. def update_unbound_controls(attrs, type) case type when "checkbox" update_unbound_check_box(attrs) when "radio" update_unbound_radio_button(attrs) when "file" @multipart = true end attrs[:disabled] ? attrs[:disabled] = "disabled" : attrs.delete(:disabled) end def update_unbound_check_box(attrs) boolean = attrs[:boolean] || (attrs[:on] && attrs[:off]) ? true : false case when attrs.key?(:on) ˆ attrs.key?(:off) raise ArgumentError, ":on and :off ..." when (attrs[:boolean] == false) && (attrs.key?(:on)) raise ArgumentError, ":boolean => false ... " when boolean && attrs.key?(:value) raise ArgumentError, ":value cannot be ... " end if attrs[:boolean] = boolean attrs[:on] ||= "1"; attrs[:off] ||= "0" end

From the Library of Shirong Chen

184

Chapter 6: Helpers attrs[:checked] = "checked" if attrs.delete(:checked) end # ...

end

Remembering how the bound checkbox eventually defers to the behavior of the unbound checkbox, we see that the code above is used by both methods. The argument errors are ways of making sure developers don’t misuse the helper, while the final line shows us that despite whatever value it may have had in the past, the checked attribute simplifies to the HTML oddity of either being present and equal to "checked" or not there at all. We’ve left out the numerous other methods used behind the scenes by form fields, but we recommend the pure API for help with the specifics of these helpers. If, however, you do run into a bug, you’ll know right where to track it down. The Base class for form builders can be extended. For instance, the following subclass of Base adds labels to forms and is used by the Merb form helpers by default: class Form < Base def label(contents, attrs = {}) if contents if contents.is_a?(Hash) label_attrs = contents contents = label_attrs.delete(:title) else label_attrs = attrs end tag(:label, contents, label_attrs) else "" end end

The method label is used to build a label element, but we don’t typically call this method ourselves: %w(text password file).each do |kind| self.class_eval <<-RUBY, _ _FILE_ _, _ _LINE_ _ + 1 def unbound_#{kind}_field(attrs = {}) unbound_label(attrs) + super end RUBY end # ...

From the Library of Shirong Chen

6.6

Form helpers

185

Instead, the methods for individual form elements have been extended to include labels automatically. The code above displays only some of these extended methods. However, all of them make use of the method unbound_label to determine what to name and caption the label: def unbound_label(attrs = {}) if attrs[:id] label_attrs = {:for => attrs[:id]} elsif attrs[:name] label_attrs = {:for => attrs[:name]} else label_attrs = {} end label_option = attrs.delete(:label) if label_option.is_a? Hash label(label_attrs.merge(label_option)) else label(label_option, label_attrs) end end

Altogether, the application developer should be aware that form helper methods that have not been handed a value for the :label key within the attributes parameter are not preceded by a label. Two other extensions of the form builder come as modules. Take your time understanding both, as they probably serve as the best structure for extending the form helpers for your own applications. module Errorifier def error_messages_for(obj, error_class, build_li, header, before) obj ||= @obj return "" unless obj.respond_to?(:errors) sequel = !obj.errors.respond_to?(:each) errors = sequel ? obj.errors.full_messages : obj.errors return "" if errors.empty? header_message = header % [errors.size, errors.size == 1 ? "" : "s"] markup = %Q{

} +

From the Library of Shirong Chen

186

Chapter 6: Helpers Q{#{header_message}

} errors.each do |err| markup << (build_li % (sequel ? err : err.join(" "))) end markup << %Q{

} end

This module defines a method error_messages_for, which can be used to output validation errors related to form objects. Many of the lines are there to handle the various ways ORMs store this error within the properties of an invalidated object. private def update_bound_controls(method, attrs, type) if @obj && [email protected](method.to_sym).blank? add_css_class(attrs, "error") end super end end

The private method update_bound_controls does something sweet with ease: It adds a CSS error class on all specifically invalidated element fields. By now, update_bound_controls should no longer seem pointless but instead quite useful to developers needing to extend the base form builder. class FormWithErrors < Form include Errorifier end

Above we see the inclusion of the module within a subclass of the Form builder class. Note, however, that Merb does not use the FormWithErrors builder by default, but it does use the module above through the builder we’re about to see. module Resourceful private def process_form_attrs(attrs) attrs[:action] ||= @origin.url(@name, @obj) if @origin super end end

From the Library of Shirong Chen

6.6

Form helpers

187

The extension of the method process_form_attrs allows us to automatically set the action of a form when it is bound to a resource object. In practice this means a form bound to a RESTfully controlled model. class ResourcefulForm < Form include Resourceful end class ResourcefulFormWithErrors < FormWithErrors include Errorifier include Resourceful end end

Ending our discussion of form builders, we arrive at the form builder used by default with Merb, ResourcefulFormWithErrors. Having gone through the greater part of the source for the Merb form builder, you should be aware of how form elements are handled under the hood. However, we did skip the specifics for a number of elements, so you may need to consult the Merb documentation at times, or otherwise adventurously dive into the source code, which by now should cause you no fear.

6.6.2 Helpers The Helpers::Form module holds the actual methods that application developers use with regard to forms. With that in mind, though we will be going through the raw source for them, it’s worth taking the time to let these methods sink in for later use. module Merb::Helpers::Form def form_contexts @_form_contexts ||= [] end def current_form_context form_contexts.last || _singleton_form_context end

The concept of form context is critical to the form helper methods. This is because forms can associate with model objects, and the context of those objects affects how particular form elements should semantically be created. The two methods form_contexts and current_form_context serve as a foundation for determining the current context: def form(*args, &blk) _singleton_form_context.form(*args, &blk) end

From the Library of Shirong Chen

188

Chapter 6: Helpers

def _singleton_form_context self._default_builder = Merb::Helpers::Form:: Builder::ResourcefulFormWithErrors unless self._default_builder @_singleton_form_context ||= self._default_builder.new(nil, nil, self) end

The application developer should pay particular attention to the method form. It is used for forms without any model object context. As a consequence, we see it pull up what is internally called the singleton form context. This context initiates a new form builder or retrieves the last one built. The form method then delegates the handling of its parameter block to the same-named builder method as in the last section. This, however, is not the only way to construct a form. def form_for(name, attrs = {}, &blk) with_form_context(name, attrs.delete(:builder)) do current_form_context.form(attrs, &blk) end end def _new_form_context(name, builder) if name.is_a?(String) || name.is_a?(Symbol) ivar = instance_variable_get("@#{name}") else ivar, name = name, name.class.to_s.snake_case end builder ||= current_form_context.class if current_form_context (builder || self._default_builder).new(ivar, name, self) end def with_form_context(name, builder) form_contexts.push(_new_form_context(name, builder)) ret = yield form_contexts.pop ret end

In contrast with the method above, form_for takes a name in addition to its attributes. This name is used to form a specific form context. Note that this name can be either a string/symbol or a variable. This means that :user and @user are equivalent. We recommend that you stay away from using strings or symbols because they apply only to instance variables and consequently are not applicable to the local variables of partials. Another takeaway message from the code above is that the form block is handled through

From the Library of Shirong Chen

6.6

Form helpers

189

a yield statement that is surrounded by the push and later pop of the form context array. As a web application developer, you may be wondering, Why all the complexity? After all, forms cannot be embedded within one another. Our helpers, however, allow for something a bit different: def fields_for(name, attrs = {}, &blk) attrs ||= {} with_form_context(name, attrs.delete(:builder)) do capture(&blk) end end def fieldset(attrs = {}, &blk) _singleton_form_context.fieldset(attrs, &blk) end def fieldset_for(name, attrs = {}, &blk) with_form_context(name, attrs.delete(:builder)) do current_form_context.fieldset(attrs, &blk) end end

The three helpers fields_for, fieldset, and fieldset_for offer us a way of changing the form context from within another form. This versatility means that we can easily produce the appropriate form elements for multiple objects within one form. The distinction between fields_for and the other two is that fields_for does not create a fieldset HTML entity. Of course, of interest to us now is the helper method for the particular form elements: def check_box; end def file_field; end def hidden_field; end def password_field; end def radio_button; end def radio_group; end def select; end def text_area; end def text_field; end

From the Library of Shirong Chen

190

Chapter 6: Helpers

You may find it odd that none of the methods above has any body. The reason for this is to make them available even before they are dynamically generated below. %w(text_field password_field hidden_field file_field text_area select check_box radio_button radio_group). each do |kind| self.class_eval <<-RUBY, _ _FILE_ _, _ _LINE_ _ + 1 def #{kind}(*args) if bound?(*args) current_form_context.bound_#{kind}(*args) else current_form_context.unbound_#{kind}(*args) end end RUBY end

The templated method above holds the actual code for each of these methods. If it’s your first time, note the explicit use of _ _FILE_ _ and _ _LINE_ _ with a class_eval. These are there so that exception output actually directs us to the relevant file and line. Inside the method template itself, it delegates to either the bound or the unbound builder methods. The way of determining which is simple: private def bound?(*args) args.first.is_a?(Symbol) end

We realize that the only thing that matters is whether the helper method’s first argument is a symbol or not. This is because the methods above accept a hash of arguments, but a symbol can be added before this hash, effectively indicating that it should be bound within the current form context. The symbol given, therefore, should be that of a model accessor. As we previously saw, this is used to dynamically generate the name attribute on the element. If the form element we need should not be bound, however, then we can explicitly give it its name by setting the value of :name within the attributes hash. public def label(*args) current_form_context.label(*args) end def button(contents, attrs = {})

From the Library of Shirong Chen

6.6

Form helpers

191

current_form_context.button(contents, attrs) end def submit(contents, attrs = {}) current_form_context.submit(contents, attrs) end

The label, button, and submit helper methods of course do not need to be bound, so they have been handled separately. def error_messages_for(obj = nil, opts = {}) current_form_context.error_messages_for(obj, opts[: error_class] || "error", opts[:build_li] || "

", opts[:header] || "

Form submission failed because of %s problem%s

", opts.key?(:before) ? opts[:before] : true) end alias error_messages error_messages_for

The method error_messages_for can simplify the output of model object validation errors. Note that we can pass in alternatives to its defaults, which is certainly useful if we need to deviate from standard text. def delete_button(object_or_url, contents="Delete", attrs = {}) url = object_or_url.is_a?(String) ? object_or_url : resource(object_or_url) button_text = (contents || 'Delete') tag :form, :class => 'delete-btn', :action => url, : method => :post do tag(:input, :type => :hidden, :name => "_method", : value => "DELETE") << tag(:input, attrs.merge(:value => button_text, : type => :submit)) end end end

Finally, the delete_button method creates a delete form consisting of only a hidden element and a delete button. This helper needs either a specific object to delete or a URL pointing to the path requesting its deletion. The reason for this is simply to avoid misuse of GET requests to alter persisted states on the server.

From the Library of Shirong Chen

192

Chapter 6: Helpers

6.7 Conclusion In this chapter, we explored in depth the code build helpers. That said, both application developers and framework enthusiasts should be able to take away direct insight into how to extend the controllers and views of Merb applications with just about any kind of helper method. We also saw, principally through the form helpers, how a model object can more easily be used within views, tucking away applicable logic almost exclusively into helper code.

From the Library of Shirong Chen

C HAPTER 7

Slices

As we add more features to a Merb application, we may find that some are generic enough to be applicable to other apps. Whereas in the past you may have copied and pasted the relevant controller, views, and models from one application to another, Merb slices allow you to genuinely refactor the code encapsulating them within a gem. This gem can then be included with multiple applications, allowing for application-level overriding of particulars, for instance. In this chapter we’ll go through both the anatomy of slices as well as the source that makes them possible.

7.1 Slice development Slice development practices have been designed to mimic those of standard applications. There are some differences, though, that you need to be aware of. In this section we’ll shed some light on the basics of generating, running, and using a slice.

7.1.1 Generating slices The generation of a slice is similar to the generation of a Merb application. Using merb-gen, we can create the skeleton for our slice: vas@nocturne:˜/src$ merb-gen slice merb-forums-slice Generating with slice generator: [ADDED] README [ADDED] lib/merb-forums-slice.rb [ADDED] Rakefile [ADDED] spec/requests/main_spec.rb [ADDED] spec/spec_helper.rb [ADDED] spec/merb-forums-slice_spec.rb [ADDED] TODO

193 From the Library of Shirong Chen

194

Chapter 7: Slices [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED] [ADDED]

stubs/app/controllers/application.rb stubs/app/controllers/main.rb app/controllers/application.rb app/controllers/main.rb app/helpers/application_helper.rb app/views/main/index.html.erb app/views/layout/merb_forums_slice.html.erb config/router.rb config/init.rb public/javascripts/master.js public/stylesheets/master.css LICENSE lib/merb-forums-slice/merbtasks.rb lib/merb-forums-slice/slicetasks.rb lib/merb-forums-slice/spectasks.rb

You’ll notice that some of these files are particular to slices, most importantly the files in lib and in stub. Let’s open up the most important of them, lib/merb-forumsslice.rb: if defined?(Merb::Plugins) $:.unshift File.dirname(_ _FILE_ _) dependency 'merb-slices', :immediate => true Merb::Plugins.add_rakefiles( "merb-forums-slice/merbtasks", "merb-forums-slice/slicetasks", "merb-forums-slice/spectasks") Merb::Slices::register(_ _FILE_ _) Merb::Slices::config[:merb_forums_slice][:layout] ||= :merb_forums_slice module MerbForumsSlice # Slice metadata self.description = "MerbForumsSlice!" self.version = "0.0.1" self.author = "Engine Yard" def self.loaded end def self.init end

From the Library of Shirong Chen

7.1

Slice development

195

def self.activate end def self.deactivate end def self.setup_router(scope) scope.match('/index(.:format)'). to(:controller => 'main', :action => 'index'). name(:index) scope.match('/'). to(:controller => 'main', :action => 'index'). name(:home) scope.default_routes end end MerbForumsSlice.setup_default_structure! end

The first thing to note is that the code adds the lib directory to the list of locations from which required files can be found. This makes the slice’s local dependencies easy to find even from the host application. The code then proceeds to add various rake task files that may be used for slice maintenance. If your slice needs custom rake tasks, inside one of these files is the best place to put them. The next thing done is the registration of the slice. Note that the register method uses the full fill path to do this. If we peek into the method itself, located in the merb-slices source, we can understand why: module Merb::Slices def register(slice_file, force = true) identifier = File.basename(slice_file, '.rb') underscored = identifier.gsub('-', '_') module_name = underscored.camel_case slice_path = File.expand_path( File.dirname(slice_file) + '/..') if !self.paths.include?(slice_path) || force self.files[module_name] = slice_file self.paths[module_name] = slice_path slice_mod = setup_module(module_name) slice_mod.identifier = identifier slice_mod.identifier_sym = underscored.to_sym slice_mod.root = slice_path slice_mod.file = slice_file

From the Library of Shirong Chen

196

Chapter 7: Slices

slice_mod.registered slice_mod else Object.full_const_get(module_name) end end

The snippet of source above reveals that register prefers the filename so that we can register multiple cascading slices of the same name. The two most important things to take away from this are that slice module names are inferred from the included file’s filename and that a second parameter allows us to turn off the cascading nature of slices by passing in false. Going back to lib/merb-forums-slice.rb, we come across the module MerbForumsSlice and can recognize its importance in being named such. At the start of this module is some metadata that could be used by the master application to identify what slices and slice versions it is using. Below this we find empty hook methods that will allow us to enhance the activation and deactivation of the module. The final and possibly most interesting section of the module is the router block. Though a config/router.rb exists for standardly generated Merb slices, it is intended only for testing isolated slices and not employed by slices that are activated through full apps. Instead, the method setup_router is used to scope slices relative to slice paths. This is critically important for the slice developer to remember: Router configuration happens in the slice file and requires the use of scope. Otherwise, routes are defined exactly the same.

7.1.2 Running slices Having generated a slice, we can fire it up as if it were an isolated application. We can use the command slice from within the slice’s top directory in the same way we would use merb: foysavas@nocturne:˜/src/merb-forums-slice$ slice -C Loading init file from /home/foysavas/src/merb-forumsslice/config/init.rb ˜ Loaded slice 'MerbForumsSlice' ... ˜ Parent pid: 11741 ˜ Activating slice 'MerbForumsSlice' ... merb : worker (port 4000) ˜ Starting Mongrel at port 4000 merb : worker (port 4000) ˜ Successfully bound to port 4000 merb : worker (port 4000) ˜ Interrupt a second time to quit. ˆC irb(main):001:0> MerbForumsSlice.version => "0.0.1"

From the Library of Shirong Chen

7.1

Slice development

197

As you can see, we were even able to use the console trap option -C and then pull up an IRB console for our slice. Additionally, if we visit localhost:4000, we’ll be presented with a simple page showing off the metadata from our slice. You may be interested in knowing how the slice command works and how it is different from the standard merb command. Opening up the executable file itself, we can differentiate the two: #!/usr/bin/env ruby require 'rubygems' require 'merb-core' # Start slice only stuff require 'merb-slices' _ _DIR_ _ = Dir.pwd slice_name = File.basename(_ _DIR_ _) Merb::Config.use { |c| c[:framework] = { :public => [Merb.root / "public", nil] } c[:session_store] = 'none' c[:exception_details] = true } if File.exists?(slice_file = File.join( _ _DIR_ _, 'lib', "#{slice_name}.rb")) Merb::BootLoader.before_app_loads do $SLICE_MODULE = Merb::Slices. filename2module(slice_file) require slice_file end Merb::BootLoader.after_app_loads do Merb::Router.prepare do slice($SLICE_MODULE) slice_id = slice_name.gsub('-', '_').to_sym slice_routes = Merb::Slices. named_routes[slice_id] || {} route = slice_routes[:home] || slice_routes[:index]

From the Library of Shirong Chen

198

Chapter 7: Slices if route params = route.params.inject({}) do |hsh,(k,v)| hsh[k] = v.gsub("\"", '') if k == :controller || k == :action

hsh end match('/').to(params) else match('/').to(:controller => 'merb_slices', :action => 'index') end end end else puts "No slice found (expected: #{slice_name})" exit end class MerbSlices < Merb::Controller def index html = "

#{slice.name}

"+ "

#{slice.description}

" html << "

Routes

#{name}: #{route.inspect}
#{name}: #{route.inspect}

" html end private

From the Library of Shirong Chen

7.1

Slice development

199

def slice @slice ||= Merb::Slices.slices.first end end # End slice only stuff ARGV.push '-H' if ARGV[0] && ARGV[0] =˜ /ˆ[ˆ-]/ unless %w[-a --adapter -i --irb-console -r --script-runner].any? { |o| ARGV.index(o) } ARGV.push *%w[-a mongrel] end Merb.start

We moved a line or two around, but otherwise you’ll find that slice is identical to merb, excluding the long section in the middle. This region of code handles, among many other things, finding and requiring the lib files, the creation of a default route, and the explicit setting up of a simple controller to display metadata if no other default action exists. One subtlety to notice, which may trip you up otherwise, is that in finding the appropriately named lib/ slice file, slice uses the present working directory name. In other words, the name of the directory containing the slice does in fact matter and should match the name of the lib/ slice file.

7.1.3 Building slices Building a slice into a gem is an incredibly easy part of the slice development process. All there is to be done is editing the Rakefile to set the appropriate gem specifications and then running the rake task install. This builds and installs a gem containing your slice. This gem can also be found in pkg/ and distributed to others directly or put up on a Ruby gem server. When required as a Merb dependency, the gem includes the slice application code as part of the full Merb application. Let’s take a look at the relevant sections of the Rakefile that make this work: require 'rubygems' require 'rake/gempackagetask' require 'merb-core' require 'merb-core/tasks/merb' GEM_NAME = "merb-forums-slice"

From the Library of Shirong Chen

200

Chapter 7: Slices

AUTHOR = "Your Name" EMAIL = "Your Email" HOMEPAGE = "http://merbivore.com/" SUMMARY = "Merb Slice that provides ..." GEM_VERSION = "1.0.1" spec = Gem::Specification.new do |s| s.rubyforge_ project = 'merb' s.name = GEM_NAME s.version = GEM_VERSION s.platform = Gem::Platform::RUBY s.has_rdoc = true s.extra_rdoc_files = ["README", "LICENSE", 'TODO'] s.summary = SUMMARY s.description = s.summary s.author = AUTHOR s.email = EMAIL s.homepage = HOMEPAGE s.add_dependency('merb-slices', '>= 1.0.6.1') s.require_path = 'lib' s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec,app,public,stubs}/**/*") end Rake::GemPackageTask.new(spec) do |pkg| pkg.gem_spec = spec end desc "Install the gem" task :install do Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION) end

As a slice developer, you may need to venture only as far as the constant lines to get your work done. However, we’ve also included the code for the install rake task to show off the usage of a Merb rake helper. Venturing into the source code of the Merb::RakeHelper is left as an exercise for the reader.

7.1.4 Slice controllers A number of methods are mixed into the AbstractController class and meant for use within Merb controller slices. For the most part these methods can be tucked away, leaving application code within a Merb slice indistinguishable. As an example, let’s open up the default-generated application controller within a slice:

From the Library of Shirong Chen

7.2

Slice usage

201

class MerbForumsSlice::Application < Merb::Controller controller_for_slice end

This lone class method does three things. First, it determines the slice module in which the class is resting, checks if it should be active, and if so stores a reference to the containing module under the class-inheritable reader slice. Second, it sets up proper template root directories for all inheriting slice controllers. Finally, it uses the method layout_for_slice to enhance the selection of the default layout so that we can specify a host-overriding slice layout for our templates. The easiest way to do so is to pass in a hash containing a key-and-value pair for :layout as a parameter to controller_for_slice.

7.2 Slice usage A number of methods are added to the router when the merb-slices gem is required. These methods are meant to bridge individual slices with the host application by allowing us to specify which routes should be handled by which slices. However, only one of these router extension methods is intended to be used by the application developer: slice. Below we have used it to add the forums slice to our host application. Merb::Router.prepare do slice(MerbForumsSlice) end

The most useful option that we can use with slice is path. It effectively prepends the route path to all slice routes. Below we push forums into the path /community. Merb::Router.prepare do slice(MerbForumsSlice, :path => '/community' end

Here’s the code for the slice extension method: def slice(slice_module, options = {}, &block) options[:path] ||= "" add_slice(slice_module, options.merge(:reset_controller_prefix => true), &block) end

The method merges in the option to reset the controller prefix. This is necessary because without it a controller prefix is used on the routes. Aside from that, slice basically

From the Library of Shirong Chen

202

Chapter 7: Slices

delegates to add_slice, another router extension method that we advise application developers to stay away from unless they intend to use a controller prefix. For the sake of clarity on other options, here’s the source to add_slice: def add_slice(slice_module, options = {}, &block) if Merb::Slices.exists?(slice_module) options = { :path => options } if options.is_a?(String) slice_module = Object.full_const_get( slice_module.to_s.camel_case) if slice_module.class.in?(String, Symbol) namespace = options[:namespace] || slice_module.identifier_sym options[:path] ||= options[:path_prefix] || slice_module[:path_prefix] || options[:namespace] || slice_module.identifier options[:prepend_routes] = block if block_given? slice_module[:path_prefix] = options[:path] Merb.logger.verbose!("Mounting slice ... ") @options[:controller_prefix] = nil if options.delete(:reset_controller_prefix) self.namespace(namespace, options.except( :default_routes, :prepend_routes, :append_routes, :path_prefix)) do |ns| Merb::Slices.named_routes[ slice_module.identifier_sym] = ns.capture do options[:prepend_routes].call(ns) if options[:prepend_routes].respond_to?(:call) slice_module.setup_router(ns). options[:append_routes].call(ns) if options[:append_routes].respond_to?(:call) end end else

From the Library of Shirong Chen

7.3

Conclusion

203

Merb.logger.info!("Skipped adding slice ... ") end self end

From the perspective of a student of the frameworks, the most interesting code above is in the lines where the route namespace is created. Particularly be aware of the use of the behavior method capture, which simply collects a hash of routes as they are added within its block without affecting the routes themselves in any way. This method, which you may have written off, actually allows Merb to store a partitioned list of routes related to particular slices, a necessity for the dynamic deactivation of slices.

7.3 Conclusion Merb slices are one of the most attractive features from an application developer’s perspective because they increase the ease and reusability of code. The second version of Merb was intended to make great strides toward dynamic activation of Merb slices and build an arsenal of slices for developers to share. However, given the merge, such work has been put on hold until a similar system is settled upon within Rails 3.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 8

Sessions

Sessions allow an application to customize the responses sent out to different users. They do this by enabling us to store data about each session and use that data as the foundation for statefulness between requests. When used in conjunction with user authentication, session data also means that we can trust that a request comes from a particular user without having to reauthenticate on subsequent requests. Strictly speaking, HTTP is a stateless protocol, and every request that comes to an HTTP server is treated like any other. However, at an application level we can transcend the limitations of statelessness using sessions. If we had to construct sessions from the ground up, we would have to design a way to distribute HTTP cookies with session IDs and then session data stored either client- or server-side. However, Merb’s builtin session support eliminates the need to do any of this work, typically streamlining it down to the selection of configuration options and interaction with a hash named session. Merb’s emphasis on hackabiliy is not lost, however, through the streamlining of session maintenance. In this chapter we’ll explore the construction of session containers and stores and find that building them poses little difficulty to the developer with such a need. One warning, though: Sessions also incidentally bring up security concerns, but we’ll point these out when they arrive and explain how to deal with them.

8.1 How sessions work Assuming that sessions are enabled on a Merb application, a session ID is established for each capable browser that sends a request. This session ID is stored client-side as an encrypted value inside an HTTP cookie. All subsequent requests made by the user’s browser will include this cookie as a header, and Merb will decrypt the session ID 205 From the Library of Shirong Chen

206

Chapter 8: Sessions

from it. In this way we can establish and maintain the identity of the individual users of our application. However, data related to each session must be stored separately, and Merb provides us with multiple storage options. These include saving data in memory, in a database, cached with memcache, or even within the HTTP cookie itself. Each of these options is appropriate under different conditions. We’ll go over when and how to use them later on.

8.2 Conﬁguration Not all applications need sessions to the same degree and some do not need them at all. At the same time, different environments make different demands on how session data must be stored and accessed. For these reasons, our sessions must be configured. Configuration is typically done in either config/init.rb or one of the environment files in config/environments. Remember that any configuration settings made in an environment file override what is in the init script. Consequently, the configuration in the init script tends to be the development configuration and acts only as a template for the other environments. There are five basic values for configuration that can be set, but depending on the storage mechanism there may be additional settings to configure: • session_store—the type of session to use: cookie, memory, memcache, container,

datamapper, etc. • session_id_key—defaults to _session_id but can be useful when you need to

differentiate sessions for the same domain • session_expiry—defaults to two weeks but its value can be set as an integer in

seconds • session_secret_key—a string of at least 16 chars used for the encryption of the

cookie session store • default_cookie_domain—the domain the cookies are for

Typically, some of these values are set from within config/init.rb as follows: Merb::Config.use do |c| c[:session_store] = 'cookie' c[:session_secret_key] = 'theywontguessthis' c[:session_id_key] = '_app_session_id' end

From the Library of Shirong Chen

8.3

Storing sessions

207

8.3 Storing sessions The mechanics behind sessions are for the most part not necessary for an application developer to know. However, in the interest of understanding the tools we use, we’ll cover the topic in some detail. Before jumping in, you should know that there are two central classes to sessions storage: SessionContainer and SessionStoreContainer.

8.3.1 Session containers The fundamental structure storing individual session data in Merb is a session container. The class SessionContainer inherits from Mash, making its keys accessible by either symbol or equivalent string. The reason the Mash class has been used here again is so that request parameter data may easily be stored within session containers without complication. module Merb class SessionContainer < Mash class_inheritable_accessor :session_store_type cattr_accessor :subclasses self.subclasses = [] # :api: private attr_reader :session_id # :api: private attr_accessor :needs_new_cookie class << self def inherited(klass) self.subclasses << klass.to_s super end # :api: private def generate end # :api: private def setup(request) end end # :api: private

From the Library of Shirong Chen

208

Chapter 8: Sessions def initialize(session_id) @_destroy = false self.session_id = session_id end # :api: private def session_id=(sid) self.needs_new_cookie = (@session_id && @session_id != sid) @session_id = sid end # :api: private def finalize(request) end # :api: private def clear! @_destroy = true self.clear end # :api: private def regenerate end

end end

Nearly all the methods of SessionContainer are effectively stubs. This is because the class is intended to be made more concrete through various subclasses of containers for particular storage mechanisms. We get a feel for this through the subclasses class attribute, which is used upon inheritance to grow a list of subtypes. The class methods setup and generate are used to indirectly initialize a new store with a unique session ID. Along with the instance methods finalize and regenerate, a more concrete container class has to define this method. However, both clear! and session_id= are basically in their final forms; clear simply empties the mash and session_id= changes the ID while making clear that a new cookie is needed. The method session_id= has been built with cases where a session ID needs to be exposed and a new one used to avoid compromising the session.

8.3.2 Session store containers Some session containers also need to be stored server-side. This is accomplished by making use of the class SessionStoreContainer, which itself actually inherits from

From the Library of Shirong Chen

8.3

Storing sessions

209

the class StoreContainer. Let’s take a look at the added-on and no longer stubbed methods of this class: class Merb::SessionStoreContainer < SessionContainer class_inheritable_accessor :store # :api: private attr_accessor :_fingerprint self.session_store_type = :store class << self # :api: private def generate session = new(Merb::SessionMixin.rand_uuid) session.needs_new_cookie = true session end # :api: private def setup(request) session = retrieve(request.session_id) request.session = session session._fingerprint = Marshal.dump(request.session.to_hash).hash session end private # :api: private def retrieve(session_id) unless session_id.blank? begin session_data = store.retrieve_session(session_id) rescue => err Merb.logger.warn!("Could not retrieve session") end # Not in container, but assume that cookie exists session_data = new(session_id) if session_data.nil? else # No cookie...make a new session_id session_data = generate end if session_data.is_a?(self)

From the Library of Shirong Chen

210

Chapter 8: Sessions session_data else new(session_id).update(session_data) end end

end # :api: private def finalize(request) if @_destroy store.delete_session(self.session_id) request.destroy_session_cookie else if _fingerprint != Marshal.dump(data = self.to_hash).hash begin store.store_session(request.session( self.class.session_store_type).session_id, data) rescue => err Merb.logger.warn!("Could not persist session") end end if needs_new_cookie || Merb::SessionMixin.needs_new_cookie? request.set_session_id_cookie(self.session_id) end end end # :api: private def regenerate store.delete_session(self.session_id) self.session_id = Merb::SessionMixin.rand_uuid store.store_session(self.session_id, self) end end end

The first thing you should notice is that a new class-inheritable attribute store has been added. This bridges the container with its storage mechanism. There’s also a fingerprint, which is used to recognize the dirtiness of a yet-to-be-persisted container.

From the Library of Shirong Chen

8.3

Storing sessions

211

Moving on, the class methods setup and generate have been filled in and are now ready to generate unique IDs and create store instances. A private class method retrieve looks to find existing stores and is used by setup to assure uniqueness. It’s also capable of moving stored session data from one session store type to another. The other two previously stubbed methods, finalize and regenerate, are also fleshed out. The former is used to persist data (note the use of store) and the latter to refresh the session ID.

8.3.3 Session storage mechanisms There are multiple storage mechanisms that implement the previously described session stores. We’ll go through each of these, starting off not necessarily with the simplest, but with the only one to use SessionContainer directly, CookieSession.

8.3.3.1 Cookie sessions Cookie sessions have been designed to keep all of the session data client-side. This eliminates the need for a storage mechanism client-side but comes at the cost of limited session size and possible security implications. Let’s open up the source for this session type: require 'base64' require 'openssl' class Merb::CookieSession < Merb::SessionContainer class CookieOverflow < StandardError; end class TamperedWithCookie < StandardError; end # Cookies can typically store 4096 bytes. MAX = 4096 DIGEST = OpenSSL::Digest::Digest.new('SHA1')

# :api: private attr_accessor :_original_session_data self.session_store_type = :cookie

Above we see that CookieSession inherits directly from SessionContainer and does not use any store mechanisms. It also sets a limitation on size, 4K. This limitation is necessary as it is the largest cookie size allowed by some browsers. The use of OpenSSL will become clear as we see the digest above used to encrypt the cookie session data.

From the Library of Shirong Chen

212

Chapter 8: Sessions

class << self # :api: private def generate self.new(Merb::SessionMixin.rand_uuid, "", Merb::Request._session_secret_key) end # :api: private def setup(request) session = self.new(Merb::SessionMixin.rand_uuid, request.session_cookie_value, request._session_secret_key) session._original_session_data = session.to_cookie request.session = session end end

The class methods generate and setup have been filled in above. The first simply generates a new cookie session, generating a session ID by way of UUID and encrypting it with the application’s configure secret session key. The setup method does nearly that but passes in preexisting cookie values so that they may also be stored. The conversion of session data to a cookie format may be of interest: # :api: private def to_cookie unless self.empty? data = self.serialize value = Merb::Parse.escape( "#{data}--#{generate_digest(data)}") if value.size > MAX msg = "Cookies have limit of 4K." Merb.logger.error!(msg) raise CookieOverflow, msg end value end end

Here we see that the data is serialized (by a method we have yet to encounter) and compounded with a message digest. If, however, the data stretches over the 4K max, an overflow error is raised. In practice, you should limit the size of session data when using cookie sessions mainly to storing things like related model object IDs.

From the Library of Shirong Chen

8.3

Storing sessions

213

protected # :api: private def serialize Base64.encode64(Marshal.dump(self.to_hash)).chop end # :api: private def unserialize(data) Marshal.load(Base64.decode64(data)) rescue {} end private # :api: private def generate_digest(data) OpenSSL::HMAC.hexdigest(DIGEST, @secret, data) end

Here we see the methods that serialize the session data for the cookie. Note that assuming users on the client side know enough to figure out that the data was encoded with Base64, the actual data of the session is clear. Consequently, do not under any circumstances store sensitive data in a cookie session. The inability of users to hijack other users’ cookie sessions, however, is made possible through the message digest generated through generate_digest. This hash of the data incorporates our session secret, meaning that unless it is compromised client-altered session data, it should not be possible. # :api: private def unmarshal(cookie) if cookie.blank? {} else data, digest = Merb::Parse.unescape(cookie). split('--') return {} if data.blank? || digest.blank? unless digest == generate_digest(data) clear unless Merb::Config[:ignore_tampered_cookies] raise TamperedWithCookie, "..." end end unserialize(data)

From the Library of Shirong Chen

214

Chapter 8: Sessions

end end # ... end

Above we witness how the unmarshaling of the data does in fact raise the error TamperedWithCookie if the incoming digest does not hash out correctly. Note that we

can also prevent this error from being raised (perhaps for testing) by setting a configuration value to ignore_tampered_cookies. Though there are other methods to explore within this class, we’ve encountered those most fundamental and characteristic of cookie sessions themselves and will leave the other methods, if of interest, to the reader.

8.3.3.2 Memory sessions Memory sessions are possibly the second-easiest way to set up sessions and probably your best bet when doing application development and testing. However, they do require that all Merb workers behave in a thread-safe manner when accessing session data. Even more important for production environments, they prohibit the distribution of Merb workers across several physical devices. In any case, let’s explore the source behind memory sessions, taking away some lessons on thread safety as well as the structure of the more complex session stores: module Merb class MemorySession < SessionStoreContainer self.session_store_type = :memory # :api: private def store self.class.store end # :api: private def self.store @_store ||= MemorySessionStore.new( Merb::Config[:memory_session_ttl]) end end

The fundamental difference between session store containers and regular session containers is that the former must connect to some storage mechanism. Above we see

From the Library of Shirong Chen

8.3

Storing sessions

215

this as MemorySessionStore. Note that memory session stores are also time-limited and that we can set this limit with the configuration variable memory_session_ttl. class MemorySessionStore # :api: private def initialize(ttl=nil) @sessions = Hash.new @timestamps = Hash.new @mutex = Mutex.new @session_ttl = ttl || Merb::Const::HOUR start_timer end

With the initialization of the class MemorySessionStore, we see a mutual exclusion lock that prevents simultaneous access of session data. Additionally, the time limitation comes into play and defaults to one hour. Let’s pull up the start_timer method to see how it will work: # :api: private def start_timer Thread.new do loop { sleep @session_ttl reap_expired_sessions } end end # :api: private def reap_expired_sessions @timestamps.each do |session_id,stamp| delete_session(session_id) if (stamp + @session_ttl) < Time.now end GC.start end

A new thread with a simple loop, sleeping for the required time, repeatedly calls up the reaping of sessions. During the reap, sessions that have not been updated in the specified number of seconds are deleted. Interestingly, the garbage collector is forcibly invoked to assure the reduction of memory used. # :api: private def retrieve_session(session_id) @mutex.synchronize { @timestamps[session_id] = Time.now

From the Library of Shirong Chen

216

Chapter 8: Sessions @sessions[session_id] } end # :api: private def store_session(session_id, data) @mutex.synchronize { @timestamps[session_id] = Time.now @sessions[session_id] = data } end

# :api: private def delete_session(session_id) @mutex.synchronize { @timestamps.delete(session_id) @sessions.delete(session_id) } end end end

The final three methods are essential to any store, allowing sessions to be individually manipulated or deleted. Though there isn’t much of anything special in them, focus on the use of Mutex#synchronize and the combined setting of a timestamp along with session data. If you need to create your own custom store, the methods shown above will serve well as an initial template, especially for thread safety.

8.3.3.3 Memcached sessions The code behind a memcache session is actually remarkably simple, because really, memcache itself does all the work. Opening up the source, we find the following: module Merb class MemcacheSession < SessionStoreContainer self.session_store_type = :memcache end module MemcacheStore # :api: private def retrieve_session(session_id)

From the Library of Shirong Chen

8.3

Storing sessions

217

get("session:#{session_id}") end # :api: private def store_session(session_id, data) set("session:#{session_id}", data) end # :api: private def delete_session(session_id) delete("session:#{session_id}") end end end

Notably absent is a definition of store. This is because it is expected that you will define it from within a configuration (or preferably environment) file: Merb::BootLoader.after_app_loads do require 'memcache' Merb::MemcacheSession.store = MemCache.new('127.0.0.1:11211', :namespace => 'app') end

Pay special attention to the need to require the memcache gem as well as to have the code placed within an after_app_loads block.

8.3.3.4 DataMapper sessions DataMapper sessions are an alternative way to accomplish production-suitable sessions without the need for a memcache server. This may suit the needs of smaller production environments where putting up memcache is not a possibility. However, we still strongly recommend not using database sessions if for no other reason than session data is retrieved frequently, and memcache is designed to handle that better. Nonetheless, as an exploration of the versatility of Merb sessions, let’s take a look at how it’s done: module Merb class DataMapperSession < SessionStoreContainer self.session_store_type = :datamapper self.store = DataMapperSessionStore end

There’s nothing special so far, but by now you should be capable of making your own store and connecting it to the container.

From the Library of Shirong Chen

218

Chapter 8: Sessions

class DataMapperSessionStore include ::DataMapper::Resource table_name = Merb::Plugins. conf[:merb_datamapper][:session_storage_name] || 'sessions' storage_names[default_repository_name] = table_name def self.default_repository_name Merb::Plugin. conf[:merb_datamapper][:session_repository_name] || :default end

In this way, a DataMapper resource has effectively been created, but special attention has been given to the name of the table and the repository to use. These two variables can be altered within our configuration files. property :session_id, String, :size => 32, :nullable => false, :key => true property :data, Object, :default => {}, :lazy => false property :created_at, DateTime, :default => Proc.new { |r, p| DateTime.now }

The three properties above form the basis of DataMapper session storage. Note that created_at has used its own Proc, meaning that no requirements on dm-timestamps

are made. Additionally, we see a good use of the database-admin-frightening property type Object. It’s important that it’s not lazy-loaded since its primitive type is Text, and we will want to access the session data whenever we pull up the record. def self.retrieve_session(session_id) if session = get(session_id) session.data end end def self.store_session(session_id, data) if session = get(session_id) session.update_attributes(:data => data) else create(:session_id => session_id, :data => data) end end def self.delete_session(session_id)

From the Library of Shirong Chen

8.4

Request access

219

all(:session_id => session_id).destroy! end end end

Finally, the three methods we’ve come to expect appear again, this time using the DataMapper retrieval methods to do their work.

8.4 Request access Within Merb, sessions are glued onto their associated requests. To accomplish this, the RequestMixin adds several methods to the Request class. Only the first is of importance to the typical application developer, so we’ll take a look at it, letting the reader dig deeper if desired. module Merb::Session::SessionMixin::RequestMixin # :api: public def session(session_store = nil) session_store ||= default_session_store if class_name = self.class.registered_session_types[session_store] session_stores[session_store] ||= Object.full_const_get(class_name).setup(self) elsif fallback = self.class.registered_session_types.keys.first Merb.logger.warn "Session store not found." Merb.logger.warn "Falling back." session(fallback) else msg = "No session store set." Merb.logger.error!(msg) raise NoSessionContainer, msg end end

Note that if we are using multiple session stores, we can specify the desired one to check inside. If it’s not found, Merb falls back to the first session store defined. A practical use of the method from the application developer’s perspective would be the use of session data from inside router deferral blocks.

From the Library of Shirong Chen

220

Chapter 8: Sessions

8.5 Controller access The controller also needs access to the session. This is likewise accomplished through a controller session mixin: module Merb::Session::SessionMixin # :api: public def session(session_store = nil) request.session(session_store) end module RequestMixin # ... end end

Here we see that the session method simply delegates to the method we saw defined within the request mixin. It is somewhat intriguing that the RequestMixin we saw a moment ago is actually embedded within the controller mixin. This kind of organization is typical among Merb request enhancements and minimizes redundancy. Anyway, as application developers, we have full access to the session data via this method, and treating it as a hash can set its values.

8.6 Conclusion Merb handles sessions in such a way that application developers do not have to be aware of the storage mechanisms being used. Nonetheless, the limitations and security implications behind some session storage, mainly cookie storage, demand the developer’s awareness when they are used. Our exploration of the internals of both session containers and stores should make it easy to extend Merb sessions as needed for custom or composite storage mechanisms when the nearly standard production use of memcache will not do.

From the Library of Shirong Chen

C HAPTER 9

Authentication

Nearly all web applications need to authenticate their users, but how they authenticate them varies. The Merb stack, however, includes a highly modular authentication plugin that gives us a miniature stack of minimally constraining tools that together offer us out-of-the-box authentication within our applications. Created by Daniel Neighman, the Merb auth plugin went through several intense iterations. Before long, however, its design came to exemplify the principle of Merb itself and without hesitation was included within the stack, ultimately because its modularity countered the contentions of custom authentication so strongly. This also makes it one of the absolute best plugins from which to learn, so we’re going to explore it nearly in its entirety. We recommend that you take your time and keep several goals in mind while we do so. First, as a Merb application developer, remember the methods that you’ll need to use. These will also be listed among other documentation, however, so another goal should be obtaining a deeper understanding of how they work. From the perspective of a Merb plugin developer, you should also pick up on the structural considerations apparent throughout the plugin. Various techniques will indubitably come in handy during the construction of your own plugins. Last, as a student of Merb’s design itself, look to this chapter to impart a deeper understanding of the envisioned extensibility of Merb.

9.1 Auth core The core part of merb-auth is divided into several sections. We can find the code breakdown spelled out in the file lib/merb-auth-core.rb: require 'merb-auth-core/authentication' require 'merb-auth-core/strategy'

221 From the Library of Shirong Chen

222 require require require require require require require require

Chapter 9: Authentication 'merb-auth-core/session_mixin' 'merb-auth-core/errors' 'merb-auth-core/responses' 'merb-auth-core/authenticated_helper' 'merb-auth-core/customizations' 'merb-auth-core/bootloader' 'merb-auth-core/router_helper' 'merb-auth-core/callbacks'

Merb::BootLoader.before_app_loads do Merb::Controller.send(:include, Merb::AuthenticatedHelper) end Merb::Plugins.add_rakefiles "merb-auth-core/merbtasks" Merb.push_path(:lib_authentication, Merb.root_path("merb" / "merb-auth"), "*.rb" )

We’ll go through the significance and use of each of the files within this section. Note the use of before_app_loads for the inclusion of the authenticated helper. These lines exemplify the common need for methods defined in a plugin to be loaded before application code is loaded, lest the application code blow up. This is because the authenticated helper adds a method, ensure_authenticated, which the application developer may use to ensure the authentication of users. We can also spot the use above of Plugins.add_rakefiles to include various rakefile tasks. This appends rakefiles to the array Merb.rakefiles, which are all iteratively required within the standardly generated Merb application rakefile. Finally, the use of Merb.push_path is a method that adds files for inclusion within our Merb application. For the authentication plugin, and many other plugins, this is critical because it allows for particular code to be contained within the application itself, overriden by the developer as necessary. In the case of the authentication plugin, there are two such files of importance: setup.rb and strategies.rb. Let’s look at the first of these two: Merb::Authentication.user_class = User require 'merb-auth-more/mixins/salted_user' Merb::Authentication.user_class.class_eval do include Merb::Authentication::Mixins::SaltedUser end class Merb::Authentication def fetch_user(session_user_id) Merb::Authentication.user_class.get(session_user_id) end

From the Library of Shirong Chen

9.1

Auth core

223

def store_user(user) user.nil? ? user : user.id end end

The first thing this does, and that you may need to change, is select which model class will be used for authentication. The standard class is User, as we can see above, but if your application demands that it be something else, such as Person, changing the value within setup.rb allows you to use the authentication plugin without issue. The next few lines add in the salted user mixin. We’ll see the code for this later on, but for now know that this adds properties and methods to the user model for authentication. The last section of the code opens up the Authentication class, adding in two methods. The first wraps the manner of retreiving a user by ID, and the second defines how a user should be stored within a session. Don’t let the tertiary operator confuse you, however. All that’s being said is that a user’s ID alone should be stored within the session store. Now let’s take a look at the second file, strategies.rb: Merb::Slices::config[:"merb-auth-slice-password"][: no_default_strategies] = true Merb::Authentication.activate!(:default_password_form) Merb::Authentication.activate!(:default_basic_auth)

We see that the default strategies are cleared out and then two of them are reactivated. We’ll find out more about this soon, but from this alone we get a feel for how the application developer can interact with cascading authentication strategies.

9.1.1 Authentication Let’s take a look at parts of the first file required by the authentication core, which defines Merb::Authentication: module Merb class Authentication module Strategies; end include Extlib::Hook attr_accessor :session attr_writer :error_message class DuplicateStrategy < Exception; end class MissingStrategy < Exception; end class NotImplemented < Exception; end

From the Library of Shirong Chen

224

Chapter 9: Authentication def initialize(session) @session = session end def authenticated? !!session[:user] end def user return nil if !session[:user] @user ||= fetch_user(session[:user]) end def user=(user) session[:user] = nil && return if user.nil? session[:user] = store_user(user) @user = session[:user] ? user : session[:user] end def abandon! @user = nil session.clear end

Note that the contained module Strategies is stubbed and will be used later on to contain various means of authentication. The inclusion of Extlib::Hook is also noteworthy; it allows the authentication plugin to make particular methods hookable for the application developer. Moving on to the methods, we can see that an authentication is tightly coupled with a session store. It also specifically stores user data within the session store under the key :user. This means that application developers should stay away from using this key for other purposes. The double bang within the authenticated? method assures that either true or false is returned even if session[:user is nil. The method user returns nil whenever the session user key isn’t holding a user. Otherwise, it fetches the user or, if that has already been done, returns a memoized user. The corresponding writer method delegates to the method store_user, which we previously saw in setup.rb. Going further into the file, we can see stubs for a number of methods, all labeled API overwritable: # @api overwritable cattr_accessor :user_class # @api overwritable def error_message @error_message || "Could not log in" end

From the Library of Shirong Chen

9.1

Auth core

225

# @api overwritable def store_user(user) raise NotImplemented end # @api overwritable def fetch_user(session_contents = session[:user]) raise NotImplemented end

Some of these are the same methods we saw in setup.rb. The overwritable therefore specifies that they can be defined within that file by the application developer. The crown jewel of the Authentication class, however, is the method authenticate!. Here it is in full: def authenticate!(request, params, *rest) opts = rest.last.kind_of?(Hash) ? rest.pop : {} rest = rest.flatten strategies = if rest.empty? if request.session[:authentication_strategies] request.session[:authentication_strategies] else Merb::Authentication.default_strategy_order end else request.session[:authentication_strategies] ||= [] request.session[:authentication_strategies] << rest request.session[:authentication_strategies]. flatten!.uniq! request.session[:authentication_strategies] end msg = opts[:message] || error_message user = nil strategies.detect do |s| s = Merb::Authentication.lookup_strategy[s] unless s.abstract? strategy = s.new(request, params) user = strategy.run! if strategy.halted? self.headers, self.status, self.body = [strategy.headers, strategy.status, strategy.body] halt! return end

From the Library of Shirong Chen

226

Chapter 9: Authentication user end end user = run_after_authentication_callbacks(user, request, params) if user raise Merb::Controller::Unauthenticated, msg unless user session[:authentication_strategies] = nil self.user = user end

The method takes three arguments: a request, parameters, and an optional array of strategies that may also end with a hash of options. After a sorting out which strategies are to be employed through authentication, the method iterates through these using the Ruby enumerable method detect. This returns the succeeding strategy name as soon as its block evaluates to true. The block itself pulls up a strategy using the lookup_strategy method and then calls the run! method as a means of strategic delegation. If successful, a user is authenticated, but a halted strategy can also induce immediate overall failure. Finally, an application developer should be aware of the use of run_after_authentication_callbacks to serially make callbacks after authentication. Let’s finish off the code for this class by looking at some of the methods used within authenticate!: # @private def self.lookup_strategy @strategy_lookup || reset_strategy_lookup! end def self.reset_strategy_lookup! @strategy_lookup = Mash.new do |h,k| case k when Class h[k] = k when String, Symbol h[k] = Merb::Authentication::Strategies. full_const_get(k.to_s) end end end private

From the Library of Shirong Chen

9.1

Auth core

227

def run_after_authentication_callbacks(user, request, params) Merb::Authentication.after_callbacks.each do |cb| user = case cb when Proc cb.call(user, request, params) when Symbol, String user.send(cb) end break unless user end user end end end

The first two of these deal with strategy lookup, the first being a memoization that defaults to the second, which effectively stores all authentication strategies into a mash. The final and private method handles authentication callbacks. In a later subsection we’ll see how application developers can make use of these.

9.1.2 Strategy The Strategy class is important in that it defines a common structure with which the auth plugin can interface during user authentication. In the source file for this class, we see that the first step is the extension of the Authentication class: module Merb class Authentication cattr_reader :strategies, :default_strategy_order, :registered_strategies @@strategies, @@default_strategy_order, @@registered_strategies = [], [], {} # @public def self.default_strategy_order=(*order) order = order.flatten bad = order.select{ |s| !s.ancestors.include?(Strategy)} raise ArgumentError, "..." unless bad.empty? @@default_strategy_order = order end # @plugin

From the Library of Shirong Chen

228

Chapter 9: Authentication def self.register(label, path) self.registered_strategies[label] = path end def self.activate!(label) path = self.registered_strategies[label] raise "The #{label} Strategy is not registered" unless path require path end

The class variables, which have been made redundantly read-accessible through cattr_reader, are used to store a list of strategies. The reason the class method register is labeled as an API plugin is that it is meant to be used by merb-authmore and possibly other auth strategy plugins.

Moving on to the Strategy class, we can comprehend the manner by which strategies are to be designed. Let’s start by looking only at class methods: class Strategy attr_accessor :request attr_writer :body class << self def inherited(klass) Merb::Authentication.strategies << klass Merb::Authentication.default_strategy_order << klass end def before(strategy) order = Merb::Authentication.default_strategy_order order.delete(self) index = order.index(strategy) order.insert(index,self) end def after(strategy) order = Merb::Authentication.default_strategy_order order.delete(self) index = order.index(strategy) index == order.size ? order << self : order.insert(index + 1, self) end

From the Library of Shirong Chen

9.1

Auth core

229

def abstract! @abstract = true end def abstract? !!@abstract end end # End class << self

First notice the use of the inherited method to assure that the class is appended to the list of strategies. Consequently, the default strategy order is determined by the order in which the strategies are defined. This isn’t permanently necessary, however, as the two class methods before and after allow us to reinsert a strategy before or after some particular strategy. Finally, the methods abstract! and abstract? will be used later on to determine if a strategy is treated concretely or not. Let’s now take a look at the instance methods. Insofar as the Strategy class is an abstraction of the strategy interface, these form a basis upon which strategies must be developed. def initialize(request, params) @request = request @params = params end def params @params end def cookies request.cookies end def session request.session end def redirect!(url, opts = {}) self.headers["Location"] = url self.status = opts[:permanent] ? 301 : 302 self.status = opts[:status] if opts[:status] self.body = opts[:message] || "

You are being redirected ...

" halt!

From the Library of Shirong Chen

230

Chapter 9: Authentication return true end def redirected? !!headers["Location"] end attr_accessor :status def headers @headers ||={} end def halt! @halt = true end def halted? !!@halt end def body @body || "" end

The initialize method takes two parameters, request and request parameters. A strategy object should therefore be understood to be tightly coupled with particular requests. Here a number of these methods are simply designed to proxy to an underlying method. The redirect method is particularly interesting in that it allows strategies to halt authentication and have Merb pursue immediate redirect. The methods halt! and halted? are the ones that set and get whether a strategy object has been halted or not. # @api overwritable def run! raise NotImplemented end # @api overwritable def user_class Merb::Authentication.user_class end end end end

From the Library of Shirong Chen

9.1

Auth core

231

Finally, we again see the method user_class, which is used here to give access to the user model class to strategy objects. We also see an abstract method run!, which is used by all concrete classes to define the precise manner of authentication.

9.1.3 Sessions The ubiquitousness of the auth plugin is made clear by how many other classes and modules it opens up. Here we see what additions it makes to the Session module: module Merb module Session def authentication @authentication ||= Merb::Authentication.new(self) end def authenticated? authentication.authenticated? end def authenticate!(request, params, *rest) authentication.authenticate!(request, params, *rest) end def user authentication.user end def user=(the_user) authentication.user = the_user end def abandon! authentication.abandon! end end end

Since these methods are the ones application developers will find themselves using the most, be sure to remember them. They are all accessible through the session object and can be collectively used to set, check, initialize, or abandon authentication.

From the Library of Shirong Chen

232

Chapter 9: Authentication

9.1.4 Errors Authentication errors are a means of storing error messages when authentication fails. Let’s take a quick look at the file that does this: module Merb class Authentication def errors @errors ||= Errors.new end class Errors include Enumerable def clear! errors.clear end def add(field_name, message) (errors[field_name] ||= []) << message end def full_messages errors.inject([]) do |list,pair| list += pair.last end end def on(field_name) errors_for_field = errors[field_name] errors_for_field.blank? ? nil : errors_for_field end def each errors.map.each do |k,v| next if v.blank? yield(v) end end def empty? entries.empty? end def method_missing(meth, *args, &block) errors.send(meth, *args, &block) end

From the Library of Shirong Chen

9.1

Auth core

233

private def errors @errors ||= {} end end end end

You’ll see that, for the most part, it is a reimplementation of what we find in the DataMapper validation plugin. Consequently, we’ll be able to use the method error_messages_for on the authentication object as if it were a validatable model.

9.1.5 Responses Authentication strategies can push out responses for use by Merb directly. In order to facilitate this, the file responses.rb layers in various methods (which we actually saw being referenced previously) within the class Authentication: module Merb class Authentication attr_accessor :body def redirected? !!headers["Location"] end def headers @headers ||= {} end def status @status ||= 200 end def status=(sts) @status = sts end def halted? !!@halt end def headers=(headers) raise ArgumentError, "..." unless

From the Library of Shirong Chen

234

Chapter 9: Authentication headers.kind_of?(Hash) @headers = headers end def halt! @halt = true end

end end

Notice how the default status level is 200, and "Location" is the header key used for redirects. It’s clear from this that Merb auth, like Merb itself, is designed to work in an HTTP world.

9.1.6 Helpers The single controller helper method that comes along with the auth plugin is ensure_authenticated. We saw its containing module previously included before the Merb application code loads. Nonetheless, here is the source to the actual method: module Merb class Controller::Unauthenticated < ControllerExceptions::Unauthorized; end module AuthenticatedHelper protected def ensure_authenticated(*strategies) session.authenticate!(request, params, *strategies) unless session.authenticated? auth = session.authentication if auth.halted? self.headers.merge!(auth.headers) self.status = auth.status throw :halt, auth.body end session.user end end end

The method itself is protected so that it won’t appear as a controller action. It also accepts strategies as an optional list; when absent, the method authenticate! uses the default strategy list instead. In an application controller, this method may be used with a before filter:

From the Library of Shirong Chen

9.1

Auth core

235

class Application < Merb::Controller before :ensure_authenticated end

Here we have locked out all unauthenticated requests.

9.1.7 Router helper The router helper extends the Merb router with a method authenticate. Application developers can use this to alternatively demand authentication from within the router as opposed to within controllers. Merb::Router.extensions do def authenticate(*strategies, &block) p = Proc.new do |request, params| if request.session.authenticated? params else if strategies.blank? result = request.session.authenticate!(request, params) else result = request.session.authenticate!(request, params, *strategies) end if request.session.authentication.halted? auth = request.session.authentication [auth.status, auth.headers, auth.body] else params end end end defer(p, &block) end end

Interestingly, the method first creates a new Proc that is used by the defer method, which you may recall from our discussion of routers. Within the Proc, the first thing checked is whether authentication has already occurred or not. If so, the request params are immediately passed along. Otherwise, logic that imitates what we found in ensure_authenticated relays to the method authenticate!. As long as no authentication strategy led to a halt, params are passed, but in the case when a halt was encountered, the triplet of status, headers, and body form the immediate Merb response.

From the Library of Shirong Chen

236

Chapter 9: Authentication

9.1.8 Customizations Merb auth core defines a class method customize_default that can be used to append extra blocks to run by its own boot loader. Below we see both the definition of this method along with the creation of the MerbAuthBootLoader. Both of these will be used later by the Merb auth password slice. module Merb class Authentication class << self def customize_default(&block) default_customizations << block default_customizations end def default_customizations @custom_default_blocks ||= [] end end end end class Merb::BootLoader::MerbAuthBootLoader < Merb::BootLoader before Merb::BootLoader::AfterAppLoads def self.run Merb::Authentication.default_customizations.each { |c| c.call } end end

9.1.9 Callbacks At the beginning of this section, we encountered the invoking of callbacks. Now let’s discover how application developers can create these callbacks. Here is the source that enables us to do this: module Merb class Authentication

From the Library of Shirong Chen

9.2

Auth more

237

cattr_accessor :after_callbacks @@after_callbacks = [] # @api public def self.after_authentication(*callbacks, &block) self.after_callbacks = after_callbacks + callbacks.flatten unless callbacks.blank? after_callbacks << block if block_given? end end end

Here we find the class method after_authentication appending to the array after_callbacks. In some cases it appends method names as callbacks. These must be user model instance methods. In other cases, it simply appends an unnamed block if one is given. Looking back to how these callbacks are invoked by the method run_after_authentication_callbacks, we remember that these blocks are provided three parameters: the user (if authenticated), the request, and the request params. It is also important to realize that the return value of our callback will be used to reset the value of user. As application developers, we can therefore make final adjustments through these callbacks, potentially further filtering authentication by returning a nontrue value through our callback.

9.2 Auth more Merb auth more contains the strategies used by a standard Merb application for authentication. Opening the file lib/merb-auth-more.rb, we can see an outline of the strategies provided: if defined?(Merb::Plugins) basic_path = File.expand_path(File.dirname(_ _FILE_ _)) / "merb-auth-more" / "strategies" / "basic" Merb::Authentication.register(:default_basic_auth, basic_path / "basic_auth.rb") Merb::Authentication.register(:default_openid, basic_path / "openid.rb") Merb::Authentication.register(:default_password_form, basic_path / "password_form.rb")

From the Library of Shirong Chen

238

Chapter 9: Authentication

Merb::Plugins.add_rakefiles "merb-auth-more/merbtasks" end

The method Authentication.register, which we saw in the auth core, is used to name and establish the path to the strategies to be used. We’ll first go through each of these and then also take a look at more general modifications Merb auth more makes to Merb.

9.2.1 Strategies All strategies use a base class, aptly named Base. Let’s open up its source to get a feel for what it does and what all strategies have in common: class Merb::Authentication module Strategies module Basic class Base < Merb::Authentication::Strategy abstract! def self.password_param (Merb::Plugins.config[:"merb-auth"][:password_param] || :password).to_s.to_sym end # Overwrite this method to customize the field def self.login_param (Merb::Plugins.config[:"merb-auth"][:login_param] || :login).to_s.to_sym end def password_param @password_param ||= Base.password_param end def login_param @login_param ||= Base.login_param end end end end end

It is easy to overlook the use of the class method abstract!, which as we discovered while looking through the auth core makes the strategy abstract. The effect is that we can programmatically recognize that it should not be used among the strategy cascade.

From the Library of Shirong Chen

9.2

Auth more

239

The most important methods it defines are the class methods password_param and login_param. These two methods allow us to use plugin config values in place of the default symbols :login and :password. These are carried over to instance methods as well.

9.2.1.1 Basic The basic authentication strategy uses HTTP basic access authentication. To be fair, its code is one of the more complicated among the three strategies, but given its class name, we’ll introduce it first. class Merb::Authentication module Strategies module Basic class BasicAuth < Base def run! if basic_authentication? basic_authentication do |login, password| user = user_class.authenticate(login, password) unless user request_basic_auth! end user end end end

The most important method of any strategy is run!. This method does the dirty work of authentication. Here we see it first determining whether basic access authorization is possible. If so, it passes a block to basic_authentication, and upon failure, it sets up a request for authentication. def self.realm @realm ||= "Application" end cattr_writer :realm def realm @realm ||= self.class.realm end cattr_accessor :failure_message @@failure_message = "Login Required"

From the Library of Shirong Chen

240

Chapter 9: Authentication

Moving forward, the strategy allows the use of access realms, setting the default to Application. In case you’re not familiar with HTTP basic access authorization, realms

allow for authentication across certain resources to be done only once. As application developers we can make use of these realms by subclassing this strategy and activating those multiple subclasses. Above, a default failure message is also set. private def initialize(request, params) super @auth = Rack::Auth::Basic::Request.new(request.env) end def basic_authentication? @auth.provided? and @auth.basic? end

The initialization method shows that the strategy employs Rack’s ability to recognize and interpret basic authentication. Note that the method basic_authentication? ensures that basic authorization can occur and that some credentials were provided. def request_basic_auth! self.status = Merb::Controller::Unauthorized.status self.headers['WWW-Authenticate'] = 'Basic realm="%s"' % realm self.body = self.class.failure_message halt! end def basic_authentication(realm = nil, &authenticator) self.realm = realm if realm if basic_authentication? authenticator.call(*@auth.credentials) else false end end end end end end

From the Library of Shirong Chen

9.2

Auth more

241

Finally, here we arrive at the two most critical methods that were referenced in run!. The latter of these is used to wrap authentication in order to provide for its use across multiple realms. The former method issues a halt after setting the HTTP response appropriately to instigate basic authentication client-side.

9.2.1.2 Password form Most web applications rely on web forms for authentication because they tend to be prettier and less obtrusive. The authentication strategy for forms also happens to be far simpler. Here it is in its entirety: class Merb::Authentication module Strategies module Basic class Form < Base def run! if (login = request.params[login_param]) && (password = request.params[password_param]) user = user_class.authenticate(login, password) if !user errors = request.session.authentication.errors errors.clear! errors.add(login_param, strategy_error_message) end user end end def strategy_error_message "#{login_param.to_s.capitalize} or "+ "#{password_param.to_s.capitalize} were incorrect" end end end end end

Aside from pushing out the strategy error message into a helper method, everything is contained within run!. We can see how it makes use of the model class method authenticate that we saw in the auth core. Upon failure, an authentication error becomes accessible to application developers via the session object.

From the Library of Shirong Chen

242

Chapter 9: Authentication

9.2.1.3 OpenID OpenID is growing in use, and providing it as an alternative among a cascade of authentication methods is a great way to ease the pain users get from having to log in on a myriad of sites, including yours. However, because of the strong interweaving of the OpenID gem with this strategy, and the need to extensively introduce OpenID concepts alongside the source, we’ll leave its exploration to the reader.

9.2.2 Models Merb auth more also steps into the user model to define how authentication should occur. Having seen auth more contain the concrete logic for strategies, you should now realize that auth more is intended to provide actual authentication implementations, whereas the auth core is concerned only with underlying mechanisms. As we explore the source related to extending the user model for authentication, we will concern ourselves only with the DataMapper-related code. require "digest/sha1" require File.expand_path(File.dirname(_ _FILE_ _) / "..") / "strategies" / "abstract_password" class Merb::Authentication module Mixins module SaltedUser def self.included(base) base.class_eval do attr_accessor :password, :password_confirmation include InstanceMethods extend ClassMethods path = File.expand_path(File.dirname(_ _FILE_ _)) / "salted_user" if defined?(DataMapper) && DataMapper::Resource > self require path / "dm_salted_user" extend(DMClassMethods) # ... else for other ORMs end

From the Library of Shirong Chen

9.2

Auth more

243

end # base.class_eval end # self.included

Above, the SaltedUser module makes good use of the methods included and class_eval to create password accessors as well as extend and include class and instance methods respectively. This is a typical construct found within many such modules, and it helps avoid the deep nesting of numerous methods within the class_eval. module ClassMethods def encrypt(password, salt) Digest::SHA1.hexdigest( "--#{salt}--#{password}--") end end

The only class method provided is encrypt, and it needs to be this way since we may have to encrypt passwords even when not yet dealing with user objects. Interestingly enough, despite this insight, all the methods that do call this method are just instance methods. A chaining of instance to class method can be observed below. module InstanceMethods def encrypt(password) self.class.encrypt(password, salt) end def authenticated?(password) crypted_password == encrypt(password) end def password_required? crypted_password.blank? || !password.blank? end def encrypt_password return if password.blank? self.salt = Digest::SHA1.hexdigest( "--#{Time.now.to_s}--"+ "#{Strategies::Basic::Base.login_param}"+ "--") if new_record? self.crypted_password = encrypt(password) end end # InstanceMethods end # SaltedUser end # Mixins end # Merb::Authentication

From the Library of Shirong Chen

244

Chapter 9: Authentication

What we also see is a method for the initial encryption of the password. The creation of a class-level salt is required as we saw with the class method encrypt. Note that if you need more powerful or custom encryption, we recommend that you take these methods as templates for your own, placing them within the user model class itself. There are also modifications made to the user model class dependent upon the ORM. Let’s open up the file related to DataMapper models and see what it does: class Merb::Authentication module Mixins module SaltedUser module DMClassMethods def self.extended(base) base.class_eval do property :crypted_password, String property :salt, String validates_present :password, :if => proc{|m| m.password_required?} validates_is_confirmed :password, :if => proc{|m| m.password_required?} before :save, :encrypt_password end # base.class_eval end # self.extended

This time we see a variation from included and class_eval to extended and class_eval. This is because every alteration is essentially class-level but needs the DataMapper::Resource module to be included first for the methods property, validates_*, and before. More precisely, we see above the addition of two prop-

erties, validations for those properties, and a before hook that will ensure the encryption of passwords. There’s one more method, though, and it’s not in the class_eval: def authenticate(login, password) @u = first( Strategies::Basic::Base.login_param => login) @u && @u.authenticated?(password) ? @u : nil end

From the Library of Shirong Chen

9.3

Auth password slices

245

end # DMClassMethods end # SaltedUser end # Mixins end # Merb::Authentication

The method authenticate is a class method that allows us to locate a user object matching credentials. If no such user exists, we’ll get nil, which we know can be evaluated to false in Ruby.

9.2.3 Controller Merb auth more adds only one method to Merb controllers. This is the method redirect_back_or, which is used to return users to the page they intially requested before being redirected to a login: module Merb::AuthenticatedHelper def redirect_back_or(default_url, opts = {}) if !session[:return_to].blank? && ![opts[:ignore]].flatten.include?( session[:return_to].first) redirect session[:return_to].first, opts session[:return_to] = nil else redirect default_url, opts end "Redirecting to "+ "#{default_url}" end end

Above we see that the method checks for a URL within the session store, but that we can pass it a default URL as well as an optional hash to prevent the redirection to particular pages. As an application developer, you may need to use this method from inside a custom sessions controller.

9.3 Auth password slices The final stretch for the Merb auth plugin is to provide a slice that already sets up basic controllers and views to handle web form logins. Since we’ve already explored the

From the Library of Shirong Chen

246

Chapter 9: Authentication

composition of slices, it’s a great time to see one in action. Let’s open up the all-important lib file first and then move on to the application files the slice provides.

9.3.1 Lib file The lib file of any slice is where a number of essential steps occur. For the Merb auth password slice, this means requiring its dependencies along with setting up routes. With regard to the form, we discover the following: if defined?(Merb::Plugins) $:.unshift File.dirname(_ _FILE_ _) require 'merb-slices' require 'merb-auth-core' require 'merb-auth-more' # ... module MerbAuthSlicePassword self.description = "MerbAuthSlicePassword" self.author = "Daniel Neighman" def self.init unless MerbAuthSlicePassword[:no_default_strategies] ::Merb::Authentication.activate!( :default_password_form) end end # ...

Note the required gems at the top, the setting of metadata, and then the use of init to turn on the password form strategy. Moving on, we find the routes: def self.setup_router(scope) scope.match("/login", :method => :get ). to(:controller => "exceptions", :action => "unauthenticated").name(:login) scope.match("/login", :method => :put ). to(:controller => "sessions", :action => "update").name(:perform_login) scope.match("/logout").

From the Library of Shirong Chen

9.3

Auth password slices

247

to(:controller => "sessions", :action => "destroy").name(:logout) end end # ... end

We see three matches, one of them pointing to the Exceptions controller for login and the other two involving the Sessions controller. It may seem odd at first to use an Exceptions controller for anything the user sees on a regular basis, but once you realize that you can throw Unauthenticated exceptions to get the user to a login page, the decision to do so makes perfect sense. Finally, remember that scope is used to limit the reach of our routes within the main application. Thus, within our application router we’ll probably spot code like that below to get the routes matching at the root level. slice(:merb_auth_slice_password, :name_prefix => nil, :path_prefix => "")

9.3.2 Controller The password slice makes modifications to two controllers, Sessions and Exceptions. Let’s take a look at the Sessions controller first since its construction is the most direct: class MerbAuthSlicePassword::Sessions < MerbAuthSlicePassword::Application before :_abandon_session, :only => [:update, :destroy] before :ensure_authenticated, :only => [:update] after :redirect_after_login, :only => :update, :if => lambda{ !(300..399).include?(status) } after :redirect_after_logout, :only => :destroy def update "Add an after filter to do stuff after login" end def destroy "Add an after filter to do stuff after logout" end

From the Library of Shirong Chen

248

Chapter 9: Authentication

What we notice first is the use of underscored filters. The underscores are there to prevent conflict with your own. More important, though, we can conclude that there are two actions in this controller, update and destroy. In either case, a session will be abandoned, but in the case of update, ensure_authenticated will come into play by authenticating our session, as was previously seen. Additionally, the two after filters do not have underscores and are meant to be overwritten if desired. private # @overwritable def redirect_after_login message[:notice] = "Authenticated Successfully" redirect_back_or "/", :message => message, :ignore => [slice_url(:login), slice_url(:logout)] end # @overwritable def redirect_after_logout message[:notice] = "Logged Out" redirect "/", :message => message end # @private def _abandon_session session.abandon! end end

If not, they behave as above, using the method redirect_back_or to direct the user appropriately after login or logout. Finally, we see that _abandon_session simply relays to a method we saw in Chapter 8, abandon!. Moving on to the code for the Exceptions controller, we’ll warn you that it has been structured as a mixin: module MerbAuthSlicePassword::ExceptionsMixin def unauthenticated provides :xml, :js, :json, :yaml case content_type when :html render else basic_authentication.request! "" end end # unauthenticated end

From the Library of Shirong Chen

9.3

Auth password slices

249

Simply enough, though, the method authenticated looks like an action and either renders an HTML template or attempts basic authentication otherwise using the Merb core method basic_authentication.request!. Encountering the use of the authentication boot loader method customize_default, we find the reason for the mixin above: Merb::Authentication.customize_default do Exceptions.class_eval do include Merb::Slices::Support # Required to provide slice_url # # This stuff allows us to provide a default view the_view_path = File.expand_path(File.dirname( _ _FILE_ _) / ".." / "views") self._template_roots ||= [] self._template_roots << [the_view_path, :_template_location] self._template_roots << [Merb.dir_for(:view), : _template_location] include MerbAuthSlicePassword::ExceptionsMixin show_action :unauthenticated end# Exceptions.class_eval end # Customize default

As we can see, the Exceptions controller needs a bit of added work to get the slice templates working with it. It also needs unauthenticated to be manually added as an action because of its being mixed. Is this all a bit undesirable? Perhaps. But altogether this isn’t much work for an edge use case of a custom exception action in a slice.

9.3.3 Views The one view necessary for the slice to function is the login. A common point of bewilderment among first-time Merb application developers is where this view is. Thinking back to the routes we’ve seen in the password slice, it’s apparent that it should be in app/views/exceptions/unauthenticated.html.erb. Below we present the default login view, but if your application is like most and needs to customize this, it should be as easy as providing a replacement within your application code.

Login

From the Library of Shirong Chen

250

Chapter 9: Authentication

<%= error_messages_for session.authentication %> <% @login_param = Strategies::Basic::Base.login_param %> <% @password_param = Strategies::Basic::Base.password_param %>

Of course, if you make this form for yourself, there’s no reason not to use the Merb helper, which out of courtesy has not been used above. Also, you probably want to refer to login and password by indirect references. The most interesting line is the one with the method error_messages_for. Remember the errors included within Authentication? It’s nice to finally put them to use as if they were model validation errors.

From the Library of Shirong Chen

9.4

Conclusion

251

9.4 Conclusion Nearly all web applications need to authenticate their users. With merb-auth, Adam French, Daniel Neighman, and other contributors have isolated the core mechanism of authentication, providing a fully modular approach to its additional features. Our tour of the code behind merb-auth, probably the pinnacle of beautiful Merb plugins, has given us examples of both low-level plugins as well as a high-level slice. We recommend that all students of the Merb framework grok the code as a supplement to this chapter.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 10

Mailers

Many applications need to send email. Merb Mailers allow you to do this easily with the same controller and view conventions the rest of your application follows. The Mailer class is thus a subclass of AbstractController, and the relevant templates are standardly placed in app/mailers/views. In this chapter we’ll configure, generate, describe, and test mailers used in Merb applications.

10.1 Conﬁguration If you don’t configure Merb otherwise, it tries to use SMTP locally when asked to deliver mail. In most cases these exact defaults do not suffice, but alternative configurations are as simple as a few extra lines in either config/init.rb or one of the environment config files in a before_app_loads block. Below we describe the various configuration options available, separated by delivery method.

10.1.1 SMTP Though SMTP is the default for the Merb Mailer, chances are you’ll need to configure it more explicitly. This may involve specifying the host, port, user, password, authentication method, and HELO domain. Below we do this by setting various hash values for Merb::Mailer.config. Merb::Mailer.config = { :host => 'smtp.gmail.com', :port => 587, :user => '[email protected]', :password => 'password', :auth => 'plain' }

253 From the Library of Shirong Chen

254

Chapter 10: Mailers

Note that if you are using the Gmail SMTP servers or some other TLS-required SMTP service, you will need Anatol Pomozov’s gem smtp_tls in order to enhance some of the net_smtp methods.

10.1.2 Sendmail In order to use sendmail, you must specify the mailer delivery method in a configuration file. This overrides the default of :net_smtp. You may also need to alter the default sendmail path from /usr/sbin/sendmail. Here we do both: Merb::Mailer.delivery_method = :sendmail Merb::Mailer.config = {:sendmail_path => '/usr/local/sbin /sendmail'}

10.1.3 Test send A third option, perfect for both test and possibly development environments, is the test_send delivery method. This method does not actually send email but instead pushes the message into the array Merb::Mailer.deliveries: Merb::Mailer.delivery_method = :test_send

10.1.4 Custom delivery methods You can also create custom delivery methods for your applications. For instance, if the SMTP gateway you’re using severely penalizes attempts to send messages above the daily quota, you may want to construct a custom delivery method that first checks to make sure you haven’t surpassed your limit. By adding a couple of methods within Merb::Mailer, we can do just this: class Merb::Mailer def net_smtp_with_quota if increase_quota_use net_smtp end end def increase_quota_use # ... end end Merb::Mailer.delivery_method = :net_smtp_with_quota

From the Library of Shirong Chen

10.2

Using mailers directly

255

Note that in the example above, we haven’t included the actual methods for checking and increasing quota usage. This is because implementation will indubitably differ with the circumstances. One warning, though: Make sure the implementation is thread-safe. Otherwise, despite all your efforts, you may go beyond your quota anyway. Should this really be part of conﬁguration? While Merb mail controllers, as we’ll soon learn, are sophisticated enough to employ filters, some cases are better suited to exist as configuration code. There are a couple of reasons why. First, by choosing to implement quota checking or some similar functionality as part of a delivery method as opposed to in a filter, we are assured that it applies to all messages sent out by the application, including those that may not use a mail controller. Second, by locating the code in configuration files, the existence of the mail quota does not tie itself directly to our application code. Thus, should we need to work in multiple production environments, we won’t have to deal with any leftover cruft.

10.2 Using mailers directly Though it’s not advisable, you can use mailers directly to send out messages. In most cases we recommend the use of the Merb Mail Controller, which is covered in the next section. However, because you may come across a scenario where you need to send out mail from inside some other noncontroller class, let’s cover its use directly. Internally, Merb::Mailer interfaces to David Powers’s MailFactory. Passing in a hash during initialization, you construct the email just as if you were using MailFactory itself and set the attributes of a message. Below we create and send a new message by first initializing a mailer object and then calling the Mailer#deliver! method. m = Merb::Mailer.new( :to => '[email protected]', :from => '[email protected]', :subject => 'Pro Ruby Conf', :text => 'Great meeting you!' ) m.deliver!

Some email clients are capable of also rendering HTML email. The Merb Mailer allows you to send HTML emails by simply setting the :html key instead of the :text key. However, it is standard practice to also include a text-only version whenever sending out HTML messages. Such dual-formatted messages are called multipart messages.

From the Library of Shirong Chen

256

Chapter 10: Mailers

Constructing a multipart message with the Merb Mailer is as simple as setting both the :text and :html keys at initialization: m = Merb::Mailer.new( :to => '[email protected]', :from => '[email protected]', :subject => 'Pro Ruby Conf', :text => 'Great meeting you!', :html => '<strong>Great meeting you!' )

Let’s take a look at the code behind Merb::Mailer to understand how it interfaces with MailFactory: module Merb class Mailer class_inheritable_accessor :config, :delivery_method, :deliveries attr_accessor :mail self.deliveries = [] def sendmail sendmail = IO.popen( "#{config[:sendmail_path]} #{@mail.to}", 'w+') sendmail.puts @mail.to_s sendmail.close end def net_smtp Net::SMTP.start( config[:host], config[:port].to_i, config[:domain], config[:user], config[:pass], config[:auth]) { |s| s.send_message(@mail.to_s, @mail.from.first, @mail.to.to_s.split(/[,;]/)) } end def test_send deliveries << @mail end def deliver! send(delivery_method || :net_smtp) end

From the Library of Shirong Chen

10.3

Mail controllers

257

def attach(file_or_files, filename = file_or_files.is_a?(File) ? File.basename(file_or_files.path) : nil, type = nil, headers = nil) if file_or_files.is_a?(Array) file_or_files.each do |v| if v.length < 2 v << v.first.is_a?(File) ? File.basename(v.first.path) : nil end @mail.add_attachment_as *v end else raise ArgumentError, "No file." if !file_or_files.is_a?(File) @mail.add_attachment_as(file_or_files, filename, type, headers) end end

def initialize(o={}) self.config = { :sendmail_path => '/usr/sbin/sendmail' } if config.nil? o[:rawhtml] = o.delete(:html) m = MailFactory.new() o.each { |k,v| m.send "#{k}=", v } @mail = m end end end

10.3 Mail controllers Mail controllers provide an MVC way of sending out email with Merb. In other words, they are intended to separate your message logic and presentation layers using controllers and views. To accomplish this, MailController subclasses from AbstractController, inheriting, among other things, filtering and rendering capabilities. Mail controllers are standardly located in app/mailers. By convention their class names are singular words with the word Mailer appended. The actions of the controller

From the Library of Shirong Chen

258

Chapter 10: Mailers

represent various types of messages that can be sent. The convention is to name these actions according to the event that sparks them, for example, notify_on_invite. If, however, there is only one action in the controller, it is often simply named notify. Each mail controller instance initializes with a MailFactory object, @mail. We can consequently construct the message from within the action similarly to the way we did before, using the Merb Mailer directly. Note, however, that if both @mail.html and @mail.text are empty by the completion of the action, no message will be sent. class InviteMailer < Merb::MailController def notify @mail.subject = "You've Been Invited!" @mail.to = "[email protected]" @mail.from = "[email protected]" @mail.replyto = SUPPORT_EMAIL @mail.text = "Visit the #{DOMAIN} to sign up." end end

10.3.1 Invoking actions Mail controllers have been designed to be called from inside standard Merb controllers. Thus a subtle characteristic of the mail controller is its reliance on the controller that called it. This dependence allows for the accessing of the original request and session data as well as the use of URL helpers. The sending of mail from a standard controller is invoked using Controller#send_mail, a method mixed into Merb::Controller when the merbmailer dependency is included. This method takes three parameters: the mail controller class name, the method name, and a hash of message parameters used during the initialization of @mail. Below we present the invoking of an invite mailer. class InviteMailer < Merb::MailController def notify @mail.subject = "You've been invited!" @mail.from = SUPPORT_EMAIL @mail.text = "Sign up at #{DOMAIN}" end end class Invites < Application def new

From the Library of Shirong Chen

10.3

Mail controllers

259

render end def create(invite) send_mail(InviteMailer, :notify, { :to => invite[:to] }) redirect url(:new_invite) end end

We recommend that you send mail out of sync with the construction of responses since SMTP gateways can hold you up at times. The easiest way to do this is with a run_later block. Here we use run_later in a slightly more complex controller action: class Invites < Application def create(invite) @invite = Invite.new(invite) if @invite.save run_later do send_mail(InviteMailer, :notify, { :from => MAILER_EMAIL, :to => @invite.email, :subject => "You're invited!" }) end redirect url(:new_invite) end end end

10.3.2 Parameters Mail controllers by default have access to invoking a controller’s parameters. To access them with the mail controller, we simply use the params mash as we would in a standard mail controller. We can, however, override the value of params by using a fourth parameter on the action Controller#send_mail. Below we pass in a custom hash of parameters to be used from within the mail controller. class UserMailer def notify_on_signup @mail.subject = "You signed up!" @mail.text = "Welcome #{params[:user][:full_name]}!"

From the Library of Shirong Chen

260

Chapter 10: Mailers

@mail.from = SUPPORT_EMAIL end end class Users < Application def create(user) @user = User.new(user) if @user.save run_later do send_mail( UserMailer, :notify_on_signup, {:to => @user.email}, {:user => @user} ) end end redirect url(:home) end end

10.3.3 Attaching files Files can be attached to messages using the method MailController#attach. This method takes either one or two parameters. When you use it to attach a single file, the first parameter should be the file. Optionally, the second parameter may be an alternate filename used when the message is actually sent. This may be useful if you are personalizing documents. Below we attach two documents, one at a time. Both will be included in the final email. attach(File.open '/data/documents/terms.txt') attach(personalized_invoice, "#{account_id}_invoice.txt")

Instead of passing in an array to the attach method, we can attach multiple documents at once: attach([first_file, second_file])

Finally, we can also manually specify the MIME type and final filename using arrays of arrays: attach([[ first_file, "#{account_id}_invoice.html",

From the Library of Shirong Chen

10.5 Generation

261

"text/html" ]]

10.3.4 Templates Of course the principal attraction of using mail controllers is the rendering of mail message views. These are not stored in the same location as standard views but instead in /app/mailers/views. Each mail controller should have its own subdirectory within this directory just like a standard controller. This subdirectory should be a snake-cased version of the mail controller’s own name in full, such as invite_mailer/ for the InviteMailer. Mailer templates are rendered just the same as regular templates, so you should encounter no other complications.

10.4 Testing Testing mailers can seem tricky since they’re not part of the standard request-response cycle. However, using a few extra methods alongside the :test_method delivery method makes testing mailer behavior no problem at all. describe InviteMailer, "#notify" do before :each do Merb::Mailer.deliveries.clear end it "should include invite code" do InviteMailer.dispatch_and_deliver(:notify, { :invite_code => "QWERTY88" }) Merb::Mailer.deliveries.last.text.should =˜ "Your code is: QWERTY88" end end

In the code above we use the array Merb::Mailer.deliveries, the array to which test delivery pushes, to test the results of the mailer against our expectations.

10.5 Generation Finally, application developers should be aware that they can quickly generate the numerous files that mailers typically entail using merb-gen. Below we create the invite mailer.

From the Library of Shirong Chen

262 $ merb-gen Generating [ADDED] [ADDED] [ADDED]

Chapter 10: Mailers mailer invite with mailer generator: app/mailers/invite_mailer.rb app/mailers/views/invite_mailer/notify_on_event.text.erb spec/mailers/invite_mailer_spec.rb

10.6 Conclusion Merb Mailers are an excellent example of the intelligence of the Merb architecture. Subclassing off of the abstract controller base class, the Merb mail controller inherits standard controller functionality, allowing the application developer to deal with the sending of email through the same best practices used for the rest of the app.

From the Library of Shirong Chen

C HAPTER 11

Parts

Widgets are everywhere on the web. These component-like regions on web pages deliver high levels of functionality. Though many of them are Ajax-dependent, having the same functionality as standard responses really expands the possibilities of our applications. To this effect, the gem merb-parts subclasses AbstractController, providing a new type of controller whose responses can be emebedded like partials within the actual response to a request.

11.1 Parts controllers Parts controllers are used in nearly the same way as the standard Merb controller. Here’s an example of a part placed in app/parts/: class GraphPart < Merb::PartController def index @log = params[:log] @width = params[:width] || 690 @height = params[:height] || 360 if params[:date].nil? @date = Date.parse(params[:date]) else @date = Date.today end render end end

The most important thing to note is how the controller inherits from Merb::PartController. Otherwise, nearly all the methods you might use in a

263 From the Library of Shirong Chen

264

Chapter 11: Parts

controller, including render, are available. Let’s take a look at the source code behind parts controllers in general: require File.join(File.dirname(_ _FILE_ _), "mixins", "web_controller") module Merb class PartController < AbstractController cattr_accessor :_subclasses self._subclasses = Set.new def self.subclasses_list() _subclasses end def self.inherited(klass) _subclasses << klass.to_s super klass._template_root = Merb.dir_for(:part) / "views" unless self._template_root end

We find that all subclasses of the parts controller are maintained in a set. Also important is the fact that part templates are located in a special directory, app/parts/views. Each widget should have its own subdirectory for view files. Aside from their location, the views of parts are exactly like the views of the standard Merb controllers and are capable of using whatever templating engines are available. include Merb::Mixins::WebController attr_reader :params def initialize(web_controller, opts = {}) @web_controller = web_controller @params = @web_controller.params.dup @params.merge!(opts) unless opts.empty? super @content_type = @web_controller.content_type end

When initialized, Merb parts connect with the web controller that has called them, duplicating their parameters and then merging in additional parameters. We’ll see where these parameters come from later on. def url(name, *args) args << params Merb::Router.url(name, *args) end

From the Library of Shirong Chen

11.1

Parts controllers

265

alias_method :relative_url, :url def method_missing(sym, *args, &blk) @web_controller.instance_variable_set( :@_merb_partial_locals, @_merb_partial_locals) if @_merb_partial_locals @web_controller.send(sym, *args, &blk) end end end

In order to make the URL helper available from inside our parts, the method url has been set up to delegate directly to the Merb router. The interesting use of method_missing also means that other methods coming directly from the web controller are available. In practice this means that to application developers, parts definitely feel just the same as proper web controllers. Some methods, however, are better explicitly hooked. For this reason the WebController mixin, which we saw included before, exists: module Merb module Mixins module WebController def self.included(base) [:content_type, :web_controller].each do |attr| base.send(:attr_accessor, attr) end base.send(:include, InstanceMethods) end module InstanceMethods def request @web_controller.request end def cookies @web_controller.cookies end def headers @web_controller.headers end def session

From the Library of Shirong Chen

266

Chapter 11: Parts @web_controller.session end def response @web_controller.response end def route request.route end def url(name, *args) @web_controller.url(name, *args) end end

end # WebController end # Mixins end # Merb

11.2 Invoking actions The invocation of a Merb part is intended to be done from inside a standard Merb view. To accomplish this, the method Controller#part is mixed in when the dependency merb-parts is included. The use of Controller#part mimics the use of partials in that the only parameter it allows is a hash of options. Somewhere in the hash, however, a key-value pair specifying a parts controller and action must appear. By convention this is the first key set in the hash. The rest of the hash is merged into the original controller params to form the parameters for the parts controller. Below we invoke the GraphPart#index action from inside an ERB template. <%= part GraphPart => :index, :log => @log, :width => 345, :height => 180 %>

Let’s take a look at the mixin that makes this possible by adding in the method part: module Merb module PartsMixin def part(opts = {}) klasses, opts = opts.partition do |k,v| k.respond_to?(:ancestors) && k.ancestors.include?(Merb::PartController) end

From the Library of Shirong Chen

11.4 Conclusion

267

opts = opts.empty? ? {} : Hash[*(opts.first)] res = klasses.inject([]) do |memo,(klass,action)| memo << klass.new(self, opts)._dispatch(action) end res.size == 1 ? res[0] : res end end end

A curiosity of this method is the fact that it supports the passing of multiple partaction pairs, appending the results of each to the previous. Also note the initialization of each part and how the second parameter consists of the additional parameters that will be merged in.

11.3 Generation You can generate the most typical files for individual parts with merb-gen. Below we create a widget part for our application. $ merb-gen part widget [ADDED] app/parts/widget_part.rb [ADDED] app/parts/views/widget_part/index.html.erb [ADDED] app/helpers/widget_part_helper.rb

11.4 Conclusion Merb parts, as another example of the subclassing of AbstractController, capture the versatility of the framework. They allow us to compartmentalize parts of our application’s views into their own controllers and views. Thus it becomes possible to ensure that the logic and presentation layers of widgets stay separate. If you find yourself stretching the limits of regular partials or including seemingly unrelated widget code within controllers, parts are a great way to refactor your code and keep it DRY.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

C HAPTER 12

Caching

Dynamic content distinguishes the web as an interactive medium, but dynamic content can also mean huge strains on web servers. Thankfully, caching can be used to relieve this stress by eliminating redundancies among the generation of identical response content. To this end, the Merb plugin merb-cache is included in the Merb stack and has been designed to simplify the common challenges of integrating caching in an application.

12.1 Conﬁguration Though caching is included within the Merb stack, you need to configure it to put it to use.

12.1.1 Fundamental stores There are two fundamental cache stores, FileStore and MemcachedStore. You can use multiples of each of these stores in your application if necessary. • FileStore—an implementation of caching using files. It stores these files in

the directory dir, which, if not specified, defaults to Merb.root_path(:tmp / :cache). File stores have the best performance for fragment and page caching but not for object caching. • MemcachedStore—an implementation of caching using memcached, a caching

daemon used by nearly all the web’s largest sites. By virtue of its incredible versatility, memcached allows you to distribute caching across multiple servers and suits all forms of efficient caching. The two options namespace and servers accept a string for the memcached application namespace and an array for server addresses, respectively. The defaults of these two configuration options are nil and ["127.0.0.1:11211"]. 269 From the Library of Shirong Chen

270

Chapter 12: Caching

To set up a cache store within Merb, you can pass a block of cache registrations into Merb::Cache. This is best done either in config/init.rb or through one of the environment files should you need to tailor caching to the environment. Merb::Cache.setup do register(FileStore) register(:memcached, MemcachedStore) end

Above we have set up a single-file store cache as well as a secondary memcached cache named memcached. Once registered, all data stores are accessible via Merb::Cache. Treated like an array, Merb::Cache by default retrieves the default store and otherwise pulls up the store we specify by name: Merb::Cache # gets the file store we registered Merb::Cache[:memcached] # gets the memcache store

12.1.2 Strategy stores Strategy stores are layered stores on top of the two fundemental stores. You can wrap them on top of both file and memcached stores or even on top of themselves. • ActionStore—stores responses for cached controller actions that may have re-

sponses conditioned upon request parameters • AdhocStore—wraps a list of multiple stores together using the first one that will

work • GzipStore—gzips cached data and is thus suitable for large files • PageStore—sends out cached responses for simple actions, avoiding full controller

dispatch • SHA1Store—hashes parameters to form a key for each cache and is best used when

numerous parameters are involved Below we wrap the stores we previously created with two of the strategy stores from above. Merb::Cache.setup do register(:actions, ActionStore[:default]) register(:zipped, GzipStore[:memcached]) end

From the Library of Shirong Chen

12.2

Caching basics

271

12.2 Caching basics Merb application development does not typically involve getting your hands dirty with low-level caching methods. However, understanding how to get down to caching basics adds both breadth to your understanding of the plugin as well as a few essentials to your development arsenal. Therefore, let’s take a look at the basic methods used to interact with cache stores.

12.2.1 Writing There are two methods related to writing data to a cache. These are writable? and write. The first checks to see if a particular cache key is writable or not. Between the two fundamental data stores, write makes a call to writable? in order to get the go-ahead to cache data. Therefore, as an application developer you need to be aware of only the method write. Here we use it to store a value into the cache store: Merb::Cache[:default].write("key1", "data1") Merb::Cache[:memcached].write("key2", "data2", {:id => 1}, :expire_in => 3600 )

The first line is the easier of the two, simply setting data to be associated with a value. The second, however, has two extra method parameters, the first being a hash of additionally identifying parameters and the second being a condition that applies only to memcache stores. In order to contrast the two methods and know how they work, let’s take a look at the two implementations of write, first for FileStore and second for MemcachedStore: # for FileStore def write(key, data = nil, parameters = {}, conditions = {}) if writable?(key, parameters, conditions) if File.file?(path = pathify(key, parameters)) write_file(path, data) else create_path(path) && write_file(path, data) end end end # for MemcachedStore def write(key, data = nil, parameters = {}, conditions = {})

From the Library of Shirong Chen

272

Chapter 12: Caching

if writable?(key, parameters, conditions) begin @memcached.set(normalize(key, parameters), data, expire_time(conditions)) true rescue nil end end end

As previously mentioned, both make use of the writable? method, but the file store is more complicated. It creates a path for the file and then writes to it.

12.2.2 Reading Reading, like writing, is handled by two methods, exists? and read. You may end up finding some use for exists? as an application developer, but for the most part read is sufficient since the first thing it does is seek the approval of exists?. Merb::Cache[:default].read("key1") # => "data1" Merb::Cache[:memcached].read("key2", {:id => 1}) # => "data2"

Above we have pulled the data that we previously persisted in the two data stores. # for FileStore def read(key, parameters = {}) if exists?(key, parameters) read_file(pathify(key, parameters)) end end # for MemcachedStore def read(key, parameters = {}) begin @memcached.get(normalize(key, parameters)) rescue Memcached::NotFound, Memcached::Stored nil end end

Note that the read method of FileStore uses exists?, as opposed to DataStore#read, which rescues not-found errors, ignoring them and returning nil.

From the Library of Shirong Chen

12.2

Caching basics

273

12.2.3 Fetching The fetching of records is essentially shorthand for the retrieval or otherwise writing of a cached value. Below we use a block to return the potential value of a cache element that may not exist. Merb::Cache.fetch("key0") do render end

The fetch methods for both of the fundamental stores is the same: def fetch(key, parameters = {}, conditions = {}, &blk) read(key, parameters) || ( writable?(key, parameters, conditions) && write(key, value = blk.call, parameters, conditions) && value ) end

In its highly condensed statement, fetch reads from or otherwise attempts to write to a cached element.

12.2.4 Deleting You can delete cached data using the method delete and passing in the cached element key along with any identifying parameters needed. Observe that the code behind the delete method differs between the two fundamentals, but no more than we’ve seen before: # for FileStore def delete(key, parameters = {}) if File.file?(path = pathify(key, parameters)) FileUtils.rm(path) end end # for MemcachedStore def delete(key, parameters = {}) begin @memcached.delete(normalize(key, parameters)) rescue Memcached::NotFound nil end end

From the Library of Shirong Chen

274

Chapter 12: Caching

12.3 Caching helpers Various helpers exist to ease the use of caching away from the primitive methods we have so far seen. We’ll take a glimpse at all of these in this section.

12.3.1 Action caching In order to better facilitate the page and action stores, a number of methods are mixed into controllers at both an instance and a class level. The simpliest of these is cache!, which caches all actions. Alternatively, the method cache accepts a list of actions to cache. More precisely, we can specify that a particular action should be cached only under certain conditions with cache_action: class Papers < Application cache! # ... end class Users < Application cache :new, :index cache_action :show, :if => important_user? # ... end

All of these work by adding in before filters: def cache!(conditions = {}) before(:_cache_before, conditions.only(:if, :unless). merge(:with => conditions)) after(:_cache_after, conditions.only(:if, :unless). merge(:with => conditions)) end def cache(*actions) if actions.last.is_a? Hash cache_action(*actions) else actions.each {|a| cache_action(*a)} end end def cache_action(action, conditions = {}) before("_cache_#{action}_before",

From the Library of Shirong Chen

12.3

Caching helpers

275

conditions.only(:if, :unless).merge( :with => [conditions], :only => action)) after("_cache_#{action}_after", conditions.only(:if, :unless).merge( :with => [conditions], :only => action)) alias_method "_cache_#{action}_before", :_cache_before alias_method "_cache_#{action}_after", :_cache_after end

Do note that the position of the cache class methods can have an effect on the ultimate request, since they may be part of a complex filter chain. Authentication filters, for instance, should certainly appear above cache method lines.

12.3.2 Eager caching A variant of action caching that is better suited for pages where the most current information is mildly less important than the speed of the response is eager caching. Making use of after filters instead of before filters, eager caching updates stale versions of the cache based upon the evoking of a triggering action. It does so in a run_later block after the triggering action is evoked, making eager caching perfect for actions with expensively constructed responses. However, that’s the only problem eager caching solves, since it also effectively marks as stale all old caches. This versatility can be seen in the example below, where we employ the method eager_cache. class Users < Application eager_cache :create, :index eager_cache :update, :show do |params| build_request(build_url(:user, :id => params[:id]), :id => params[:id]) end end

The two methods build_url and build_request are helper methods used by the eager_cache method to construct URLs and internally dispatch requests, respectively. In the first case above we don’t pass in a block and let eager_cache do its own magic. The second is more explicit. Here’s the code that sets up the after filters: def eager_cache(trigger_action, target = trigger_action, conditions = {}, &blk) target, conditions = trigger_action, target if target.is_a? Hash

From the Library of Shirong Chen

276

Chapter 12: Caching

if target.is_a? Array target_controller, target_action = *target else target_controller, target_action = self, target end after("_eager_cache_#{trigger_action}_to_"+ "#{target_controller.name.snake_case}"+ "_ _#{target_action}_after", conditions.only(:if, :unless).merge( :with => [target_controller, target_action, conditions, blk], :only => trigger_action) ) alias_method "_eager_cache_#{trigger_action}_to_"+ "#{target_controller.name.snake_case}_ _"+ "#{target_action}_after", :_eager_cache_after end

But far more interestingly, here’s the code that dispatches the eager requests to be cached. Pay special attention to the variety of forms in which requests can be created. def eager_dispatch(action, params = {}, env = {}, blk = nil) kontroller = if blk.nil? new(Merb::Request.new(env)) else result = case blk.arity when 0 then blk[] when 1 then blk[params] else blk[*[params, env]] end case when when when when else end end

result NilClass then new(Merb::Request.new(env)) Hash, Mash then new(Merb::Request.new(result)) Merb::Request then new(result) Merb::Controller then result raise ArgumentError, "..."

kontroller.force_cache! kontroller._dispatch(action)

From the Library of Shirong Chen

12.3

Caching helpers

277

kontroller end

12.3.3 Fragment caching Fragment caching through the method fetch_fragment allows application developers to store small sections of a view template. This is perfect if only a region of a template needs caching.

Friend

<% fetch_fragment do %> <% @friends.each do |f| %> <%= user_info_block(f) %> <% end %> <% end %>

Looking into the source, we see how it magically identifies fragments by file and line number: def fetch_fragment(opts = {}, conditions = {}, &proc) if opts[:cache_key].blank? file, line = proc.to_s. scan(%r{ˆ#$}).first fragment_key = "#{file}[#{line}]" else fragment_key = opts.delete(:cache_key) end concat(Merb::Cache[_lookup_store(conditions)].fetch( fragment_key, opts, conditions) { capture(&proc) }, proc.binding) end

12.3.4 Partial caching The method fetch_partial can act as a replacement for partial when the partial needs to be cached. As we saw with fetch, the cached element is generally either read or otherwise written. However, unlike fetch, the fact that we’re referring to a template means there is no need for passing in a block. fetch_partial 'users/stats', :user => @user

From the Library of Shirong Chen

278

Chapter 12: Caching

Here’s the source behind fetch_partial; note how it takes a possible third parameter of conditions that will be passed along to the actual fetch method. def fetch_partial(template, opts={}, conditions = {}) template_id = template.to_s if template_id =˜ %r{ˆ/} template_path = File.dirname(template_id) / "_#{File.basename(template_id)}" else kontroller = (m = template_id.match(/.*(?=\/)/)) ? m[0] : controller_name template_id = "_#{File.basename(template_id)}" end unused, template_key = _template_for(template_id, opts.delete(:format) || content_type, kontroller, template_path) fetch_proc = lambda { partial(template, opts) } concat(Merb::Cache[_lookup_store(conditions)]. fetch(template_key, opts, conditions, &fetch_proc), fetch_proc.binding) end

12.4 Conclusion Caching in Merb can be handled in a number of ways. The best ways, however, are those that interfere the least with application code. The code behind action and eager caching exhibits the Merb controller’s ease in layering these mechanisms. Our look at the various caching stores available within Merb should make it clear that no one storage mechanism fits all, and that caching must make sense for the particular data being cached. Nonetheless, the caching store strategies provide a number of extensions on the abstract stores and when needed can be used to create composite user-defined stores as well.

From the Library of Shirong Chen

C HAPTER 13

Testing

Testing is critical to the robustness and longevity of your application, but unless you make it part of your application development process, you’re bound to find it painful. Somewhat surprisingly, however, teams and individuals who do integrate testing as part of standard development practices find that they almost can’t live without it. Why? There are two reasons. First, testing itself demands testable code, which in turn implies betterstructured code because of the need for cleanly interfacing units. Second, a well-built test suite is essentially machine-interpretable documentation that not only prevents regressions but also gives developers insight into the intent of the code, no matter its condition. Merb, as a framework and application development platform, has always encouraged testing. However, the specifics of testing continue to be intensely debated. For this reason, Merb has attempted to remain agnostic toward the tools used in building test suites. Nonetheless, a decision had to be made, and RSpec was picked both internally and at a stack level as the testing framework of choice. In this chapter we will cover the use of RSpec for testing models and requests, but following the precedent set by all the other chapters we’re more intent on revealing how testing has been integrated within the Merb framework than describing its precise use. That said, let’s start off with an exploration of tasks most commonly used with Merb when testing.

13.1 Rake tasks All rake tasks related to testing within Merb are contained within the task namespace :spec. Here’s the beginning of spectasks.rb contained within the Merb core: desc "Run specs, run a specific spec with "+ "TASK=spec/path_to_spec.rb" task :spec => [ "spec:default" ]

279 From the Library of Shirong Chen

280

Chapter 13: Testing

namespace :spec do OPTS_FILENAME = "./spec/spec.opts" if File.exist?(OPTS_FILENAME) SPEC_OPTS = ["--options", OPTS_FILENAME] else SPEC_OPTS = ["--color", "--format", "specdoc"] end Spec::Rake::SpecTask.new('default') do |t| t.spec_opts = SPEC_OPTS if(ENV['TASK']) t.spec_files = [ENV['TASK']] else t.spec_files = Dir['spec/**/*_spec.rb'].sort end end

Observe that the default spec task is effectively created by passing in the string 'default' to Spec::Rake::SpecTask.new. The SpecTask class has been designed

to simplify RSpec rake task creation. The default Merb spec, furthermore, sets two configuration variables through the block passed in to the initializer. These are the spec options and the spec files. Application developers should be aware that appending TASK='spec/some_spec.rb' to the rake spec command runs only one particular spec file. Otherwise, all files ending in _spec.rb and contained within any level subdirectory of spec/ are used. desc "Run all model specs, run a spec for a specific "+ "Model with MODEL=MyModel" Spec::Rake::SpecTask.new('model') do |t| t.spec_opts = SPEC_OPTS if(ENV['MODEL']) t.spec_files = Dir["spec/models/**/"#{ENV['MODEL']}_spec.rb"].sort else t.spec_files = Dir['spec/models/**/*_spec.rb'].sort end end desc "Run all request specs, run a spec for a specific "+ "Request with REQUEST=MyRequest" Spec::Rake::SpecTask.new('request') do |t| t.spec_opts = SPEC_OPTS if(ENV['REQUEST']) t.spec_files = Dir[

From the Library of Shirong Chen

13.1

Rake tasks

281

"spec/requests/**/#{ENV['REQUEST']}_spec.rb"].sort else t.spec_files = Dir['spec/requests/**/*_spec.rb'].sort end end # ...

The two non-default tasks, model and request, are meant to handle model and request specs. Their rake task construct is not very different from the default task, but developers should remember that MODEL and REQUEST are the environment variables for specifying the running of only particular spec files. Merb also creates a couple more tasks for view and controller testing, but most Merb developers frown upon the use of view and controller testing. The reasons are different in each case. View testing tends to be the testing of bluntly self-descriptive templates, whereas controller testing is a form of unit testing that, removed from the simulation of the request-response cycle, does not test context-genuine behavior. If you find yourself asking why the testing of context-genuine behavior is so important, you’ll definitely raise a substantially contentious question. Leaving opinion aside, the findings of many have been that the development of a test suite that does test context-genuine behavior alone quickly becomes a crufty mess whenever application code refactoring is attempted. Said differently, the isolation of particular application code through tests via excessive stubbing and mocking tends to reveal tests that possess uncanny knowledge of implementation and not simply interface. Our advice is consequently that you stick to the bread and butter of model and request specs, and if you truly think you need a controller spec, then you should probably refactor some code out of your indubitably overburdened controller. desc "Run all specs and output the result in html" Spec::Rake::SpecTask.new('html') do |t| t.spec_opts = ["--format", "html"] t.libs = ['lib', 'server/lib' ] t.spec_files = Dir['spec/**/*_spec.rb'].sort end desc "Run specs and check coverage with rcov" Spec::Rake::SpecTask.new('coverage') do |t| t.spec_opts = SPEC_OPTS t.spec_files = Dir['spec/**/*_spec.rb'].sort t.libs = ['lib', 'server/lib' ] t.rcov = true t.rcov_opts = ["--exclude 'config,spec,#{Gem::path.join(',')}'"] end end

From the Library of Shirong Chen

282

Chapter 13: Testing

Two other spec tasks exists. These are html and coverage. The former simply outputs spec results in HTML, and the other uses rcov to determine the coverage of the test suite. Rake task in hand, let’s move on to producing some actual spec files within a Merb application.

13.2 Spec ﬁles For the rest of this chapter we’re going to be working with a fake application called 0g. Honestly, though, the only critical bit of information about the application is that there is a Ship model and a Ships controller. To create the files for both of these classes, we used merb-gen resource ship. The only interesting bit is that it also gave us two additional files: spec/models/ship_spec.rb spec/requests/ships_spec.rb

Before we jump in and manipulate these spec files, let’s first look at the code for a file that both require, spec/spec_helper.rb: require "rubygems" # so local gems get priority if (local_gem_dir = File.join(File.dirname(_ _FILE_ _), '..', 'gems')) && $BUNDLE.nil? $BUNDLE = true Gem.clear_paths ; Gem.path.unshift(local_gem_dir) end require "merb-core" require "spec" # for those not using the rake tasks Merb.start_environment( :testing => true, :adapter => 'runner', :environment => ENV['MERB_ENV'] || 'test') Spec::Runner.configure do |config| config.include(Merb::Test::ViewHelper) config.include(Merb::Test::RouteHelper) config.include(Merb::Test::ControllerHelper)

From the Library of Shirong Chen

13.3

Model specs

283

config.before(:all) do DataMapper.auto_migrate! if Merb.orm == :datamapper end end

The most important method here is Merb.start_environment, which starts up Merb if it has not yet been started. Note, however, that it has been requested that Merb be started in testing mode. This prevents any Merb workers from being created, and though the application will be up and running, it won’t be accessible from any local port. Also note the inclusion of the test helper modules within the Spec::Runner.configure blocks; this makes them available for all the tests.

13.3 Model specs The spec file for our ship model is located at spec/models/ship_spec.rb. Without any modification it appears as shown below. require File.join( File.dirname(_ _FILE_ _), '..', "spec_helper" ) describe Ship do it "should have specs" end

Because the first spec description has egged us on, we should probably flesh out the file: before :each do Ship.auto_migrate! @s = Ship.new(:name => 'Starlight', :base_mass => 100, :fuel => 1000) end it "should have a various properties" do @s.should respond_to :name @s.should respond_to :base_mass @s.should respond_to :cargo_mass @s.should respond_to :fuel @s.should respond_to :x @s.should respond_to :y end

From the Library of Shirong Chen

284

Chapter 13: Testing

Through the specifications above we have set expectations about how a ship should behave. The methods before, it, and should are all out of the scope of this chapter, but if you need more familiarity with them please check the RSpec documentation. Let’s run our model specs and the result: $ rake spec:model (in /home/foysavas/src/0g) Loading init file from ˜/src/0g/config/init.rb Loading ˜/src/0g/config/environments/development.rb F 1) ArgumentError in 'Ship should have a various properties' The property 'base_mass' is not a public property. ./spec/models/ship_spec.rb:7:in ‘new' ./spec/models/ship_spec.rb:7: ...

Obviously, the code has not written itself, and so we have ended up with a failure. Let’s modify our model as follows: class Ship include DataMapper::Resource property property property property property property property

:id, Serial :name, String, :nullable => false :base_mass, Integer, :default => 0 :cargo_mass, Integer, :default => 0 :fuel, Integer, :default => 0 :x, Integer, :default => 0 :y, Integer, :default => 0

end

Now, running the model specs again, our specifications pass: $ rake spec:model (in /home/foysavas/src/0g) Loading init file from ˜/src/0g/config/init.rb Loading ˜/0g/config/environments/development.rb . Finished in 0.041148 seconds 1 example, 0 failures

From the Library of Shirong Chen

13.4

Request specs

285

Realistically, this has been only a taste of what model testing is like, but given that domain-level testing is more dependent upon knowing the chosen testing framework than any extensions that may be built on top of it (Merb in fact comes with no explicit model test helpers), we’ll just leave it at that.

13.4 Request specs Request specifications are the preferred way to test a Merb application’s full stack behavior. The concept, simple enough, is to fake a request in, and then set expectations on the response. Let’s open up the file controller spec file for ships. Since Ships was generated as a resource controller, a number of specifications establishing the basis of a RESTful interface are automatically provided: require File.join(File.dirname(_ _FILE_ _), '..', 'spec_helper.rb') given "a ship exists" do Ship.all.destroy! request(resource(:ships), :method => "POST", :params => { :ship => { :id => nil }}) end describe "resource(:ships)" do describe "GET" do before(:each) do @response = request(resource(:ships)) end it "responds successfully" do @response.should be_successful end

If you’re new to specs with Merb, the given will throw you off. This method, an extension to RSpec, takes a block that can be run before spec groups. We’ll see this usage later on, but for now, just recognize that it’s a great way to keep our tests DRY. Also notice the use of the method request, which creates a request and sends it to the Merb test server. Its first parameter is a URL, here given using the resource URL helper. The second and optional parameter is a hash of request parameters. Above, the request method and request params have been specified for the creation of a ship. Notice how the describes blocks are nested one inside the other. The first is for resource(:ships) and the second more specifically for how it behaves with GET applied.

From the Library of Shirong Chen

286

Chapter 13: Testing

There’s nothing magical about these names, and as we can see in the before(:each) block, a generic request to '/ships' is made. The return value of the request is saved as an instance variable so that we can set expectations on it within the individual it blocks. The first of these tests the most basic but essential expectation of the request: It should be successful; that is, it should come back to us with a successful status code without having raised any errors. it "contains a list of ships" do pending @response.should have_xpath("//ul") end end describe "GET", :given => "a ship exists" do before(:each) do @response = request(resource(:ships)) end it "has a list of ships" do pending @response.should have_xpath("//ul/li") end end

The next it block does something more specific: It tests that the response contains a list of ships. To do this, it makes use of the have_xpath helper, which tests for the presence of an element given an XPath. Now because the application may not respond with a list (maybe you need a table instead, or just a bunch of divs) and because a more thorough testing of the response is desirable, the pending method has been used to alert us to its incompleteness. The second describe block comes with a given that will run the previously described given block before each contained example. Otherwise the difference between this describe and the other are minuscule—a list element is also expected now that we know one ship is around. Having tested essentially the index action, let’s move on to more curious HTTP methods. describe "a successful POST" do before(:each) do Ship.all.destroy! @response = request(resource(:ships), :method => "POST", :params => { :ship => { :id => nil }}) end

From the Library of Shirong Chen

13.4

Request specs

287

it "redirects to resource(:ships)" do @response.should redirect_to(resource(Ship.first), :message => {:notice => "ship was successfully created"}) end end end describe "resource(@ship)" do describe "a successful DELETE", :given => "a ship exists" do before(:each) do @response = request(resource(Ship.first), :method => "DELETE") end it "should redirect to the index action" do @response.should redirect_to(resource(:ships)) end end end

As we see, POST and DELETE are used to send out requests to different URLs. The first goes to '/ships' and the second presumably goes to '/ships/1'. Both examples, however, set the expectation that we are redirected to some other URL using the method redirect_to. The great thing about RSpec and Ruby testing frameworks in general is that they read so naturally that they just make sense. describe "resource(:ships, :new)" do before(:each) do @response = request(resource(:ships, :new)) end it "responds successfully" do @response.should be_successful end end describe "resource(@ship, :edit)", :given => "a ship exists" do before(:each) do @response = request(resource(Ship.first, :edit))

From the Library of Shirong Chen

288

Chapter 13: Testing

end it "responds successfully" do @response.should be_successful end end

The two example groups, for /ships/new and /ships/1/edit, are barely filled in. When you get down to specifying your own application, you may want to make sure particular form elements exist on each of these pages. describe "resource(@ship)", :given => "a ship exists" do describe "GET" do before(:each) do @response = request(resource(Ship.first)) end it "responds successfully" do @response.should be_successful end end describe "PUT" do before(:each) do @ship = Ship.first @response = request(resource(@ship), :method => "PUT", :params => { :ship => {:id => @ship.id} }) end it "redirect to the ship show action" do @response.should redirect_to(resource(@ship)) end end end

Closing up the resource-generated request spec file, we see the testing of /ships/1. The first describe block tests the success of the retrieval of the page, and the second makes sure that updating the ship object redirects us to its page. For the rest of this chapter we will describe in detail the Merb test helper methods, some of which were shown above.

From the Library of Shirong Chen

13.5

Request helper

289

13.5 Request helper The request method which we saw before takes two parameters, the first a URL and the second an optional hash of all the environment variables related to the request. Let’s open up the source to see how it works: def request(uri, uri = url(uri) uri = URI(uri) uri.scheme ||= uri.host ||=

env = {}) if uri.is_a?(Symbol) "http" "example.org"

if (env[:method] == "POST" || env["REQUEST_METHOD"] == "POST") params = env.delete(:body_params) if env.key?(:body_params) params = env.delete(:params) if env.key?(:params) && !env.key?(:input) unless env.key?(:input) env[:input] = Merb::Parse.params_to_query_string(params) env["CONTENT_TYPE"] = "application/x-www-form-urlencoded" end end if env[:params] uri.query = [ uri.query, Merb::Parse.params_to_query_string( env.delete(:params)) ].compact.join("&") end

Above we see the request method taking the uri given and translating it to the full and proper uri to test with. Note that we can pass in a symbol and it is automatically wrapped in the method url. We advise against this, however, for the sake of explicitness within specs. If the URL method is POST, then the method pushes all the params as a query string into env[:input]. We can do this ourselves, test-side, using the hash option :input, but there are few cases when it’s desirable to do so. Finally, if the request method is not POST, all params are inserted as query params.

From the Library of Shirong Chen

290

Chapter 13: Testing

ignore_cookies = env.has_key?(:jar) && env[:jar].nil? unless ignore_cookies @_ _cookie_jar_ _ ||= Merb::Test::CookieJar.new jar = env.delete(:jar) || :default @_ _cookie_jar_ _.update(jar, uri, env.delete(:cookie)) if env.has_key?(:cookie) env["HTTP_COOKIE"] = @_ _cookie_jar_ _.for(jar, uri) end

The request method also makes sending and receiving cookies a possibility. To do so we can pass in a cookie jar with the option :jar. This jar must be constructed using the class Merb::Test::CookieJar. Because statefulness through cookies is so important on the web, if we do not pass in a cookie jar a default one is passed in for us. app = Merb::Config[:app] rack = app.call(::Rack::MockRequest.env_for(uri.to_s, env)) rack = Struct.new(:status, :headers, :body, :url, :original_env). new(rack[0], rack[1], rack[2], uri.to_s, env) @_ _cookie_jar_ _.update(jar, uri, rack.headers["Set-Cookie"]) unless ignore_cookies Merb::Dispatcher.work_queue.size.times do Merb::Dispatcher.work_queue.pop.call end rack end end

And here’s the real magic. Using Rack::MockRequest, the request is sent off and handled by our application. Note how the rack response is restructured for our ease in testing. The methods status, helpers, body, url, and original_env all get us to the bits and pieces of the response we want to test. Finally, the dispatcher work queue is emptied, so we can have a clean room for testing our next request no matter what happened.

13.6 Request matchers Among the spec matchers Merb provides, several simply test the application’s responsiveness to the request. We’ve already seen a few of them, so now let’s peek inside to see what they’re made of: Spec::Matchers.create( :be_successful, :respond_successfully) do

From the Library of Shirong Chen

13.6

Request matchers

291

matches do |rack| @status = rack.respond_to?(:status) ? rack.status : rack @inspect = describe_input(rack) (200..207).include?(@status) end message do |not_string, rack| if @inspect.is_a?(Numeric) "Expected status code#{not_string} to be successful" else "Expected #{@inspect}#{not_string} " \ "to be successful, but it returned a #{@status}" end end end

Created via the class method Spec::Matchers.create (a method Merb provides as an extension to RSpec), be_successful and respond_successfully are two matchers that test if the status code returned was somewhere in the range of 200 to 207. Note the use of the message to return failure messages. Spec::Matchers.create(:be_missing, :be_client_error) do matches do |rack| @status = rack.respond_to?(:status) ? rack.status : rack @inspect = describe_input(rack) (400..417).include?(@status) end message do |not_string, rack| unless @inspect.is_a?(Numeric) "Expected #{@inspect}#{not_string} " \ "to be missing, but it returned a #{@status}" else "Expected #{not_string ? "not to get " : ""}"\ "a missing error code, " \ "but got #{@inspect}" end end end

The matchers be_missing and be_client_error are just the same, but for status codes 400 through 417.

From the Library of Shirong Chen

292

Chapter 13: Testing

Spec::Matchers.create(:have_body) do matches do |rack, body| @actual = if rack.respond_to?(:body) rack.body.to_s else rack.to_s end @actual == body end negative_failure_message do |rack, body| "Expected the response not to match:\n"\ #{body}\nActual response was:\n #{@actual}" end failure_message do |rack, body| "Expected the response to match:\n"\ #{body}\nActual response was:\n #{@actual}" end end

The match have_body is expected to be used with both should and should_not. As a consequence, its failure messages are bifurcated into failure message and negative failure message. Additionally, note the second block parameter with matches. This is the parameter on the have_body matcher method. If they do not match (or, in the negative case, do match), then the test will fail. The code for the rest of the matchers is very similar to what we’ve already seen, so we’ll leave you to venture into it if you so desire. The remaining request matchers are of use to application developers, however, so let’s describe them more briefly. The match have_content_type takes in a MIME symbol (for example, :html) that the request should match. Finally, the matchers redirect and redirect_to test whether a response has resulted in redirect and, in the case of redirect_to, if it was redirected to a specific location.

13.7 RSpec extensions There are a few helper extensions Merb makes to RSpec directly. Let’s take a look at one we’ve already encountered. Remember the given method from the request specs? Here it is: require 'spec' module Kernel

From the Library of Shirong Chen

13.7

RSpec extensions

293

def given(*args, &example_group_block) args << {} unless Hash === args.last params = args.last params[:shared] = true describe(*args) do prepend_before(:each) do self.instance_eval(&example_group_block) end end end end

One should always be wary of Kernel methods, but for the sake of testing this method is added when our application runs in test mode. Interestingly enough, the given block must push itself into a describe block and then instance evaluate the code that should be run as early as possible before each example. Noting how the example group has been set to be shared, it’s hard to keep from showing you how they actually hook into later describe blocks. Let’s take a look at the relevant section of Merb’s extension of ExampleGroup: class ExampleGroup < Spec::Example::ExampleGroup class << self def describe(*args, &example_group_block) ret = super params = args.last.is_a?(Hash) ? args.last : {} if example_group_block params[:when] = params[:when] || params[:given] ret.module_eval( %{it_should_behave_like "#{params[:when]}"}) if params[:when] end end alias context describe end end

There you have it: a module_eval (certainly a rarity) that uses the RSpec method it_should_behave_like. In other words, given is virtually an alias for it_should_behave_like that tightens up its usage.

From the Library of Shirong Chen

294

Chapter 13: Testing

It’s a shame that we have to end this section on a sour note, but Merb makes two further extension to RSpec: module Spec module Matchers def fail raise_error( Spec::Expectations::ExpectationNotMetError) end def fail_with(message) raise_error( Spec::Expectations::ExpectationNotMetError, message) end end end

Out of convenience you cannot make your examples fail outright by using the helpers fail and fails_with. Use the second if you need a message to tag along.

13.8 Miscellaneous extensions A few other methods are added onto primitives so that your tests can read nicely. For strings the methods contain? and match? have been added. These are also added to Hpricot, so you can use them with either. Below is the code that adds these methods and their aliases to String. class String def contain?(value) self.include?(value) end alias_method :contains?, :contain? def match?(regex) self.match(regex) end alias_method :matches?, :match? end

Note that contain? really just delegates to include?, and match? to match. The first takes a string, the second a regular expression.

From the Library of Shirong Chen

13.9

Conclusion

295

13.9 Conclusion Merb’s use of RSpec both internally and within applications themselves exhibits the framework’s belief in specifying behavior during development. The availability of other frameworks for use during application development, however, reveals a willingness to suppress opinions for the sake of developer comfort. Nonetheless, as we saw, Merb has adopted the preference of request specification over that of unit testing controllers and views. Though this may seem like a small difference at first, it is truly a fundamental one that insists upon the specification of only genuine behavior.

From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

Afterword If DHH ain’t doing it, you don’t do it. (Seems every time some clever fellow gets into trouble it’s because of that.) —Zed Shaw

This tactfully derisive quote got the last word in Obie Fernandez’s The Rails Way, and for the many who had reached the opinionated limits of the Rails framework it seemed all too true. Aiming to rectify the dilemma with a framework that realistically was built to be as similar as possible, the Merb team pushed the limits of modularity and stack agnosticism. In doing so, they succeeded in proving that the implementation behind Rails could conceptually be cleaned up, and that such a pursuit was ultimately worthwhile because it provided the foundation of a richer, more versatile web framework. Now that the frameworks are merging, we are left to wonder if any truth in Zed’s quote will persist. My advice is that the jury remain out, not simply because a more modular Rails may fall prey once again to too-limiting opinions, but because software inherently demands strongly coherent vision, and such vision naturally conflicts with the changing demands and use cases of the future. Thus, and in general, in order to achieve fluidity and the long-term success of our projects, we must want to experiment and always stay curious with regard to implementation. This especially applies within the realm of open-source software, where hacking forms the cornerstone of all advancement. With that in mind, it’s hard to deny that a deep understanding of the Merb framework has been my principal concern throughout this book. Too many technical books shallowly target only interfaces, but true appreciation demands at least some knowledge of internals. I hope, therefore, that wherever coding may lead you, you don’t forget that all software is within your grasp if only you possess the interest and time. All this said, may the future of Ruby be bright, but our minds ever brighter.

297 From the Library of Shirong Chen

This page intentionally left blank

From the Library of Shirong Chen

Index

= (equal sign) outputting results, 107–108 outputting strings, 108 sanitizing, 108 # (pound sign) comment indicator, 103 in ID names, 106 / (slash) in file paths, 21 path expansion, 22 . (dot), in class names, 106 & (ampersand), anchors in YAML nodes, 115 == (equal signs), sanitizing, 108 - (hyphen), code indicator, 107 % (percent sign), tag indicator, 105 { } (curly braces), in Haml tags, 107 ( ) (parentheses), in optional route matching, 52 <% %> ERB delimiters, 102 <% =%> ERB delimiters, 102 <%= %> ERB delimiters, 102 <%= -%> ERB delimiters, 102 ∼ (tilde), preserving whitespace, 108

abstract? method, 229 AbstractController class, methods before, 69 absolute_url, 71 action_name, 70 action_name=, 70 add_filter, 69 after, 69 body, 71 body=, 71 capture, 71 capture_erb, 71 catch_content, 71 clear_content, 71 concat, 71 concat_erb, 71 content_type, 71 content_type=, 71 controller_name, 69–70 default_layout, 70

absolute_url method, 71

filter, 69 general, 69, 70 inherited, 69 instance, 70 layout, 70

Abstract controllers, 69–70 abstract! method, 229, 238–239

normalize_filters!, 69 partial, 71

A

299 From the Library of Shirong Chen

300 AbstractController class,

methods (continued ) relative_url, 71 render, 70 render, 71 render_all, 71 render_html, 71 render_js, 71 render_json, 71 render_options, 70 render_text, 71 render_xml, 71 render_yaml, 71 skip_after, 69 skip_before, 69 skip_filter, 69 subclasses_list, 69 template_roots, 70, 71 template_roots=, 70, 71 throw_content, 71 throw_content?, 71 URL, 71 url, 71 view, 71 Access privileges, properties, 131 Access realms, 240 :accessor option, 131 Action caching, 274–275 action key, 42 action_name method, 70 action_name= method, 70 Actions callable, returning, 72 callable, setting, 79 calling, 66 hiding/showing, 72, 79 mailers invoking, 258–259 naming, 257–258 methods available as, 68

Index names, 70 parts, 266–267 readability, improving, 78 ActionStore strategy store, 270 ActiveRecord, definition, 26 ActiveRecord associations, versus DataMapper, 132–133 Adapter options, Rack, 23–25 Adapters, DataMapper, 114 add_filter method, 69 Adding controller names to subclasses_list, 69 CSS error class, 186 filters to filter chains, 69 names to routes, 57–58 query parameters, 143 routes, 44–45 session functionality, 29 add_rakefiles plugin, 222 Addressable URIs, storing as strings, 155 add_reversed query parameter, 145 add_slice method, 202–203 AdhocStore strategy store, 270 after class method, 81–82 After filter chain, 69 After filters, 81–82 after method AbstractController class, 69 authentication strategies, 229 creating hooks, 154 filter method, 69 Strategy class, 229 after_app_loads blocks, 30 AfterAppLoads boot loader, 30 after_app_loads method, 13–14 after_authentication method, 237 after_callbacks array, 237 Aggregates, 158–161

From the Library of Shirong Chen

Index all method, 142–145 alter_table_column_statement

method, 126 Ampersand (&), anchors in YAML nodes, 115 app argument, 3 app/ directory, 9 Application class, 31, 72 Application controllers, 72–74 Application layouts alternative, specifying, 28–29 core, 3 custom, 3 flat, 2–3, 6–8 overview, 2–3 standard, 3, 8–9 very flat, 2–6 Applications creating, 1–2 development environment, 7, 16–17 environments, 7, 16–17 nontemplate code, loading, 29 production environment, 7, 16–17 reloading, 11 single file. See Flat application layouts; Very flat application layouts. testing environment, 7, 16–17 assert_kind method, 144 Associations belongs to, 132–135 belongs_to method, 132–135 cardinality, specifying, 136 DataMapper versus ActiveRecord, 132–133 has, 132–133, 135–137 has method, 132–133 has through, 138–139 join table models, creating, 139 ManyToMany associations, 139 many-to-many-through, 139 one-to-many-through, 138–139

301 overview, 132–133 symbolized class names, 136 through method, 138–139 Attaching files to email, 260–261 Attributes, updating, 152–153 attribute_set method, 152 Audit routes rake task, 48 audit:routes command, 48 auth core. See Authentication, auth core. auth more. See Authentication, auth more. auth password slices. See Authentication, auth password slices. authenticate method, 235 authenticate! method, 225–226 Authentication, auth core abstract! method, 229 abstract? method, 229 add_rakefiles plugin, 222 after method, 229 after_authentication method, 237 after_callbacks array, 237 authenticate method, 235 authenticate! method, 225–226 Authentication class, 223–227 before method, 229 before_app_loads plugin, 222 callbacks, 236–237 customizations, 236 customize_default method, 236 ensure_authenticated helper, 234–235 error messages, storing, 232–233 halt! method, 230 halted? method, 230 helpers, 234–235 hooking methods, 224 inherited method, 229 initialize method, 230

From the Library of Shirong Chen

302

Index

Authentication, auth core (continued ) model class, selecting, 223 push_path method, 222 redirect method, 230 responses, 233–234 responses.rb file, 233–234 router helper, 235 run_after_authentication_ callbacks method, 226–227, 237

serial callbacks, 226–227 sessions, 231 setup.rb file, 222 strategies.rb file, 222 Strategy class, 227–231 user_class method, 231 Authentication, auth more controller, 245 encrypt method, 243 models, 242–245 overview, 237–238 passwords, encrypting, 243–244 redirect_back_or method, 245 redirecting logins, 245 strategies abstract! method, 238–239 access realms, 240 Base class, 238 basic, 239–241 basic_authentication?

method, 240 login_param method, 239

OpenID, 242 password form, 241 password_param method, 239 run! method, 239 Authentication, auth password slices

controller, 247–249 destroy action, 248 error_messages_for method, 250

Exceptions controller, 247–249 lib files, 246–247

login view, 249–250 Sessions controller, 247–249 underscored filters, 248 update action, 248 views, 249–250 Authentication class, 223–227 Auto-increment, enabling, 131 Auto-incrementing integers, 155 Automatic form actions, setting, 187 parameters, routing match rules, 51 parameters, symbolic matching, 51 validation, 132, 163 auto_migrate! method, 123–126 auto_upgrade! method, 123–126 :auto_validation option, 132 Average value, calculating, 159 avg method, 159

B Base class, 238 basic_authentication? method, 240 BCryptHash property type, 155 be_client_error matcher, 291–292 before class method, 80–81

Before filter chain, 69 Before filters, 80–81 before method AbstractController class, 69 authentication strategies, 229 creating hooks, 154 Strategy class, 229 BeforeAppHooks boot loader, 29 before_app_loads blocks, 29 before_app_loads plugin, 222 Belongs-to associations, 132–135

From the Library of Shirong Chen

Index be_missing matcher, 291–292 be_successful matcher, 291–292 BigDecimal class, 128

Binary flags, storing as integers, 155 Blank, testing for, 22 blank? method, 22 Block-aware enhancer, 103–105 BlockAwareEnhancer, 103–105 Blocks calling later, 97 placing in worker queue, 74 body method, 71 body= method, 71 Body of controller response, getting/setting, 71 Boolean class, 128. See also TrueClass. Boolean property type, 128 Boot loaders, overview, 27 BootLoader class AfterAppLoads, 30 BeforeAppHooks, 29 BuildFramework, 28–29 ChooseAdapter, 31 Cookies, 30 Defaults, 28 Dependencies, 29 DropPidFile, 28 LoadClasses, 29 Logger, 27 MimeTypes, 30 MixinSession, 29 RackUpApplication, 31–32 ReloadClasses, 32 ReloadTemplates, 32 SetupSession, 30 SetupStubClasses, 31 StartWorkerThread, 31 Templates, 29–30 Bound variants versus unbound, 181 bound_check_box method, 182–183

303 Builder module, 179 BuildFramework boot loader, 28–29 build_request method, 275–277 build_url method, 275–277

C cache action, 274–275 cache! action, 274–275 cache_action action, 274–275

Caching configuring ActionStore, 270 AdhocStore, 270 FileStore, 269–270

fundamental stores, 269–270 GzipStore, 270 MemcachedStore, 269–270 PageStore, 270 SHA1Store, 270 strategy stores, 270 delete method, 273 deleting, 273 exists? method, 272 fetch methods, 273 fetching, 273 helpers action caching, 274–275 build_request method, 275–277 build_url method, 275–277 cache action, 274–275 cache! action, 274–275 cache_action action, 274–275 eager caching, 275–277 eager_cache method, 275–277 fetch_fragment method, 277 fetch_partial method, 277–278 fragment caching, 277 partial caching, 277–278

From the Library of Shirong Chen

304 Caching (continued ) read method, 272 reading, 272 writable? method, 271–272 write method, 271–272 writing, 271–272 Caitlin, Hampton, 105 callable_actions method, 72 Callbacks, authentication, 236–237 Camel case, converting strings to, 21 camel_case method, 21 capture method, 71 capture_erb method, 71 Cardinality, specifying, 136 Casting values, 128–129 catch_content method, 71 cattr_accessor method, 20 cattr_reader method, 20 cattr_writer method, 20 -C flag, 9–10 Checkbox control, 182–183 check_box method, 189–190 Checking routes, 45 check_request_for_route method, 11 ChooseAdapter boot loader, 31 Class class, 20, 128 Classes listing, 20 models creating, 116 inheritance, 116 organizing, 115 Principle of Substitutability, 116 required for DataMapper, 115–117 Resource method, 115–117 names Haml views, 106–107 storing as strings, 128 reloading, 32

Index class_inheritable_accessor method,

20 class_inheritable_reader method, 20 class_inheritable_writer

method, 20 class_provided_formats method,

72–73 class_provided_formats= method,

72–73 clear! method, 208 clear_content method, 71

Clearing content, rendering templates, 71 clear_provides method, 72 Client response time, filters, 82 close_sandbox! method, 11 Collections, reversing object order, 145 Comments, ERB views, 103 Compiling templates, 89–90 concat method, 71 concat_erb method, 71 Conditions, validations, 163–164 conditions query parameter, 145 config/ directory, 12 Config method, 14 Configuration caching ActionStore, 270 AdhocStore, 270 FileStore, 269–270 fundamental stores, 269–270 GzipStore, 270 MemcachedStore, 269–270 PageStore, 270 SHA1Store, 270 strategy stores, 270 mailers delivery methods, 254–255 quota checking, 255 sendmail, 254

From the Library of Shirong Chen

Index SMTP, 253–254 test_send method, 254 sessions, 206 Configuration files databases, 19–20 database.yml, 19–20 development.rb, 16 environments, 16–17 init script after_app_loads method, 13–14 basic configuration, 14 dependencies, 13–14 gems and load path, 12 inflector customization, 15 libraries, distributing, 12–13 ORM options, 14–15 plugins, distributing, 12–13 RubyGems, 12–13 template engines, 14 testing options, 15 init.rb, 19–20 logging debug messages, 18 error messages, 18 example, 18 fatal messages, 18 flushing logs, 11, 18 info messages, 18 log file location, 17 message levels, specifying, 18 viewing logs, 18 warn messages, 18 production.rb, 16–17 router, 17 router.rb, 17, 43 routers, 43 test.rb, 17 YAML files, 19–20 Console methods, 10–11

305 Console traps, 9–10 Constants, converting to paths, 21 Content type for controller response, getting/setting, 71 content_type method, 71 content_type= method, 71 Contexts, validations, 164 Controller access, sessions, 220 Controller class class methods callable_actions, 72 class_provided_formats, 72 class_provided_formats=, 72 clear_provides, 72 does_not_provide, 72

format, 72 general, 72 hide_action, 72 only_provides, 72

overview, 70 provides, 72 reset_provides, 72 show_action, 72

instance methods class_provided_formats, 73 class_provided_formats=, 73 cookies, 73 delete_cookie, 73 does_not_provide, 73 escape_xml, 74

escaping, 74 format, 73 general, 73 h, 74 headers, 73 html_escape, 74 nginx_send_file, 74 only_provides, 73

other, 74

From the Library of Shirong Chen

306

Index

Controller class (continued )

general, 69, 70

instance methods (continued ) params, 73 provides, 73 rack_response, 73 redirect, 73 render_chunked, 74 render_deferred, 74 render_then_call, 74 request, 73 run_later, 74 send_chunk, 74 send_data, 74 send_file, 74 session, 73 session, 73 set_cookie, 73 status, 73 status=, 73 stream_file, 74 Controller classes AbstractController, methods before, 69 absolute_url, 71 action_name, 70 action_name=, 70 add_filter, 69 after, 69 body, 71 body=, 71 capture, 71 capture_erb, 71 catch_content, 71 clear_content, 71 concat, 71 concat_erb, 71 content_type, 71 content_type=, 71 controller_name, 69–70 default_layout, 70 filter, 69

inherited, 69

instance, 70 layout, 70 normalize_filters!, 69 partial, 71 relative_url, 71

render, 70 render, 71 render_all, 71 render_html, 71 render_js, 71 render_json, 71 render_options, 70 render_text, 71 render_xml, 71 render_yaml, 71 skip_after, 69 skip_before, 69 skip_filter, 69 subclasses_list, 69 template_roots, 70, 71 template_roots=, 70, 71 throw_content, 71 throw_content?, 71

URL, 71 url, 71

view, 71 Application, 72 Controller, class methods callable_actions, 72 class_provided_formats, 72 class_provided_formats=, 72 clear_provides, 72 does_not_provide, 72

format, 72 general, 72 hide_action, 72 only_provides, 72

overview, 70 provides, 72

From the Library of Shirong Chen

Index

307

reset_provides, 72 show_action, 72 Controller, instance methods class_provided_formats, 73 class_provided_formats=,

73 cookies, 73 delete_cookie, 73 does_not_provide, 73 escape_xml, 74

escaping, 74 format, 73 general, 73 h, 74 headers, 73 html_escape, 74 nginx_send_file, 74 only_provides, 73

other, 74 params, 73 provides, 73 rack_response, 73 redirect, 73 render_chunked, 74 render_deferred, 74 render_then_call, 74 request, 73 run_later, 74 send_chunk, 74 send_data, 74 send_file, 74

session, 73 session, 73 set_cookie, 73 status, 73 status=, 73 stream_file, 74 Exceptions, 31, 74

Controller classes, custom actions callable, setting, 79

hiding/showing, 79 readability, improving, 78 controller location, 75–76 naming controllers, 76 organizing methods action readability, improving, 78 making methods available to subclasses, 77–78 overview, 76 sharing nonaction methods, 77 controller key, 42 Controller prefixes, 59 Controller response body, getting/setting, 71 content type, getting/setting, 71 formats provided, 72, 73 controller_for_slice method, 201 controller_name method, 69–70 Controller#part method, 266–267 Controllers abstract, 69–70. See also AbstractController. application, 72–74 authentication auth more, 245 auth password slices, 247–249 calling actions, 66 definition, 34 dispatching requests, 66–67 exceptions, 74, 88 initializing, 66–67 location, 75–76 mailers, 257–258 Merb, 70–72. See also Controller class. names adding to subclasses_list, 69 creating, 76 returning, 69–70 parts, 263–266 rack response, 73 for slices, 200–201

From the Library of Shirong Chen

308 Controller#send_mail method,

258–259 Convention over configuration, 5 Converting constants to paths, 21 numbers to currency values, 169–170 strings to camel case, 21 time to EpochTime, 155 Cookies deleting, 73 functionality, loading, 30 getting, 73 session domain, setting, 206 session storage, 211–214 session store, encrypting, 206 setting, 73 Cookies boot loader, 30 cookies method, 73 CookieSession class, 211–214 Core application layouts, 3 core argument, 3 count method, 159–161 Counting numerical properties, 159–161 coverage task, 282 create action, 62 create_model_storage method, 123–126 create_table_statement method, 127 CRUD (create, retrieve, update, delete) basics all method, 142–145 assert_kind method, 144 creating records, 140–142 deleting collections, 154 deleting records, 154 destroy!: method, 154 destroy method, 154 enforcing types, 144 first method, 142–145 lazy loading of collections, 146–148 lazy loading of properties, 148–150

Index LazyArray class, 147–148

model objects, creating and saving, 140–142 N+1 queries, 150 overview, 140 query object algebra, 144 query parameters, adding, 143 Query#merge method, 144–145 Relationship class, 151–152 retrieving records data sets, reloading, 146 fields, fetching as an array, 145 grouping by fields, 146 including other data, 145 lazy loading of collections, 146–148 limiting number returned, 146 links in related model data, 146 overview, 142–145 query offset, 146 query order, 146 reversing object order, 145 SQL conditions, setting, 145 strategic eager loading, 150–152 scoped_query method, 143 special query parameters, 145–146 strategic eager loading, 150–152 updating records attribute_set method, 152 original values versus dirty values, 153 overview, 152 save method, 152 update_attributes method, 152–153 update_speed method, 153 CSS error class, adding, 186 Csv property type, 155 Curly braces ({ }), in Haml tags, 107 Currency values, converting numbers to, 169–170 current_form_context method, 187–188

From the Library of Shirong Chen

Index Custom application layouts, 3 Customizations, authentication, 236 customize_default method, 236 Cycle helpers, 176–177 cycle method, 176–177 Cycling through a list of values, 176–177

D Data sets, reloading, 146 Database storage automigrating DB schema, 121–127 default configuration file, 120 overview, 120–121 sample_development.db file, 120 Databases accessing without a password, 19 configuration files, 19–20 creating with rake, 120 database.yml files, 19–20, 115 DataMapper adapters, 114 associations, versus ActiveRecord, 132–133 CRUD. See CRUD (create, retrieve, update, delete) basics. data sources, 114 database back ends, 114 definition, 26 Ferret adapter, 114 required module, 115–117 Salesforce adapter, 114 session storage, 217–219 Date and time. See also Helpers, date and time. converting time to EpochTime, 155 property type, 128 time equivalent of date, 22 Date class, 128 date format, 171 DateAndTimeFormatting module, 173 DateTime class, 22, 128 db format, 171

309 Debug messages, logging, 18 Debugging code. See Interactive sessions. Decimal places, setting, 132 Decimal precision, property type, 128 default method, 57 :default option, 131 default_cookie_domain setting, 206 default_layout method, 70 Defaults boot loader, 28 Deferred blocks, running, 31 deferred method, 82 Deferred routes, routing match rules, 53–54 Deferring rendering responses, 74 Defining property types, 127–130, 155–156 Delete button, creating, 191 delete method, 11, 273 DELETE verb, 39–40 delete_button method, 191 delete_cookie method, 73 Deleting cache data, 273 collections, 154 cookies, 73 records, 154 URLs, 11 users, 62 Dependencies gems as, 13–14 init script file, 13–14 loading, 29 models, 114 Dependencies boot loader, 29 dependencies method, 14 dependency method, 13 Design principles, 5 destroy!: method, 154 destroy action, 62, 248 destroy method, 154 destroy_model_storage method, 123–126

From the Library of Shirong Chen

310 Development environment, applications, 7, 16–17 development.rb files, 16 Dirty values versus original, 153 tracking properties for, 132 Discriminator class, 128 _dispatch method, 66 Dispatcher, overview, 33 Dispatching requests, 11, 66–67 dispatch_request method, 11 dispatch_to method, 11 display method, 95–96 dm-aggregate plugin, 158–161 dm-timestamps gem, 156–158 does_not_provide method, 72–73 Domain matching, 41 Dot (.), in class names, 106 DropPidFile boot loader, 28 drop_table_statement method, 126 Dual-formatted email messages, 255

E Eager caching, 275–277 eager_cache method, 275–277 Ebb adapter, 25 ebb key, 25 edit action, 62 -e flag, 16 Email. See Mailers. emongrel key, 25 encrypt method, 243 Encryption cookies session store, 206 encrypt method, 243 passwords, 243–244 strings, 155 Enforcing types, 144 ensure_authenticated helper, 234–235

Index Enum property type, 155

Enumerated values, storing as integers, 155 Environment configuration file, loading, 29 Environments applications, 7, 16–17 configuration files, 16–17 settings, 16–17 specifying, 16–17 EpochTime, converting to, 155 EpochTime property type, 155 Equal sign (=) outputting results, 107–108 outputting strings, 108 sanitizing, 108 Equal signs (==), sanitizing, 108 ERB format, rendering templates, 89 ERB (eRuby) views. See also Views. # (pound sign), comment indicator, 103 <% %> delimiters, 102 <% =%> delimiters, 102 <%= %> delimiters, 102 <%= -%> delimiters, 102 basic delimiters, 102 block-aware enhancer, 103–105 BlockAwareEnhancer, 103–105 comments, 103 overview, 101–102 whitespace, removing, 102 Error messages logging, 18 storing, 232–233 error_messages_for method, 186, 191, 250 escape_regex method, 21 escape_xml method, 74 Escaping HTML entities, 74 methods, 74 special characters, 21, 155

From the Library of Shirong Chen

Index

311

strings, 155 XML entities, 74 Evented Mongrel adapter, 25 Exception controllers, setting up, 31 Exceptions in controller code, 74, 87–88. See also Exceptions controller. overview, 87 raising, 87 Exceptions class, 31, 74 Exceptions controller, 247–249 exists? method, 272 Expiration time for sessions, setting, 206 Extlib. See also Stack. / (slash), in file paths, 21 / (slash), path expansion, 22 blank, testing for, 22 blank? method, 22 camel_case method, 21 cattr_accessor method, 20 cattr_reader method, 20 cattr_writer method, 20 class, 20 Class class, 20 classes, listing, 20 class_inheritable_accessor

method, 20 class_inheritable_reader

method, 20 class_inheritable_writer

method, 20 date, 22 date, time equivalent, 22 DateTime class, 22 escape_regex method, 21 Hook module, 23 in? method, 21 inheritable class-level variables, creating, 20 keys, strings or symbols as, 22 lazy loading, 23

LazyArray class, 23 Logger class, 22

logging, 22 Mash class, 22 meta_class method, 21 methods, associating before/after other methods, 23 Object class, 21 objects in arrays, duplicating, 21 in arrays, finding, 21 singleton class access, 21 ObjectSpace class, 20 overview, 20 Pathname class, 22 Pooling module, 23 resource sharing, 23 SimpleSet class, 23 snake_case method, 21 String class, 21 strings camel case, converting to, 21 escaping special characters, 21 as inline templates, 23 joining in file paths, 21 language translation, 21 path/constant conversion, 21 snake case, converting to, 21 String.translate method, 21 String.translations

method, 21 t method, 21

time, returning, 22 Time class, 22 to_const_path method, 21 to_const_string method, 21 to_datetime method, 22 to_json method, 22 to_time method, 22 try_dup method, 21

From the Library of Shirong Chen

312 Extlib. See also Stack. (continued ) unescape_regex method, 21 unified class and instance variables, creating, 20 VirtualFile class, 23

F fake_request method, 11 FalseClass method, 22

FastCGI adapter, 25 Fatal messages, logging, 18 fcgi key, 25 Ferret adapter, 114 fetch methods, 273 fetch_fragment method, 277 Fetching cache data, 273 fetch_partial method, 277–278 -f flag, 18 :field option, 131 Fields fetching as an array, 145 grouping retrieved data by, 146 names, overriding, 131 fields query parameter, 145 Fieldset elements, creating, 180–182 fieldset method, 180, 189 fieldset_for method, 189 fields_for method, 189 File paths, strings in, 21 file_field method, 189–190 FilePath property type, 155 Files, attaching to email, 260–261 FileStore cache store, 269–270 Filter chains, adding filters, 69 Filter methods, 69 Filters before, 80–81 AbstractController methods, 69 adding to a filter chain, 69

Index after, 81–82 after class method, 81–82 after filter chain, 69 applying selectively, 82–83 before class method, 80–81 client response time, 82 deferred method, 82 ensuring option values are arrays, 69 before filter chain, 69 Haml views, 109 :if option, 83 options, 82–83 overview, 79–80 passing parameters to, 83 skip_after class method, 83–84 skip_before class method, 83–84 skipping, 69, 83–84 underscored, 248 :unless option, 83 :with option, 83 finalize method SessionContainer class, 208 SessionStoreContainer class, 211 first method, 142–145 Fixatable routes, 59–60 Flag property type, 155 Flat application layouts, 3, 6–8 flat argument, 3 Flexible segmentation, 52 Float class, 128 Floating property type, 128 flush method, 18 Flushing logs, 11, 18 form method, 180, 188 Form module, 187–191 format key, 42 :format key, 163 Format methods, 72–73 :format option, 132

From the Library of Shirong Chen

Index Formats controller response, 72, 73 date and time, 171–173 rendering templates default, 89 ERB, 89 specifying, 92–94 form_contexts method, 187–188 form_for method, 188–189 Forms actions, setting automatically, 187 context, changing from another form, 189 default builder, 187 elements, creating, 180–182, 185–187. See also Helpers, form. helpers. See Helpers, form. names, 188–189 without model object content, 188 ForumSlice module, 196 Fragment caching, 277 Freezing gems, 13

G Garbage collection, session storage, 215–216 Gems as dependencies, 13–14 directory size, reducing, 13 freezing, 13 libraries, distributing, 12–13 and load path, init script file, 12 --no-rdoc flag, 13 plugins, distributing, 12–13 RubyGems, 12–13 version-specific, installing, 13 generate method SessionContainer class, 208 SessionStoreContainer class, 211

313 get method, 11

GET verb, 39–40 Getter/setter methods, dynamic creation, 119 Getting. See Retrieving; specific items. Globs, 29 GzipStore strategy store, 270

H h method, 74 halt! method, 230 halted? method, 230 :haml parameter, 14

Haml views. See also Views. = (equal sign) outputting results, 107–108 outputting strings, 108 sanitizing, 108 . (dot), in class names, 106 == (equal signs), sanitizing, 108 - (hyphen), code indicator, 107 % (percent sign), tag indicator, 105 # (pound sign), in ID names, 106 { } (curly braces), in Haml tags, 107 ∼ (tilde), preserving whitespace, 108 class names, 106–107 filters, 109 history of, 105 HTML injections, preventing, 108 HTML-sensitive characters, sanitizing, 108 ID names, 106–107 indentation, 106 versus inline styles, 109 interpreting lines, 107 nesting code, 106 outputting lines, 107–108 sanitized lines, 108 tags, 105–106 whitespace, preserving, 108

From the Library of Shirong Chen

314 Has associations, 132–133, 135–137 has method, 132–133 Has through associations, 138–139 have_body matcher, 292 have_content_type matcher, 292 Headers, requests, 73 headers method, 73 Helpers authentication, 234–235 caching action caching, 274–275 build_request method, 275–277 build_url method, 275–277 cache action, 274–275 cache! action, 274–275 cache_action action, 274–275 eager caching, 275–277 eager_cache method, 275–277 fetch_fragment method, 277 fetch_partial method, 277–278 fragment caching, 277 partial caching, 277–278 cycle, 176–177 cycle method, 176–177 date and time date format, 171 DateAndTimeFormatting module, 173 db format, 171 formats, 171–173 long format, 171 prettier_time method, 175–176 relative date and time, 175–176 relative time, 175–176 relative_date method, 175 relative_date_span method, 175 relative_time_span method, 175 RFC 822 format, matching, 171 rfc822 format, 171

Index short format, 171

Time DSL, 173–175 time format, 171 time_lost_in_words method, 175

numeric minutes_to_hours method, 169 to_currency method, 169–170 two-digits method, 168 ordinalize method, 173

ordinals, 173 overview, 167 tag, 177–178 tag method, 178 truncate method, 167–168 Helpers, form. See also Forms. builders bound variants versus unbound, 181 bound_check_box method, 182–183 Builder module, 179 checkbox control, 182–183 CSS error class, adding, 186 error_messages_for method, 186 fieldset elements, 180–182 fieldset method, 180 form actions, setting automatically, 187 form elements, 180–182, 185–187 form method, 180 forms, default builder, 187 label elements, 184–185 label method, 184–185 name parameter, 179 obj parameter, 179 origin parameter, 179 process_form_attrs method, 180, 187 ResourcefulFormWithErrors, 187 update_bound_check_box method, 183–184

From the Library of Shirong Chen

Index

315

update_bound_controls

method, 186 update_*_controls method,

181–182 validation errors, outputting, 186 helpers check_box method, 189–190 current_form_context method, 187–188 delete button, creating, 191 delete_button method, 191 error_messages_for method, 191 fieldset method, 189 fieldset_for method, 189 fields_for method, 189 file_field method, 189–190 form context, changing from another form, 189 form method, 188 Form module, 187–191 form names, 188–189 form_contexts method, 187–188 form_for method, 188–189 forms without model object content, 188 hidden_field method, 189–190 password_field method, 189–190 radio_button method, 189–190 radio_group method, 189–190 select method, 189–190 singleton form context, 188 text_area method, 189–190 text_field method, 189–190 validation errors, outputting, 191 overview, 179 hidden_field method, 189–190 hide_action method, 72 Hiding actions, 72 Hijacking user accounts, 59–60 Hook module, 23

Hooking methods, authentication, 224 Hooks, models, 154 HTML (HyperText Markup Language) email messages, 255 entities, escaping, 74 injections, preventing, 108 MIME set, rendering views with, 71 html task, 282 html_escape method, 74 HTML-sensitive characters, sanitizing, 108 HTTP verbs, 39–40 Hyphen (-), code indicator, 107

I ID names, Haml views, 106–107 identify method, 63 :if option, 83 -i flag, 9–10, 13 in? method, 21 includes query parameter, 145 Indentation, Haml views, 106 index action, 61 :index option, 132 Indexing properties, 132 Inflector customization, 15 info messages, logging, 18 Inheritable class-level variables, creating, 20 Inheritance, model classes, 116 inherited method AbstractController class, 69 Strategy class, 229 Init file, loading, 29 Init script file after_app_loads method, 13–14 basic configuration, 14 dependencies, 13–14 gems and load path, 12 inflector customization, 15 libraries, distributing, 12–13

From the Library of Shirong Chen

316

Index

Init script file (continued ) ORM options, 14–15 plugins, distributing, 12–13 RubyGems, 12–13 template engines, 14 testing options, 15 initialize method, 230 Initializing controllers, 66–67 init.rb files, 19–20 Inline styles versus Haml views, 109 Inlining templates, 90 Instance methods, 70 Integer class, 128 Integers. See also Numbers. auto-incrementing, 155 binary flags as, 155 enumerated values as, 155 property type, 128 Interactive Merb, registering routes, 45–48 Interactive sessions check_request_for_route

method, 11 close_sandbox! method, 11

console methods, 10–11 console traps, 9–10 delete method, 11 dispatch_request method, 11 dispatch_to method, 11 fake_request method, 11 get method, 11 logger output, flushing, 11, 18 open_sandbox! method, 11 post method, 11 put method, 11 reload! method, 11 reloading the application, 11 request method, 11 request routes, checking or listing, 11 requests, 11

sandboxing, 11–12 show_routes method, 11 starting, 9 trace_log! method, 11 url method, 11 URLs, 11 IP addresses, storing as strings, 155 IPAddress property type, 155 IRB adapter, 25 irb key, 25 Iterating through a list of values, 176–177

J Join table models, creating, 139 JS MIME set, rendering views with, 71 JSON, storing as a string, 155 JSON MIME set, rendering views with, 71 Json property type, 155

K Katz, Yehuda, 103, 114 Kernel methods, 293–294 :key option, 131 Keys action, 42 controller, 42 ebb, 25 emongrel, 25 fcgi, 25 format, 42 :format, 163 irb, 25 :key option, 131 :length, 163 :nullable, 163 Rack, 25 route parameters, 42 runner, 25

From the Library of Shirong Chen

Index session_id_key setting, 206 session_secret_key setting, 206 :set, 163 :size, 163

strings or symbols as, 22 swift, 25 table keys, defining, 131 thin, 25 webrick, 25

L Label elements, creating, 184–185 label method, 184–185 Language translation, 21 layout method, 70 Layout options, rendering templates class-level, setting, 70 disabling, 70 resetting, 70 setting, 70 Layout templates, 94–95 layout_for_slice method, 201 Lazy loading collections, 146–148 enabling, 131 :lazy option, 131 LazyArray class, 23, 147–148 properties, 148–150 :lazy option, 131 LazyArray class, 23, 147–148 :length key, 163 :length option, 131. See also :size option. lib files, 246–247 Libraries, distributing, 12–13 limit query parameter, 146 links query parameter, 146 Listing classes, 20 routes

317 with audit routes rake task, 48 audit:routes command, 48

with interactive Merb, 45–48 route command, 45 show_routes method, 11, 47–48 subclasses, 69 users, 61 Literal matching, routing match rules, 50–51 Literal segments, 40–41 LoadClasses boot loader, 29 Location, controllers, 75–76 Logger boot loader, 27 Logger class, 22 Logger output, flushing, 11, 18 Loggers, updating, 29 Logging configuration files debug messages, 18 error messages, 18 example, 18 fatal messages, 18 flushing logs, 11, 18 info messages, 18 log file location, 17 message levels, specifying, 18 viewing logs, 18 warn messages, 18 Extlib, 22 Logger boot loader, 22, 27 Login view, 249–250 login_param method, 239 Logins, redirecting, 245 long format, 171

M MailController classes, 257–258 MailController#attach method,

260–261

From the Library of Shirong Chen

318

Index

Mailer class

max method, 159

configuring, 253–255 MailFactory interface, 255–257 Mailers actions invoking, 258–259 naming, 257–258 attaching files, 260–261 configuration delivery methods, 254–255 quota checking, 255 sendmail, 254 SMTP, 253–254 test_send method, 254 controllers, 257–258 Controller#send_mail method, 258–259 dual-formatted messages, 255 generating mailer files, 261–262 HTML email, 255 MailController classes, 257–258 MailController#attach method, 260–261 MailFactory, 255–257 multipart messages, 255 parameters, 259–260 rendering message views, 261 templates, 261 testing, 261 :test_method method, 261 using directly, 255–257 MailFactory, 255–257 ManyToMany associations, 139 Many-to-many-through associations, 139 Mash class, 22 Master process, 2 Match captures, registering routes with, 56 match method, routing match rules, 50 Match rules. See Routing, match rules.

Maximum value, calculating, 159 Memcached session storage, 216–217 MemcachedStore cache store, 269–270 Memory session storage, 214–216 MemorySessionStore class, 215–216 Merb controllers, 70–72 Merb servers overview, 32–33 shutting down, 2 Merb stack. See Stack. merb-gen command, 1–2 meta_class method, 21 (Method) parameters, 43 Method route conditions, 39–40 Methods. See also Helpers; specific methods. associating before/after other methods, 23 available as actions, 68 organizing action readability, improving, 78 making methods available to subclasses, 77–78 overview, 76 sharing nonaction methods, 77 MIME types, registering defaults, 30 MimeTypes boot loader, 30 min method, 159 Minimum value, calculating, 159 minutes_to_hours method, 169 MixinSession boot loader, 29 Model class, selecting for authentication, 223 Model objects, creating/saving, 140–142 Model serial IDs, property type, 128 Model specs, in testing, 283–285 model task, 281 Models after method, 154 associations. See Associations. authentication, auth more, 242–245

From the Library of Shirong Chen

Index classes creating, 116 inheritance, 116 organizing, 115 Principle of Substitutability, 116 required for DataMapper, 115–117 Resource method, 115–117 configuration, 113–115 CRUD basics. See CRUD (create, retrieve, update, delete) basics. database.yml file, 115 DataMapper adapters, 114 data sources, 114 database back ends, 114 dependencies, 114 hooks, 154 before method, 154 plugins. See Plugins. properties. See Properties. repository configuration, 114–115 serial IDs, 128 YAML configuration file, 114–115 YAML nodes, 115 Mongrel adapter, 25 Multipart email messages, 255

N N+1 queries, 150 name method, 58 name parameter, 179 Names actions, 70 controllers adding to subclasses_list, 69 creating, 76 returning, 69–70 mail controller actions, 257–258 MailController classes, 257

319 routes adding, 57–58 controller prefixes, 59 namespaces, 59 prefixing, 58–59 namespace method, 59 Namespaces, 59 Neighman, Daniel, 221 Nesting match statements, 50 new action, 62 nginx_send_file method, 74 NilClass class, 22 Nontemplate code, loading, 29 --no-rdoc flag, 13 normalize_filters! method, 69 Null values, disallowing, 131 :nullable key, 163 :nullable option, 131 Numbers. See also Integers. average value, calculating, 159 Boolean, 128 converting to currency, 169–170 counting, 159–161 dates and times, 128 decimal, precision, 128 decimal places, setting, 132 floating, 128 integers, 128 maximum value, calculating, 159 minimum value, calculating, 159 model serial IDs, 128 ordinals, 173 property types, 128 single-digit, padding to two digits, 168 summing, 159 Numeric class, 22 Numeric helpers minutes_to_hours method, 169 to_currency method, 169–170 two-digits method, 168

From the Library of Shirong Chen

320

O obj parameter, 179 Object class blank? method, 22

in Extlib, 21 property type, 128 Objects in arrays, duplicating, 21 in arrays, finding, 21 marshaling into records, 128 singleton class access, 21 ObjectSpace class, 20 offset query parameter, 146 One-to-many-through associations, 138–139 only_provides method, 72–73 OpenID, authentication strategy, 242 open_sandbox! method, 11 Optional matching, routing match rules, 52–53 options method, 59 order query parameter, 146 ordinalize method, 173 Ordinals, 173 origin parameter, 179 ORM options, init script file, 14–15 ORMs (object relational mappings), 25–27

P PageStore strategy store, 270 Parameters mailers, 259–260 (Method) parameters, 43 passing to filters, 83 request parameters, 43 from requests, 73 route parameters, 43 params method, 73 Parentheses (( )), in optional route matching, 52 PartController class, 263–266 Partial caching, 277–278

Index partial method, 71

Partials, 111–112 Parts actions, 266–267 controllers, 263–266 generating files, 267 Passing in literal strings, routing match rules, 51 Password form, authentication strategy, 241 password_field method, 189–190 password_param method, 239 Passwords. See also Authentication, auth password slices; Security. accessing databases without, 19 authentication. See Authentication, auth password slices. encrypting, 243–244 encryption, 243–244 form authentication strategy, 241 password_field method, 189–190 password_param method, 239 Path route conditions definition, 39 literal segments, 40–41 overview, 40–41 query strings, 40 segments, 40–41 symbolic segments, 40–41 syntax, 40–41 Pathname class, 22 Paths converting to constants, 21 storing as strings, 155 Percent sign (%), tag indicator, 105 Persistent accessors, 118 Pidfile, dropping, 28 Plugins addressable URIs, storing as strings, 155 aggregates, 158–161 auto-incrementing integers, 155

From the Library of Shirong Chen

Index average value, calculating, 159 avg method, 159 binary flags, storing as integers, 155 count method, 159–161 counting numerical properties, 159–161 distributing, 12–13 dm-aggregate plugin, 158–161 dm-timestamps gem, 156–158 encrypting strings, 155 enumerated values, storing as integers, 155 EpochTime, converting to, 155 escaping strings, 155 IP addresses, storing as strings, 155 JSON, storing as a string, 155 max method, 159 maximum value, calculating, 159 min method, 159 minimum value, calculating, 159 numerical properties, 159 parsing strings as CSVs, 155 paths, storing as strings, 155 property types, 155–156. See also specific types. records, counting, 158–161 regular expressions, storing as strings, 155 strings, 155 sum method, 159 summing numerical values, 159 timestamps, 156–158 URLs, strings in, 155 UUIDs, storing as strings, 155 validations. See also specific validation methods. automatic, turning off, 132, 163 with blocks, 162 conditions, 163–164 confirming attributes, 162 contexts, 164 errors, 164–165 format of a value, 162

321 formats, 163 with methods, 162 numerical length, 162–163 numerical values, 162 overview, 162–163 presence of, 163 presence of a value, 162 within a range of values, 162–163 true values, 162 uniqueness, 162–163 validates_within method, 163 YAML, storing as a string, 155 Pooling module, 23 post method, 11 POST verb, 39–40 Posting URLs, 11 Pound sign (#) comment indicator, 103 in ID names, 106 Power, David, 255 :precision option, 132 Prefixing route names, 58–59 Prepare block, router configuration, 43–44 prettier_time method, 175–176 Principle of least surprise, 5 Principle of Substitutability, 116 process_form_attrs method, 180, 187 Production environment, applications, 7, 16–17 production.rb files, 16–17 Properties access privileges, setting, 131 alter_table_column_statement

method, 126 auto-increment, enabling, 131 auto_migrate! method, 123–126 auto_upgrade! method, 123–126 create_model_storage method, 123–126

From the Library of Shirong Chen

322

Index

Properties (continued ) create_table_statement method,

127 database storage automigrating DB schema, 121–127 default configuration file, 120 overview, 120–121 sample_development.db file, 120 in DataMapper, benefits of, 121 decimal places, setting, 132 default value, setting, 131 defining casting values, 128–129 options, 131–132. See also specific options. overview, 127 property types, 127–130, 155–156. See also specific types. destroy_model_storage method, 123–126 drop_table_statement method, 126 field names, overriding, 131 getter/setter methods, dynamic creation, 119 including in model files, 121 indexing, 132 lazy-loading, enabling, 131 null values, disallowing, 131 overview, 118–120 persistent accessors, 118 properties_with_subclasses

method, 127 property_schema_statement

method, 127 size, setting, 131 with subclasses, 127 table keys, defining, 131 tracking for dirtiness, 132 type plugins, 155–156 upgrade_model_storage method,

123–126

validation, 132 values, setting with instance variables, 119–120 properties_with_subclasses method, 127 property_schema_statement method, 127 Protocol matching, 41 provides method, 72–73 public/ directory, 9 push_path method, 222 put method, 11 PUT verb, 39–40 Putting URLs, 11

Q Queries N+1, 150 parameters, adding, 143 special query parameters, 145–146 strings, path route conditions, 40 Query object algebra, 144 Query offset, 146 Query order, 146 Query#merge method, 144–145 Quota checking, email, 255

R Rack. See also Stack. adapter options, 23–25 adapters, choosing, 31 Ebb adapter, 25 ebb key, 25 emongrel key, 25 Evented Mongrel adapter, 25 FastCGI adapter, 25 fcgi key, 25 functional description, 24–26 IRB adapter, 25

From the Library of Shirong Chen

Index irb key, 25 Mongrel adapter, 25 ORMs (object relational mappings), 25 overview, 23 Runner adapter, 25 runner key, 25 setting up, 31–32 swift key, 25 Swiftiplied Mongrel adapter, 25 Thin adapter, 25 thin key, 25 WEBrick adapter, 25 webrick key, 25 Rack response, controllers, 73 rack_response method, 73 RackUpApplication boot loader, 31–32 radio_button method, 189–190 radio_group method, 189–190 Rake tasks, in testing, 279–282 read method, 272 :reader option, 131 Reading cache data, 272 Reaping session storage, 215–216 Records, counting, 158–161 redirect matcher, 292 redirect method Controller class, 73 registering a redirect, 56 Strategy class, 230 redirect_back_or method, 245 Redirecting logins, 245 Redirects after-POST requests, 85 a caveat, 84–85 in before filters, 86–87 overview, 84 redirect method, 73, 84 registering, 56 registering routes with, 56

323 redirect_to matcher, 292 regenerate method SessionContainer class, 208 SessionStoreContainer class, 211 Regexp property type, 155 register method

generating slices, 195–196 registering routes with, 55–56. See also To method; With method. Registering route parameters, 54 Registering routes with match captures, 56 to method, 54–55. See also Register method; With method. with method, 55. See also Register method; To method. redirecting, 56 register method, 55–56. See also To method; With method. symbols, 56–57 Regular expressions routing match rules, 53 segment-specific, routing match rules, 52 setting route conditions, 39 storing as strings, 155 validation against, 132 Relationship class, 151–152 Relative time, 175–176 relative_date method, 175 relative_date_span method, 175 relative_time_span method, 175 relative_url method, 71 reload! method, 11 reload query parameter, 146 ReloadClasses boot loader, 32 Reloading applications, 11 classes, 32 ReloadTemplates boot loader, 32 Renaming resources, 63

From the Library of Shirong Chen

324 render method AbstractController class, 71

basic rendering, 91–92 Render methods, 70 render_all method, 71 render_chunked method, 74, 96 render_deferred method, 74, 96–97 render_html method, 71 Rendering email message views, 261 responses, 74 views, 71 Rendering, templates basic rendering, 91–92 clearing content, 71 compiling templates, 89–90 display method, 95–96 formats default, 89 ERB, 89 specifying, 92–94 inlining templates, 90 layout options, 70 layout template, 94–95 overview, 89 render method, 91–92 render methods, 70 render_chunked method, 96 render_deferred method, 96–97 render_then_call method, 97 status code, setting, 94 :status option, 94 render_js method, 71 render_json method, 71 render_options method, 70 render_text method, 71 render_then_call method, 74, 97 render_xml method, 71 render_yaml method, 71

Index Repository configuration, 114–115 Request access, sessions, 219 Request class, 33 Request helper, in testing, 289–290 Request matchers, in testing, 290–292 request method, 11, 73 Request parameters, 43 Request routes, checking or listing, 11 Request specs, in testing, 285–288 request task, 281 REQUEST_METHOD option, 66–67 REQUEST_PATH option, 66–67 Requests building, 11 dispatching, 11, 33, 66–67 headers, 73 incoming, dispatching, 33 object routed to the controller, 73 overview, 33 parameters, 73 returning, 11 status codes, 73 reset_provides method, 72 Resource method, 115–117 resource method, 62–63 Resource routes. See also Routers; Routes; Routing. renaming resources, 63 standard resources routing create action, 62 deleting users, 62 destroy action, 62 edit action, 62 index action, 61 new action, 62 resources method, 60–62 show action, 62 single resource routing, 62–63 update action, 62 updating users, 62

From the Library of Shirong Chen

Index user accounts, creating, 62 user profiles, displaying, 62 users, listing, 61 Resource sharing, 23 ResourcefulFormWithErrors, 187 resources method, 60–62 respond_successfully matcher,

291–292 Responses, authentication, 233–234 responses.rb file, 233–234 Restarting after code changes, avoiding, 7 retrieve method, 211 Retrieving records data sets, reloading, 146 fields, fetching as an array, 145 grouping by fields, 146 including other data, 145 lazy loading of collections, 146–148 limiting number returned, 146 links in related model data, 146 overview, 142–145 query offset, 146 query order, 146 reversing object order, 145 SQL conditions, setting, 145 strategic eager loading, 150–152 URLs, 11 RFC 822 format, matching, 171 rfc822 format, 171 route command, 45 Route conditions DELETE, 39–40 domain matching, 41 GET, 39–40 HTTP verbs, 40 methods, 39–40 minimal requirements, 39 paths definition, 39

325 literal segments, 40–41 overview, 40–41 query strings, 40 segments, 40–41 symbolic segments, 40–41 syntax, 40–41 POST, 39–40 protocol matching, 41 PUT, 39–40 setting with regular expressions, 39 Route parameters action key, 42 controller key, 42 defaults, setting, 57 definition, 42 format key, 42 keys, 42 registering, 54 settings, 54 Router helper, authentication, 235 router.rb files, 17 Routers behaviors, definition, 38 configuration configuration file, 43 prepare block, 43–44 route order, 44 router.rb file, 43 routes, adding, 44–45 configuration files, 17 definition, 33 testing URL generation and recognition, 49–50 Routes absolute URLs, returning, 71 adding, 44–45 checking, 45 definition, 38 fixatable, 59–60 including session IDs. See Session fixation.

From the Library of Shirong Chen

326 Routes (continued ) interaction with resources. See Resource routes. listing with audit routes rake task, 48 audit:routes command, 48 with interactive Merb, 45–48 route command, 45 show_routes method, 47–48 names adding, 57–58 controller prefixes, 59 namespaces, 59 prefixing, 58–59 order, specifying, 44 registering with match captures, 56 to method, 54–55. See also Register method; With method. with method, 55. See also Register method; To method. redirecting, 56 register method, 55–56. See also To method; With method. symbols, 56–57 relative URLs, returning, 71 session fixation, 59–60 showing, 11, 47–48 Routing, match rules deferred routes, 53–54 full regular expressions, 53 literal matching, 50–51 match method, 50 nesting match statements, 50 overview, 50 passing in literal strings, 51 symbolic matching ( ) (parentheses), in optional matching, 52 automatic parameters, 51

Index flexible segmentation, 52 optional matching, 52–53 overview, 51 segment-specific regular expressions, 52 Routing, overview, 38 RSpec extensions, in testing, 292–294 RubyGems, 12–13 run! method, 239 run_after_authentication_ callbacks method, 226–227,

237 run_later method, 97

Runner adapter, 25 runner key, 25

S Salesforce adapter, 114 sample_development.db file, 120

Sandboxing, 11–12 Sanitized lines, Haml views, 108 save method, 152 :scale option, 132 Schaefer, Bernerd, 114 scoped_query method, 143 Security. See also Passwords. hijacking user accounts, 59–60 session fixation, 59–60 Segments, path route conditions, 40–41 Segment-specific regular expressions, routing match rules, 52 select method, 189–190 send_chunk method, 74 send_data method, 74 send_file method, 74 Sending binary data, 74 chunks, 74 files attached to email, 260–261 overview, 97–98

From the Library of Shirong Chen

Index send_file method, 98

through nginx, 74 Sendmail, 254 Sequel, 26 Serial callbacks, authentication, 226–227 Serial class, 128 Serial IDs, models, 128 :serial option, 131 Serial property type, 155 Server. See Merb servers. Session containers, 207–208, 214–215 Session fixation, 59–60 session method, 73, 220 Session methods, 73 Session store, accessing, 73 SessionContainer class, 207–208 session_expiry setting, 206 session_id= method, 208 session_id_key setting, 206 Sessions authentication, 231 configuration, 206 containers, setting up, 30 controller access, 220 cookie domain, setting, 206 cookie session store, encrypting, 206 default values, setting up, 30 default_cookie_domain setting, 206 definition, 34 expiration time, setting, 206 functionality, adding, 29 IDs, 205–206 overview, 205–206 request access, 219 session method, 220 session_expiry setting, 206 session_id_key setting, 206 session_secret_key setting, 206 session_store setting, 206

327 Sessions, storing clear! method, 208 finalize method SessionContainer class, 208 SessionStoreContainer class, 211 generate method SessionContainer class, 208 SessionStoreContainer class, 211 regenerate method SessionContainer class, 208 SessionStoreContainer class, 211 retrieve method, 211

session containers, 207–208, 214–215 SessionContainer class, 207–208 session_id= method, 208 SessionStoreContainer class,

208–211 setup method SessionContainer class, 208 SessionStoreContainer class, 211

storage mechanisms cookie sessions, 211–214 CookieSession class, 211–214 DataMapper sessions, 217–219 garbage collection, 215–216 memcached sessions, 216–217 memory sessions, 214–216 MemorySessionStore class, 215–216 reaping sessions, 215–216 TamperedWithCookie error, 214 store containers, 208–211, 214–215 Sessions controller, 247–249 session_secret_key setting, 206 session_store setting, 206 SessionStoreContainer class, 208–211 :set key, 163 set_cookie method, 73 Setting. See specific items.

From the Library of Shirong Chen

328 setup method SessionContainer class, 208 SessionStoreContainer class, 211 setup.rb file, 222 SetupSession boot loader, 30 SetupStubClasses boot loader, 31 SHA1Store strategy store, 270 short format, 171 show action, 62 show_action method, 72

Showing actions, 72 routes, 11, 47–48 show_routes method, 11, 47–48 SimpleSet class, 23 Single resource routing, 62–63 Singleton form context, 188 Singular words, switching to plural, 15 :size key, 163 Size of properties, setting, 131 :size option, 131. See also :length option. skip_after class method, 83–84 skip_after method, 69 skip_before class method, 83–84 skip_before method, 69 skip_filter method, 69 Skipping filters, 69, 83–84 Slash (/) in file paths, 21 path expansion, 22 slice command, 196–199 slice method, 201–203 Slices. See also Authentication, auth password slices. developing building slices into gems, 199–200 controller_for_slice method, 201 controllers, 200–201

Index ForumSlice module, 196

generating slices, 193–196 layout_for_slice method, 201 register method, 195–196

running slices, 196–199 slice command, 196–199

using add_slice method, 202–203

overview, 201 slice method, 201–203 Slug property type, 155

SMTP, 253–254 Snake case, converting strings to, 21 snake_case method, 21 Spec files, in testing, 282–283 Special characters, escaping, 21 spectasks.rb file, 279–280 SQL conditions, setting, 145 Stack. See also Extlib; Rack. ORMs (object relational mappings), 26–27. See also ActiveRecord; Sequel. plugins, 26–27 Standard application layouts, 3, 8–9 Standard resources routing create action, 62 deleting users, 62 destroy action, 62 edit action, 62 index action, 61 new action, 62 resources method, 60–62 show action, 62 single resource routing, 62–63 update action, 62 updating users, 62 user accounts, creating, 62 user profiles, displaying, 62 users, listing, 61 StartWorkerThread boot loader, 31

From the Library of Shirong Chen

Index Status codes rendering templates, setting, 94 requests, sending, 73 in testing, 291–292 status method, 73 status= method, 73 :status option, 94 Stepping through a list of values, 176–177 Storage mechanisms cookie sessions, 211–214 CookieSession class, 211–214 DataMapper sessions, 217–219 garbage collection, 215–216 memcached sessions, 216–217 memory sessions, 214–216 MemorySessionStore class, 215–216 reaping sessions, 215–216 TamperedWithCookie error, 214 Store containers, 208–211, 214–215 Storing sessions. See Sessions, storing. Strategic eager loading, 150–152 strategies.rb file, 222 Strategy class, 227–231 Strategy stores, 270 stream_file method, 74 Streaming files, 74, 97–98 String class, 21, 128 Strings camel case, converting to, 21 encrypting, 155 escaping special characters, 21, 155 globs, 29 as inline templates, 23 joining in file paths, 21 language translation, 21 parsing as CSVs, 155 path/constant conversion, 21 snake case, converting to, 21

329 storing, 128 truncating, 167–168 in URLs, 155 String.translate method, 21 String.translations method, 21

Stub classes, setting up, 31 Subclasses, listing, 69 subclasses_list method, 69 sum method, 159 Summing numerical properties, 159 swift key, 25 Swiftiplied Mongrel adapter, 25 Symbolic matching routing match rules ( ) (parentheses), in optional matching, 52 automatic parameters, 51 flexible segmentation, 52 optional matching, 52–53 overview, 51 segment-specific regular expressions, 52 Symbolic segments, 40–41 Symbolized class names, 136 Symbols registering routes with, 56–57 thrown content, catching, 71

T t method, 21

Table keys, defining, 131 Tag helpers, 177–178 tag method, 178 Tags, Haml views, 105–106 TamperedWithCookie error, 214 Template engines, init script file, 14 template_roots method, 70, 71 template_roots= method, 70, 71 Templates. See also Views. capture method, calling, 71 capturing ERB blocks, 71

From the Library of Shirong Chen

330 Templates. See also Views. (continued ) concat method, calling, 71 concatenating ERB blocks, 71 embedding in templates, 71 ERB blocks, 71 inline, strings as, 23 inlining, 29–30 mailers, 261 Merb view templates, 109–111 reloading, 32 rendering. See Rendering, templates. root location, 70, 71 within templates, 111–112 templating system, default, 101–102 throwing content, 71 thrown content, checking for, 71 view. See Flat application layouts. Templates boot loader, 29–30 Testing be_client_error matcher, 291–292 be_missing matcher, 291–292 be_successful matcher, 291–292 coverage task, 282 extensions, 293–294 have_body matcher, 292 have_content_type matcher, 292 html task, 282 Kernel methods, 293–294 mailers, 261 model specs, 283–285 model task, 281 rake tasks, 279–282 redirect matcher, 292 redirect_to matcher, 292 request helper, 289–290 request matchers, 290–292 request specs, 285–288 request task, 281 respond_successfully matcher, 291–292

Index routers, URL generation and recognition, 49–50 RSpec extensions, 292–294 spec files, 282–283 spectasks.rb file, 279–280 status codes, 291–292 Testing environment, applications, 7, 16–17 Testing options, init script file, 15 :test_method method, 261 test.rb files, 17 test_send method, 254 Text class, 128 Text data, storing, 128 Text MIME set, rendering views with, 71 text_area method, 189–190 text_field method, 189–190 Thin adapter, 25 thin key, 25 through method, 138–139 throw_content method, 71 throw_content? method, 71 Tilde (∼), preserving whitespace, 108 Time, returning, 22 Time class, 22, 128 Time DSL, 173–175 time format, 171 time_lost_in_words method, 175 Timestamps, 156–158 to method, registering routes with, 54–55. See also Register method; With method. to_const_path method, 21 to_const_string method, 21 to_currency method, 169–170 to_datetime method, 22 to_json method, 22 to_time method, 22 trace_log! method, 11 :track option, 132

From the Library of Shirong Chen

Index TrueClass class, 128. See also Boolean

class. truncate method, 167–168 try_dup method, 21 two-digits method, 168

U Underscored filters, 248 unescape_regex method, 21 Unified class and instance variables, creating, 20 Uniform Resource Locators (URLs). See URLs (Uniform Resource Locators). unique query parameter, 146 :unique_index option, 132 Uniqueness, validating, 162–163 :unless option, 83 update action, 62, 248 update_attributes method, 152–153 update_bound_check_box method, 183–184 update_bound_controls method, 186 update_*_controls method, 181–182 update_speed method, 153 Updating attributes, 152–153 records attribute_set method, 152 original values versus dirty values, 153 overview, 152 save method, 152 update_attributes method, 152–153 update_speed method, 153 updating attributes, 152–153 users, 62 upgrade_model_storage method, 123–126 URI property type, 155

331 URIs, storing as strings, 155 url method AbstractController class, 71

Merb console, 11 URLs, generating, 11, 50 URL methods, 71 URLs (Uniform Resource Locators) absolute, returning, 71 deleting, 11 generating, 11 getting, 11 posting, 11 putting, 11 relative, returning, 71 retrieving, 11 router generation, testing, 50 router recognition, testing, 49–50 strings in, 155 User accounts creating, 62 hijacking, 59–60 user_class method, 231 Users deleting, 62 listing, 61 profiles, displaying, 62 updating, 62 use_template_engines method, 14 UUID property type, 155 UUIDs, storing as strings, 155

V validates_absent method, 162 validates_format method, 162 validates_is_accepted

method, 162 validates_is_confirmed

method, 162 validates_is_number method, 162

From the Library of Shirong Chen

332

Index

validates_is_unique method,

162–163 validates_length method, 162 validates_present method, 162 validates_with_block method,

162 validates_within method, 163 validates_with_method

method, 162 Validations automatic, 132 automatic, turning off, 132, 163 with blocks, 162 conditions, 163–164 confirming attributes, 162 contexts, 164 errors, 164–165, 186, 191 format of a value, 162 formats, 163 with methods, 162 numerical length, 162–163 numerical values, 162 overview, 162–163 presence of, 163 presence of a value, 162 within a range of values, 162–163 against regular expressions, 132 true values, 162 uniqueness, 162–163 validates_within method, 163 Very flat application layouts, 3–6 very_flat argument, 3–6 View methods, 71 View templates. See Flat application layouts. Views. See also Templates. authentication, 249–250 for ERB. See ERB (eRuby) views.

for HTML. See Haml views. login, 249–250 Merb view templates, 109–111 partials, 111–112 templates within templates, 111–112 templating system, default, 101–102 for XML. See Haml views. VirtualFile class, 23

W Warn messages, logging, 18 WebController mixin, 265–266 WEBrick adapter, 25 webrick key, 25 Weizenbaum, Nathan, 105 Whitespace preserving, 108 removing, 102 sensitivity, 19 Widgets. See Parts. with method, registering routes with, 55. See also Register method; To method. :with option, 83 Worker queue, placing blocks in, 74 Worker threads, starting, 31 Workers, definition, 34 writable? method, 271–272 write method, 271–272 :writer option, 131 Writing cache data, 271–272

X XML entities, escaping, 74 XML MIME set, rendering views with, 71

From the Library of Shirong Chen

Index

Y YAML configuration file, 114–115 files, 19–20

333 MIME set, rendering views with, 71 nodes, 115 storing as a string, 155 Yaml property type, 155

From the Library of Shirong Chen

Also Available in The Addison-Wesley Professional Ruby Series Professional Ruby Collection Mongrel, Rails Plugins, Rails Routing, Refactoring to REST, and Rubyisms, CD 1 James Adam, David A. Black, Trotter Cashion, Jacob Harris, Matt Pelletier, Zed Shaw | 978-0-132-41799-0 This package brings together 8 breakthrough primers on today’s most valuable Ruby and Rails technologies—including five new digital Short Cuts worth $69.95 and chapters from The Ruby Way, RailsSpace, and The Rails Way. Insider’s information never before available in one place!

The Ruby Way, Second Edition Hal Fulton | 978-0-672-32884-8 The Ruby Way takes a “how-to” approach to Ruby programming with the bulk of the material consisting of more than 400 examples arranged by topic. Each example answers the question “How do I do this in Ruby?” Working along with the author, you are presented with the task description and a discussion of the technical constraints. This is followed by a step-by-step presentation of one good solution. Along the way, the author provides detailed commentary and explanations to aid your understanding.

RailsSpace Building a Social Networking Website with Ruby on Rails™ Michael Hartl & Aurelius Prochazka | 978-0-321-48079-8 Ruby on Rails is fast displacing PHP, ASP, and J2EE as the development framework of choice for discriminating programmers. Using a tutorial approach, RailsSpace teaches you to build large-scale projects with Rails by developing a real-world, social networking website application. This essential introduction to Rails provides you with a solid foundation for creating any login-based website in Rails; coverage of newer and more advanced Rails features such as form generators, REST, and Ajax (including RJS); and a thorough and integrated introduction to automated testing.

The Rails Way Obie Fernandez | 978-0-321-44561-2 Ruby on Rails strips complexity from the development process, enabling professional developers to focus on what matters most: delivering business value. Now, for the first time, there’s a comprehensive, authoritative guide to building productionquality software with Rails. Pioneering Rails developer Obie Fernandez and a team of experts illuminate the entire Rails API, along with the Ruby idioms, design approaches, libraries, and plug-ins that make Rails so valuable. Drawing on their unsurpassed experience, they address the real challenges development teams face, showing how to use Rails’ tools and best practices to maximize productivity and build polished applications users will enjoy.

For more information, visit informit.com/ruby | informit.com/shortcuts From the Library of Shirong Chen

A LSO A VAILABLE I N T HE A DDISON -W ESLEY P ROFESSIONAL R UBY S ERIES SHORT CUTS are succinct, to-the-point, fast reads on new and existing technologies. They’re digital—delivered in Adobe Reader PDF. They’re published quickly and provide the knowledge you need right away. Short cuts show you how to solve a specific problem and introduce you to new topics. Written by industry experts and bestselling authors, short cuts are published with you in mind—getting you the technical information you need now.

Rubyisms in Rails JACOB HARRIS | ISBN: 978-0-321-47407-0 A look at how the grace and philosophy of the Ruby language are reflected in the design of Ruby on Rails. The main goal is simply aesthetic appreciation. But if you are a beginning programmer in Rails who is stymied in your understanding of Ruby—or an intermediate Rails developer still writing code that looks like Ruby-tinged PHP or Java—this short cut will enlighten and inspire you about the Ruby way of programming. It also reveals how the revolutionary design of the Rails framework can only be built upon the beauty of Ruby.

Rails Plugins: Extending Rails Beyond the Core JAMES ADAM | ISBN: 978-0-321-48351-5 This short cut introduces Rails plugins and considers each aspect of their behavior and development. You’ll learn what plugins are, how they work, and why they’re useful. Discover how to find and install plugins using the provided script, then explore the world of plugin development, including common plugin idioms, testing, and version control. Finally, learn how to share your own plugins with the rest of the world.

Mongrel: Serving, Deploying, and Extending Your Ruby Applications MATT PELLETIER and ZED SHAW | ISBN: 978-0-321-48350-8 A critical resource for any developer, system/network administrator, or business owner interested in understanding Mongrel, a fast, versatile Ruby Web server. Since its initial release in January 2006, Mongrel has quickly gained the attention and support of the Ruby community as its preferred server. This short cut is the only comprehensive Mongrel documentation in existence and is written by the authors of Mongrel. It provides background information, setup and configuration instructions, and development techniques for extending Mongrel. It also covers performance tuning and security.

Rails Refactoring to Resources: Using CRUD and REST in Your Rails Application TROTTER CASHION | ISBN: 978-0-321-50174-5 Since David Heinemeier Hansson’s keynote speech at RailsConf 2006 and the release of Rails 1.2 in early 2007, Representational State Transfer, better known as REST, has taken the Rails world by storm. If you’re new to REST, this short cut will help you decide which parts of the REST paradigm you want to introduce to your application. If you’re a developer with more RESTful experience, this short cut will introduce you to some refactorings that will give your application a cleaner, leaner code base, while also serving as a reference to much of the functionality REST has brought to Rails.

Rails Routing David A. Black | ISBN: 978-0-321-50924-6 The Rails routing system has always been a key component of the framework, and with the introduction of RESTful routes in the past year, it has taken center stage. Fully programmable, the routing system governs the process of mapping request URLs to the appropriate controller action. In this short cut, you’ll learn techniques for writing custom routing rules, how to tap into the convenience and power of named routes, and the workings of the RESTful routing that’s had such an impact on Rails development.

Troubleshooting Ruby Processes: Leveraging System Tools when the Usual Ruby Tricks Stop Working Philippe Hanrigou | ISBN: 978-0-321-54468-1 When programmers develop a Ruby application they commonly experience complex problems which require some understanding of the underlying operating system to be solved. Difficult to diagnose, these problems can make the difference between a project’s failure or success. This short cut demonstrates how to leverage system tools available on Mac OS X, Linux, Solaris, BSD or any other Unix flavor to resolve problems that are difficult to diagnose with the standard Ruby development tools.

Writing Efficient Ruby Code Dr. Stefan Kaes | ISBN: 978-0-321-54003-4 This short cut focuses on a number of coding patterns which are useful when trying to get maximum speed out of performance critical sections of Ruby code. Anti-patterns, i.e. coding idioms which should be avoided in performance sensitive code sections, are also discussed and include details on how to transform such code to make it more efficient.

For more information, visit informit.com/ruby | informit.com/shortcuts From the Library of Shirong Chen

THIS PRODUCT informit.com/register Register the Addison-Wesley, Exam Cram, Prentice Hall, Que, and Sams products you own to unlock great beneﬁts. To begin the registration process, simply go to informit.com/register to sign in or create an account. You will then be prompted to enter the 10- or 13-digit ISBN that appears on the back cover of your product.

About InformIT

Registering your products can unlock the following beneﬁts: • Access to supplemental content, including bonus chapters, source code, or project ﬁles. • A coupon to be used on your next purchase. Registration beneﬁts vary by product. Beneﬁts will be listed on your Account page under Registered Products.

— THE TRUSTED TECHNOLOGY LEARNING SOURCE

INFORMIT IS HOME TO THE LEADING TECHNOLOGY PUBLISHING IMPRINTS Addison-Wesley Professional, Cisco Press, Exam Cram, IBM Press, Prentice Hall Professional, Que, and Sams. Here you will gain access to quality and trusted content and resources from the authors, creators, innovators, and leaders of technology. Whether you’re looking for a book on a new technology, a helpful article, timely newsletters, or access to the Safari Books Online digital library, InformIT has a solution for you.

informIT.com

Addison-Wesley | Cisco Press | Exam Cram IBM Press | Que | Prentice Hall | Sams

THE TRUSTED TECHNOLOGY LEARNING SOURCE

SAFARI BOOKS ONLINE

From the Library of Shirong Chen

From the Library of Shirong Chen

Try Safari Books Online FREE Get online access to 5,000+ Books and Videos

FREE TRIAL—GET STARTED TODAY! www.informit.com/safaritrial Find trusted answers, fast Only Safari lets you search across thousands of best-selling books from the top technology publishers, including Addison-Wesley Professional, Cisco Press, O’Reilly, Prentice Hall, Que, and Sams.

Master the latest tools and techniques In addition to gaining access to an incredible inventory of technical books, Safari’s extensive collection of video tutorials lets you learn from the leading video training experts.

WAIT, THERE’S MORE! Keep your competitive edge With Rough Cuts, get access to the developing manuscript and be among the ﬁrst to learn the newest technologies.

Stay current with emerging technologies Short Cuts and Quick Reference Sheets are short, concise, focused content created to get you up-to-speed quickly on new and cutting-edge technologies.

From the Library of Shirong Chen

FREE Online Edition

Your purchase of The Merb Way includes access to a free online edition for 45 days through the Safari Books Online subscription service. Nearly every Addison-Wesley Professional book is available online through Safari Books Online, along with more than 5,000 other technical books and videos from publishers such as Cisco Press, Exam Cram, IBM Press, O’Reilly, Prentice Hall, Que, and Sams.

SAFARI BOOKS ONLINE allows you to search for a speciﬁc answer, cut and paste code, download chapters, and stay current with emerging technologies.

Activate your FREE Online Edition at www.informit.com/safarifree STEP 1: Enter the coupon code: AXOHAZG. STEP 2: New Safari users, complete the brief registration form. Safari subscribers, just log in.

If you have difﬁculty registering on Safari or accessing the online edition, please e-mail [email protected]

From the Library of Shirong Chen