The Rails Way

Considerations 83 What to Name Your Routes 83 Argument Sugar 84 A Little More Sugar with Your Sugar? 85 The Special Scope Method with_options 86 Conclusion 88 References 88 Chapter 4 REST, Resources, and Rails 89 REST in a Rather Small Nutshell 89 REST in Rails 91 Routing and CRUD 92 Resources and Representations 93 REST Resources and Rails 93 From Named Routes to REST Support 94 Reenter the HTTP Verb 96 The Standard RESTful Controller Actions 96 The PUT and DELETE Cheat 98 Singular and Plural RESTful Routes 98 The Special Pairs: new/create and edit/update 99 Singular Resource Routes 100 Nested Resources 101 Setting :path_prefix Explicitly 103 Setting :name_prefix Explicitly 103 Specifying RESTful Controllers Explicitly 105 All Together Now 105 Considerations 107 Deep Nesting? 108 RESTful Route Customizations 110 Extra Member Routes 110 Extra Collection Routes 111 Considerations 112 Controller-Only Resources 113 Different Representations of Resources 115 The respond_to Method 116 Formatted Named Routes 117 The RESTful Rails Action Set 117 Index 118 Show 121 Destroy 121 New and Create 123 Edit and Update 124 Conclusion 125 Reference 126 Chapter 5 Reflecting on Rails Routing 127 Examining Routes in the Application Console 127 Dumping Routes 128 Anatomy of a Route Object 129 Recognition and Generation in the Console 132 Named Routes in the Console 134 Testing Routes 135 The Routing Navigator Plugin 136 Conclusion 137 References 137 Chapter 6 Working with ActiveRecord 139 The Basics 140 Migrations 142 Creating Migrations 143 Naming Migrations 144 Migration Pitfalls 145 Migration API 146 Defining Columns 149 Macro-Style Methods 155 Relationship Declarations 155 Convention over Configuration 156 Pluralization 157 Setting Names Manually 158 Legacy Naming Schemes 159 Defining Attributes 160 Default Attribute Values 160 Serialized Attributes 162 CRUD: Creating, Reading, Updating, Deleting 163 Creating New ActiveRecord Instances 163 Reading ActiveRecord Objects 164 Reading and Writing Attributes 166 Accessing and Manipulating Attributes Before They Are Typecast 168 Reloading 169 Dynamic Attribute-Based Finders 169 Custom SQL Queries 171 The Query Cache 172 Updating 174 Updating by Condition 176 Updating a Particular Instance 176 Updating Specific Attributes 177 Convenience Updaters 177 Controlling Access to Attributes 178 Deleting and Destroying 178 Database Locking 179 Optimistic Locking 180 Pessimistic Locking 182 Considerations 183 Advanced Finding 183 Conditions 183 Ordering of Find Results 186 Limit and Offset 186 Select Option 187 From Option 188 Group By Option 188 Locking Option 189 Joining and Including Associations 189 Read Only 189 Connections to Multiple Databases in Different Models 189 Using the Database Connection Directly 191 The DatabaseStatements Module 191 Other Connection Methods 194 Other Configuration Options 196 Conclusion 197 References 198 Chapter 7 ActiveRecord Associations 199 The Association Hierarchy 199 One-to-Many Relationships 201 Adding Associated Objects to a Collection 203 AssociationCollection Methods 204 The belongs_to Association 207 Reloading the Association 208 Building and Creating Related Objects via the Association 208 belongs_to Options 209 The has_many Association 215 has_many Options 216 Proxy Methods 224 Many-to-Many Relationships 225 has_and_belongs_to_many 225 has_many :through 233 has_many :through Options 238 :source 238 One-to-One Relationships 241 has_one 241 has_one Options 244 :Unsaved Objects and Associations 246 One-to-One Associations 246 Collections 247 Association Extensions 247 The AssociationProxy Class 249 reload and reset 249 proxy_owner, proxy_reflection, and proxy_target 249 Conclusion 250 References 251 Chapter 8 ActiveRecord Validations 253 Finding Errors 253 The Simple Declarative Validations 254 validates_acceptance_of 254 validates_associated 255 validates_confirmation_of 256 validates_each 256 validates_inclusion_of and validates_exclusion_of 257 validates_existence_of 257 validates_format_of 258 validates_length_of 259 validates_numericality_of 260 validates_presence_of 261 validates_uniqueness_of 261 RecordInvalid 263 Common Validation Options 263 :allow_nil 263 :if 263 :message 263 :on 264 Conditional Validation 264 Usage and Considerations 265 Working with the Errors Object 266 Manipulating the Errors Collection 267 Checking for Errors 267 Custom Validation 268 Skipping Validations 269 Conclusion 270 Reference 270 Chapter 9 Advanced ActiveRecord 271 Callbacks 271 Callback Registration 272 Matched before/after Callbacks 274 Halting Execution 274 Callback Usages 275 Special Callbacks: after_initialize and after_find 278 Callback Classes 279 Observers 282 Naming Conventions 283 Registration of Observers 283 Timing 284 Single-Table Inheritance (STI) 284 Mapping Inheritance to the Database 286 STI Considerations 288 STI and Associations 288 Abstract Base Model Classes 291 Polymorphic has_many Relationships 292 In the Case of Models with Comments 293 Considerations about has_many 296 Modules for Reusing Common Behavior 296 A Review of Class Scope and Contexts 299 The included Callback 300 Modifying ActiveRecord Classes at Runtime 301 Considerations 303 Ruby and Domain-Specific Languages 303 Conclusion 305 References 305 Chapter 10 ActionView 307 ERb Basics 308 ERb Practice 308 Tightening Up ERb Output 310 Commenting Out ERb Delimiters 310 Conditional Output 311 RHTML? RXML? RJS? 311 Layouts and Templates 312 Yielding Content 313 Template Variables 315 Protecting the Integrity of Your View from User-Submitted Content 319 Partials 320 Simple Use Cases 321 Reuse of Partials 322 Shared Partials 323 Passing Variables to Partials 324 Render Collections 325 Logging 327 Caching 327 Caching in Development Mode? 328 Page Caching 328 Action Caching 328 Fragment Caching 330 Expiration of Cached Content 333 Automatic Cache Expiry with Sweepers 335 Cache Logging 337 Action Cache Plugin 337 Cache Storage 338 Conclusion 340 References 340 Chapter 11 All About Helpers 341 ActiveRecordHelper 342 Reporting Validation Errors 342 Automatic Form Creation 344 Customizing the Way Validation Errors Are Highlighted 346 AssetTagHelper 348 Head Helpers 348 For Plugins Only, Add Default JavaScript Includes 352 BenchmarkHelper 353 benchmark(message = "Benchmarking", level = :info) 353 CacheHelper 353 CaptureHelper 354 capture(&block) 354 content_for(name, &block) 354 DateHelper 355 The Date and Time Selection Helpers 355 The Individual Date and Time Select Helpers 356 Common Options for Date Selection Helpers 359 distance_in_time Methods with Complex Descriptive Names 359 DebugHelper 361 FormHelper 362 Creating Forms for ActiveRecord Models 362 How Form Helpers Get Their Values 370 FormOptionsHelper 371 Select Helpers 371 Option Helpers 373 FormTagHelper 378 check_box_tag(name, value = "1", checked = false, options = {}) 378 end_form_tag 378 file_field_tag(name, options = {}) 378 form_tag(url_for_options = {}, options = {}, *parameters_for_url, &block) 379 hidden_field_tag(name, value = nil, options = {}) 380 image_submit_tag(source, options = {}) 380 password_field_tag(name = "password", value = nil, options = {}) 380 radio_button_tag(name, value, checked = false, options = {}) 380 select_tag(name, option_tags = nil, options = {}) 380 start_form_tag 380 submit_tag(value = "Save changes", options = {}) 381 text_area_tag(name, content = nil, options = {}) 381 text_field_tag(name, value = nil, options = {}) 381 JavaScriptHelper 381 button_to_function(name, function, html_options={}, &block) 381 define_javascript_functions() 382 escape_javascript(javascript) 382 javascript_tag(content, html_options={}) 382 link_to_function(name, function, html_options={}, &block) 382 NumberHelper 383 human_size(size, precision=1) 383 number_to_currency(number, options = {}) 383 number_to_human_size(size, precision=1) 384 number_to_percentage(number, options = {}) 384 number_to_phone(number, options = {}) 385 number_with_delimiter(number, delimiter=",", separator=".") 385 number_with_precision(number, precision=3) 385 PaginationHelper 386 will_paginate 386 paginator 387 Paginating Find 388 RecordIdentificationHelper 388 dom_class(record_or_class, prefix = nil) 389 dom_id(record, prefix = nil) 389 partial_path(record_or_class) 389 RecordTagHelper 390 content_tag_for(tag_name, record, *args, &block) 390 div_for(record, *args, &block) 391 TagHelper 391 cdata_section(content) 391 content_tag(name, content = nil, options = nil, &block) 391 escape_once(html) 392 tag(name, options = nil, open = false) 392 TextHelper 393 auto_link(text, link = :all, href_options = {}, &block) 393 concat(string, binding) 393 cycle(first_value, *values) 394 excerpt(text, phrase, radius = 100, excerpt_string = "...") 395 highlight(text, phrases, highlighter = '\1') 395 markdown(text) 396 pluralize(count, singular, plural = nil) 396 reset_cycle(name = "default") 397 sanitize(html) 397 simple_format(text) 398 strip_links(text) 398 strip_tags(html) 398 textilize(text) 399 textilize_without_paragraph(text) 399 truncate(text, length = 30, truncate_string = "...") 399 word_wrap(text, line_width = 80) 400 UrlHelper 400 button_to(name, options = {}, html_options = {}) 400 current_page?(options) 401 link_to(name, options = {}, html_options = nil) 401 link_to_if(condition, name, options = {}, html_options = {}, &block) 403 link_to_unless(condition, name, options = {}, html_options = {}, &block) 403 link_to_unless_current(name, options = {}, html_options = {}, &block) 403 mail_to(email_address, name = nil, html_options = {}) 404 url_for(options = {}) 405 Relying on Named Routes 406 Writing Your Own Helpers 407 Small Optimizations: The Title Helper 407 Encapsulating View Logic: The photo_for Helper 408 Smart View: The breadcrumbs Helper 409 Wrapping and Generalizing Partials 410 A tiles Helper 410 Generalizing Partials 414 Conclusion 417 References 417 Chapter 12 Ajax on Rails 419 Prototype 420 FireBug 421 The Prototype API 421 Top-Level Functions 422 Class 424 Extensions to JavaScript's Object Class 425 Extensions to JavaScript's Array Class 426 Extensions to the document Object 428 Extensions to the Event Class 428 Extensions to JavaScript's Function Class 430 Extensions to JavaScript's Number Class 432 Extensions to JavaScript's String class 433 string.dasherize() 434 string.escapeHTML() and string.unescapeHTML() 434 string.evalScripts() and string.extractScripts() 434 string.gsub(pattern, replacement) and string.sub(pattern, replacement, count) 434 string.scan(pattern, iterator) 434 string.strip() 435 string.stripScripts() and string.stripTags() 435 string.parseQuery() and string.toQueryParams() 435 string.toArray() 435 string.truncate(length, truncationString) 435 string.underscore() 436 The Ajax Object 436 Ajax.Responders 437 Enumerable 437 Hash 443 ObjectRange 444 The Prototype Object 445 The PrototypeHelper Module 445 link_to_remote 445 remote_form_for 449 periodically_call_remote 451 observe_field 451 observe_form 453 RJS--Writing Javascript in Ruby 453 RJS Templates 455 "(javascript) 456 [](id) 457 alert(message) 457 call(function, *arguments, &block) 457 delay(seconds = 1) { ... } 458 draggable(id, options = {}) 458 drop_receiving(id, options = {}) 458 hide(*ids) 458 insert_html(position, id, *options_for_render) 458 literal(code) 459 redirect_to(location) 459 remove(*ids) 459 replace(id, *options_for_render) 460 replace_html(id, *options_for_render) 460 select(pattern) 460 show(*ids) 460 sortable(id, options = {}) 460 toggle(*ids) 461 visual_effect(name, id = nil, options = {}) 461 JSON 461 Drag and Drop 463 00_5619_fm.qxd 10/25/07 4:05 PM Page xxxii Sortable 465 Autocompleter 466 In-Place Editors 467 Conclusion 467 References 468 Chapter 13 Session Management 469 What to Store in the Session 470 The Current User 470 Session Use Guidelines 470 Session Options 471 Disabling Sessions for Robots 472 Selectively Enabling Sessions 473 Secure Sessions 473 Storage Mechanisms 473 ActiveRecord SessionStore 473 PStore (File-Based) 474 DRb Session Storage 475 memcache Session Storage 475 The Controversial CookieStore 476 Timing Out and Session Life Cycle 478 Session Timeout Plugin for Rails 478 Tracking Active Sessions 479 Enhanced Session Security 480 Cleaning Up Old Sessions 481 Cookies 481 Reading and Writing Cookies 482 Conclusion 483 References 483 Chapter 14 Login and Authentication 485 Acts as Authenticated 486 Installation and Setup 486 The User Model 487 The Account Controller 496 Login from Cookie 498 The Current User 499 Logging In During Testing 501 Conclusion 502 References 502 Chapter 15 XML and ActiveResource 503 The to_xml Method 503 Customizing to_xml Output 505 Associations and to_xml 507 Advanced to_xml 508 Dynamic Runtime Attributes 509 Overriding to_xml 510 Learning from Array's to_xml Method 510 The XML Builder 513 Parsing XML 515 Turning XML into Hashes 515 XmlSimple 516 Typecasting 518 ActiveResource 519 Find 519 Create 522 Update 524 Delete 524 Headers 526 Customizing 527 Hash Forms 528 Conclusion 529 Chapter 16 ActionMailer 531 Setup 531 Mailer Models 532 Preparing Outbound Email Messages 533 HTML Email Messages 536 Multipart Messages 537 File Attachments 539 Actually Sending an Email 540 Receiving E-Mails 540 TMail::Mail API Reference 541 Handling Attachments 543 Configuration 543 Conclusion 544 References 544 Chapter 17 Testing 545 Rails Testing Terminology 546 So Much for Isolation... 547 Rails Mocks? 548 Real Mocks and Stubs 549 Integration Tests 550 Dealing with the Confusion 551 Test::Unit 552 Running Tests 553 Fixtures 554 CSV Fixtures 555 Accessing Fixture Records from Tests 556 Dynamic Fixture Data 556 Using Fixture Data in Development Mode 557 Generating Fixtures from Development Data 558 Fixtures Options 559 Everybody Hates Fixtures 560 Fixtures Really Aren't That Bad 562 Assertions 562 Basic Assertions 562 Rails Assertions 566 One Assertion per Test Method 566 Testing Models with Unit Tests 568 Model Testing Basics 568 Deciding What to Test 570 Testing Controllers with Functional Tests 570 Structure and Setup 570 Functional Test Methods 571 Common Assertions 572 Testing Views with Functional Tests 576 assert_select(selector, [*values, equality, message, &block]) 577 assert_select(element, selector, [*values, equality, message, &block]) 577 Optional Block Parameter 577 Selector Reference 578 Equality Tests 580 Testing RJS Behavior 581 Other Selection Methods 582 Testing Routing Rules 582 Rails Integration Tests 584 Basics 584 The Integration Test API 585 Working with Sessions 586 Rake Tasks Related to Testing 587 Acceptance Tests 588 Acceptance Test First? 588 Selenium 589 Basics 589 Getting Started 591 RSelenese 592 Conclusion 593 References 594 Chapter 18 RSpec on Rails 597 Introduction to RSpec 597 Should and Expectations 598 Predicates 599 Custom Expectation Matchers 601 Multiple Examples per Behavior 603 Shared Behaviors 604 RSpec's Mocks and Stubs 607 Running Specs 610 Installing RSpec and the RSpec on Rails Plugin 613 The RSpec on Rails Plugin 613 Generators 614 Model Specs 614 Controller Specs 617 View Specs 621 Helper Specs 623 Scaffolding 623 RSpec Tools 624 Autotest 624 RCov 624 Conclusion 625 References 626 Chapter 19 Extending Rails with Plugins 627 Managing Plugins 628 Reusing Code 628 T he Plugin Script 629 Subversion and script/plugin 633 Using Piston 636 Installation 636 Importing a Vendor Library 637 Converting Existing Vendor Libraries 638 Updating 638 Locking and Unlocking Revisions 639 Piston Properties 639 Writing Your Own Plugins 640 The init.rb Hook 640 The lib Directory 642 Extending Rails Classes 643 The README and MIT-LICENSE File 644 The install.rb and uninstall.rb Files 645 Custom Rake Tasks 647 The Plugin's Rakefile 648 Testing Plugins 649 Conclusion 649 References 650 Chapter 20 Rails Production Configurations 651 A Brief History of Rails In Production 652 Some Basic Prerequisites 652 The Stack Checklist 654 Server and Network Environment 655 Web Tier 656 Application Tier 656 Database Tier 656 Monitoring 657 Version Control 657 Installations 657 Ruby 658 RubyGems 658 Rails 659 Mongrel 659 Mongrel Cluster 659 Nginx 659 Subversion 660 MySQL 660 Monit 661 Capistrano 661 Configurations 661 Configuring Mongrel Cluster 662 Configuring Nginx 663 Configuring Monit 667 Configuring Capistrano 670 Configuring init Scripts 670 Nginx init Script 670 Mongrel init Script 672 Monit Configuration 673 Deployment and Launch 675 Other Production Stack Considerations 675 Redundancy and Failover 676 Caching 676 Performance and Scalability 676 Security 677 Maintainability 678 Conclusion 678 References 679 Chapter 21 Capistrano 681 Overview of Capistrano 681 Terminology 682 The Basics 682 What Do I Need to Do to Use Capistrano? 682 What Does Capistrano Expect? 683 What Has Capistrano Done and What Hasn't It? 684 Getting Started 684 Installation 684 "Capify" Your Rails Application 685 Configuring the Deployment 687 A Little Spin, Please! 688 Set Up the Deployment Machine 689 Deploy! 691 Overriding Capistrano Assumptions 691 Using a Remote User Account 691 Customizing the SCM System Used by Capistrano 692 Working without SCM Access from the Deployment Machine 692 What If I Don't Store database.yml in My SCM Repository? 693 What If My Migrations Won't Run from 0 to 100? 696 Useful Capistrano Recipes 696 Variables and Their Scope 696 Exercise #1: Staging 698 Exercise #2: Managing Other Services 701 Multiserver Deployments 702 Transactions 703 Proxied Access to Deployment Machines 705 Conclusion 706 References 706 Chapter 22 Background Processing 707 script/runner 708 Getting Started 708 Usage Notes 709 script/runner Considerations 710 DRb 710 A Simple DRb Server 711 Using DRb from Rails 711 DRb Considerations 712 Resources 713 BackgrounDRb 713 Getting Started 713 Configuration 714 Understanding BackgrounDRb 715 Using the MiddleMan 715 Caveats 717 BackGrounDRb Considerations 718 Daemons 719 Usage 719 Introducing Threads 720 Daemon Considerations 722 Conclusion 722 References 722 Appendix A ActiveSupport API Reference 723 Appendix B Rails Essentials 805 Afterword What Is the Rails Way (To You)? 815