1

Daniel Kehoe

Learn Ruby on Rails

Ruby on Rails tutorial 1.b13 (prerelease) 13 September 2013

Contents
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28.

Introduction ................................................. 3 Concepts........................................................ 9 Get Help When You Need It ................. 15 Plan Your Product .................................... 18 Manage Your Project ............................... 25 Accounts You May Need ....................... 27 Get Started .................................................. 30 Create the Application ............................ 38 The Parking Structure ............................. 46 Time Travel with Git ............................... 49 Gems ............................................................ 59 Configure .................................................... 68 Static Pages and Routing........................ 73 Request and Response ............................ 76 Dynamic Home Page .............................. 84 Troubleshoot .............................................. 94 Just Enough Ruby .................................. 105 Layout and Views .................................. 126 Stylesheets and Themes ....................... 141 Add Pages................................................. 149 Contact Form ........................................... 153 Spreadsheet Connection ....................... 172 Send Mail .................................................. 178 Mailing List .............................................. 185 Deploy ....................................................... 194 Analytics ................................................... 205 Rails Challenges...................................... 212 Comments ................................................ 217

Chapter 1

Introduction
Welcome. This tutorial is a first step on your path to learn Ruby on Rails. Youll learn key concepts so youll have a solid foundation for continued study. Youll build a working web application so youll gain hands-on experience. Along the way, youll practice the techniques used by professional Rails developers and youll understand why Rails has become a popular choice for web development.

Is It for You?
You dont need to be a programmer to succeed with this tutorial. Youll get comfortable with the Ruby programming language and the Unix command line interface as you build a Rails application. This tutorial is ideal if you are: a student a startup founder making a career change Does this sound like you? Readers who work in social media or graphic design say this tutorial is a good way to get introduced to programming. Others who previously built simple websites using HTML, or used applications such as WordPress, found they could easily progress to building websites with Rails. Programmers with experience in languages such as PHP or Java found this tutorial to be a good way to get started with the Rails framework. On the other hand, if youve never encountered HTML, CSS, or JavaScript, it is best to start elsewhere with an Introduction to Web Design course or online tutorial. There are thousands of such tutorials; I especially like the RailsBridge Frontend Curriculum. The Odin Project attempts to provide a complete curriculum for budding web developers.

Warnings
This is two books in one. At the core is a hands-on tutorial that will lead you through the code needed to build a real-world web application. I thoroughly explain the code youll need to write a Rails application. Before you start coding, I explain the culture and practices of the Rails community. If youre in a hurry to start coding, jump right now to Chapter 7, Get Started. But I urge you to read the preliminary chapters first. Theyll give you the context you need to become a skilled Rails developer. Many readers have told me the concepts at the beginning of the book provide a grounding they havent found in any other tutorial. The chapters are densely packed with links to background reading. If you click every link, youll be a well-informed student, but you may never finish the book! Its up to you to master your curiosity. Follow the links only when you want to dive deeper. There is rich satisfaction in building something and making it run. But programming can be frustrating and Rails isnt easy for beginners. Before you get to the reward, youll encounter setbacks. If at times youre ready to quit, jump to the next-to-last chapter in the book. It is titled Rails Challenges and it describes many of the problems learners encounter. Ive written it to address your concerns when learning Rails becomes difficult and frustrating.

What To Expect
This book is the foundation for a series of tutorials that accompany example applications from the RailsApps project.

RailsApps Examples and Tutorials

Tutorials from @rails_apps take you on a guided path starting with absolute basics (this tutorial). Youll progress to intermediate-level tutorials and soon be using the RailsApps indepth guides for professional Rails developers. It is important to feel satisfaction and accomplishment as you learn. Thats why each tutorial introduces Rails in stages. With each tutorial you will build a real-world Rails application. The finished product confirms your accomplishment; youll feel genuine satisfaction as you deploy your Rails application. Hands-on learning with real Rails applications is the key to absorbing and retaining knowledge. The applications youll build in the tutorials are not classroom exercises. The primary purpose of the RailsApps project is to provide starter applications for Rails developers. Youll build real applications that you can customize and adapt for your startup, at your job, or for clients. Hundreds of developers use the RailsApps project example applications, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal reference implementation so you can stay up to date. Maintenance and development of the RailsApps applications is supported by subscriptions to the RailsApps tutorials.

Next Steps
When youve completed this tutorial, you will be ready for more advanced self-study, including other tutorials from the RailsApps project, textbook introductions to Rails, or workshops and developer bootcamps that provide intensive training in Ruby on Rails. Other curriculums often skip the basics. With this tutorial youll have a solid grounding in key concepts; you wont feel overwhelmed or frustrated as you continue your studies. This tutorial is good preparation for: advanced tutorials in the RailsApps Tutorials series textbooks such as Michael Hartls Ruby on Rails Tutorial introductory workshops from RailsBridge or Rails Girls intensive training such as DevBootcamp or General Assembly

We are blessed with many textbooks, workshops, and classroom programs that teach Ruby on Rails. I believe this book is unique in covering the basics while introducing the tools and techniques of professional Rails development.

The Application
Well build a basic web application that can be used by a typical small business. The website will include a home page, about page, contact form, and option to sign up for a mailing list. Youll also learn how to collect data from a form and save it to a spreadsheet on Google Drive. Youll find the complete learn-rails application on GitHub. It is a working application that is maintained by a team of experienced developers so you can always check the reference implementation if you have problems.

A Note to Reviewers and Teachers

This book approaches the subject differently than most introductions to Rails. It introduces concepts of product planning, project management, and website analytics to place development within a larger context of product development and marketing. In introducing Rails, rather than show the student how to use scaffolding, it introduces the model-viewcontroller design pattern by creating the components manually. The tutorial recommends test-driven development, but doesnt show it, simply because Ive found TDD cant be adequately covered in a basic introduction. Lastly, though every other Rails tutorial shows how to use a database, this book doesnt, because I want the book to be a short introduction and I believe the basic principles of a web application stand out more clearly without adding a database to the application. Im already anticipating that Rails database applications could be covered in a second book: Learn Ruby on Rails, Part Two. Though this tutorial is not a typical Rails introduction, I hope youll agree that it does a good job in preparing Rails beginners for continued study, whether it is developer bootcamp or more advanced books.

Note to Editors
This is a preliminary (prerelease) version of the tutorial. Youve received a PDF version of the book. If youve volunteered to offer feedback, you can email it to me at [email protected]. The best way to give me your feedback is to mark up the PDF file with your suggestions.

On the Mac, the Preview application allows you to annotate the PDF file with the Edit toolbar. Click the pencil icon to reveal or hide the Edit toolbar. The Edit toolbar has tools for a thought balloon and other comment devices. After youve made your suggestions, email the PDF file to me at [email protected]. You dont have to finish the entire book before sending me suggestions.

About the Book

Weve got at least four top-notch books that teach Rails. Yet, with the increasing popularity of Rails, I believe there is a need for a tutorial that is geared to absolute beginners and also introduces the practices of real-world Rails development. Many people who are now coming to Rails dont have a background as web application developers. They need to learn fundamental concepts of web development and, at the same time, learn the techniques used by professional Rails developers in the workplace.

Student and Peer Editors

Depending on the time you have available, you can improve the book in any of these ways: User testing Follow the tutorial instructions and identify errors or lack of clarity Report typos and minor errors Your eyes are no doubt sharper than mine! Copyediting Suggest ways to rewrite sentences or paragraphs for improved clarity Technical comments Identify egregious errors, bad ideas, or poor practices Book report Write a few paragraphs of a book report as if you were a reviewer on Amazon, highlighting virtues and flaws Any feedback is appreciated, and will help the readers, even if your time is limited.

Technical Editors
If youve agreed to do a full technical review, here are the standard questions that guide a chapter review: What would you want to see more of in the chapter? What were the highlights? What would you like to see less of in the chapter? What could the author do to make the chapter more interesting?

What important topics does the author leave uncovered, if any? Does the chapter leave you asking nagging questions? What do you think would be the next logical topic to cover after this one? Does the reader learn to do enough in the chapter? What else should the chapter teach readers to do? Does the author explain the main important concepts clearly? Are there other important concepts and facts about the topic that should be covered in the chapter? Does the chapter provide necessary reference information? What other reference information would you expect to find in the chapter? This section, Note to Editors, concludes here and will not appear in the final release.

Chapter 2

Concepts
This chapter provides the background, or big picture, you will need to understand Rails. This chapter is excerpted from an in-depth article What is Ruby on Rails? For a deeper understanding of Rails, including background on the guiding principles of Rails, and reasons for its popularity, read the article for a complete introduction. Here are the key concepts youll need to know before you try to use Rails.

How the Web Works

We start with absolute basics, as promised. When you visit a website on the Internet you use a web browser such as Safari, Chrome, Firefox, or Internet Explorer. Web browsers are applications (software programs) that work by reading files. Compare a word processing program with a web browser. Both word processing programs and web browsers read files. Microsoft Word reads files that are stored on your computer to display documents. A web browser retrieves files from remote computers called servers to display web pages. Knowing that everything comes from files will help you build a web application. A web browser uses four kinds of files to display web pages: HTML structure (layout) and content (text) CSS stylesheets to set visual appearance JavaScript programming to alter the page Images At a minimum, a web page requires an HTML file. If a web browser receives just an HTML file, it will display text, with default styles applied by the browser. If the page is always the same, every time it is displayed by the web browser, we say it is static. Webmasters dont need software such as Rails to deliver static documents; they just create files for delivery by an ordinary web server program.

10

Static websites are ideal for particle physics papers (which was the original use of the World Wide Web). But most sites on the web, especially those that allow a user to sign in, post comments, or order products and services, generate web pages dynamically. Dynamic websites often combine web pages with information from a database. A database stores information such as a users name, comments, Facebook likes, advertisements, or any other repetitive, structured data. A database query can provide a selection of data that customizes a webpage for a particular user or changes the web page so it varies with each visit. Dynamic websites use a programming language such as Ruby to assemble HTML, CSS, and JavaScript files on the fly from component files or a database. A software program written in Ruby and organized using the Rails development framework is a Rails web application. A web server program that runs Rails applications to generate dynamic web pages is an application server (but usually we just call it a web server). Software such as Rails can access a database, combining the results of a database query with static content to be delivered to a web browser as HTML, CSS, and JavaScript files. Keep in mind that the web browser only receives ordinary HTML, CSS, and JavaScript files; the files themselves are assembled dynamically by the Rails application running on the server. Even if you are not going to use a database, there are other good reasons to generate a website using a programming language. For example, if you are creating several web pages, it often makes sense to assemble an HTML file from smaller components. For example, you might make a small file that will be included on every page to make a footer (Rails calls these partials). Just as importantly, if you are using Rails, you can add features to your website with code that has been developed and tested by other people so you dont have to build everything yourself. The widespread practice of sharing code with other developers for free, and collaborating with strangers to build applications or tools, is known as open source software development. Rails is at the heart of a vibrant open source development community, which means you leverage the work of tens of thousands of skilled developers when you build a Rails application. When Ruby code is packaged up for others to share, the package is called a gem. The name is apt because shared code is valuable. Ruby is a programming language; Rails is a development framework. That means Rails is a set of structures and conventions for building a web application using the Ruby language. Rails is also a library or collection of gems that developers use as the core of any Rails web application. By using Rails, you get well-tested code that implements many of the mostneeded features of a dynamic website. With Rails, you will be using shared standard practices that make it easier to collaborate with others and maintain your application. As an example, consider the code that is used to access a database. Using Ruby without the Rails framework, or using another language such as PHP, you could mix the complex programming code that accesses the database with the code that generates HTML. With the insight of years of developers collective experience in maintaining and debugging such code, Rails provides a library of code that segregates

11

database access from the code that displays pages, enforcing separation of concerns, and making more modular, maintainable programs. In a nutshell, thats how the web works, and why Rails is useful. For a history of Rails, and an explanation of why it is popular, see the article What is Ruby on Rails?

What is Rails?
So far, Ive defined Rails in two ways: as structures and conventions for building a web application, and as a library or collection of code. To really understand Rails, and succeed in building Rails applications, we need to consider Rails from six other perspectives. Like six blind men encountering an elephant, it can be difficult to understand Rails unless you look at it from multiple points of view. Here are six different ways of looking at Rails, summarized from the article What is Ruby on Rails? From the perspective of the web browser, Rails is simply a program that generates HTML, CSS, and JavaScript files. These files are generated dynamically. You cant see the files on the server side but you can view these files by using the web developer tools that are built in to every browser. Later youll examine these files when you learn to troubleshoot a Rails application. From the perspective of a programmer, Rails is a set of files organized with a specific structure. The structure is the same for every Rails application; this commonality is what makes it easy to collaborate with other Rails developers. We use text editors to edit these files to make a web application. From the perspective of a software architect, Rails is a structure of abstractions that enable programmers to collaborate and organize their code. Thinking in abstractions means we group things in categories and analyze relationships. Conceptual categories and relationships can be made real in code. Software programs are built of concepts made real that are the moving parts of a software machine. To a software architect, classes are the basic parts of a software machine. A class can represent something in the physical world as a collection of various attributes or properties (for example, a User with a name, password, and email address). Or a class can describe another abstraction, such as a Number, with attributes such as quantity, and behavior, such as can be added and subtracted. Youll get a better grasp of classes in the chapter, Just Enough Ruby. To a software architect, Rails is a pre-defined set of classes that are organized into a higher level of abstraction known as an API, or application programming interface. The Rails API is organized to conform to certain widely known software design patterns. Youll become familiar with these abstractions as you build a Rails application. Later in the tutorial, well

12

learn about the modelviewcontroller design pattern. As a beginner, you will see the MVC design pattern reflected in the file structure of a Rails application. We can look at Rails from the perspective of a gem hunter. Rails is popular because developers have written and shared many software libraries (RubyGems, or gems) that provide useful features for building websites. We can think of a Rails application as a collection of gems that provide basic functionality, plus custom code that adds unique features for a particular website. Some gems are required by every Rails application. For example, database adaptors enable Rails to connect to databases. Other gems are used to make development easier, for example, gems for testing that help programmers find bugs. Still other gems add functionality to the website, such as gems for logging in users or processing credit cards. Knowing what gems to use, and why, is an important aspect of learning Rails. This tutorial will show you how to build a web application using some of the most commonly used gems. We can also look at Rails from the perspective of a time traveler in order to understand the importance of software version control. Specifically, we use the Git revision control system to record a series of snapshots of your projects filesystem. Git makes it easy to back up and recover files; more importantly, Git lets you make exploratory changes, trying out code you may decide to discard, without disturbing work youve done earlier. You can use Git with GitHub, a popular social coding website, for remote backup of your projects and community collaboration. Git can keep multiple versions (branches) of your local code in sync with a remote GitHub repository, making it possible to collaborate with others on open source or proprietary projects. Strictly speaking, Git and GitHub are not part of Rails (they are tools that can be used on any development project). And there are several other version control systems that are used in open source development. But a professional Rails developer uses Git and GitHub constantly on any real-world Rails project. Rails and the gems that go into a complex web application would not exist without Git and GitHub. Finally, we can consider a Rails application from the perspective of a tester. Software testing is part of Rails culture; Rails is the first web development platform to make testing an integrated part of development. Before Rails, automated testing was rarely part of web development. A web application would be tested by users and (maybe) a QA team. If automated tests were used, the tests were often written after the web application was largely complete. Rails introduced the discipline of Test-Driven Development (TDD) to the wider web development community. With TDD, tests are written before any implementation coding. It may seem odd to write tests first, but for a skilled TDD practitioner, it brings coherence to the programming process. First, the developer will give thought to what needs to be accomplished and think through alternatives and edge cases. Second, the developer will have complete test coverage for the project. With good test coverage, it is easier to refactor, rearranging code to be more elegant or efficient. Running a test suite after refactoring provides assurance that nothing inadvertently broke after the changes. TDD is seen as a necessary skill of an experienced Rails developer. Because this is a tutorial for beginners, it will not introduce you to techniques of Test-Driven Development. As you work through more advanced tutorials from the RailsApps project, youll be introduced to Test-Driven Development.

13

Stacks
To understand Rails from the perspective of a professional Rails developer, youll need to grasp the idea of a technology stack and recognize that Rails can have more than one stack. A technology stack is a set of technologies or software libraries that are used to develop an application or deliver web pages. Stack is a term that is used loosely and descriptively. There is no organization that sets the rules about what goes into a stack. As a technologist, your choice of stack reflects your experience, values, and personal preference, just like religion or favorite beverage. For example, Mark Zuckerberg developed Facebook in 2004 using the LAMP application stack: Linux (operating system) Apache (web server) MySQL (database) PHP (programming language) For this tutorial, your application stack will be: Mac OS X, Linux, or Windows WEBrick (web server) SQLite (database) Ruby on Rails (language and framework) Sometimes when we talk about a stack, we only care about part of a larger stack. For example, a Rails stack includes the gems we choose to add features to a website or make development easier. When we select the gems well use for a Rails application, were choosing a stack. Sometimes the choice of components is driven by the requirements of an application. At other times, the stack is a matter of personal preference. Just as craftsmen and aficionados debate the merits of favorite tools and techniques in any profession, Rails developers avidly dispute whats the best Rails stack for development. The company 37signals, where the creator of Rails works, uses this Rails stack: ERB for view templates MySQL for databases MiniTest for testing It is not important (at this point) to know what the acronyms mean (well learn later).

14

Another stack is more popular among Rails developers: Haml for view templates PostgreSQL for databases Rspec for testing Well learn later what the terms mean. For now, just recognize that parts of the Rails framework can be swapped out, just like making substitutions when you order from a menu at a restaurant. You can learn much about Rails by following the experts debates about the merits of a favorite stack. The debates are a source of much innovation and improvement for the Rails framework. In the end, the power of the crowd prevails; usually the best components in the Rails stack are the most popular. The proliferation of choices for the Rails stack can make learning difficult, particularly because the components used by many leading Rails developers are not the components used in many beginner tutorials. In this tutorial, we stick to solid ground where there is no debate. In more advanced tutorials, well explore stack choices and choose components that are most often used by professional developers.

15

Chapter 3

Get Help When You Need It

Im often asked, Wheres the Rails manual? There isnt one. No single document tells you how to use Rails. Instead, theres a wealth of documentation that describes various aspects of Rails. You wont need any other documentation to complete this tutorial but Id like to suggest some resources that will be helpful as you go deeper in your study of Rails.

Getting Help
First of all, what to do when you get stuck? Google it, of course. But heres a trick to keep in mind. Google has options under Search tools to show only recent results from the past year. Use it to filter out stale advice that pertains only to older versions of Rails. Stack Overflow is as important as Google for finding answers to programming problems. Stack Overflow answers are often included in Google search results, but you can go directly to Stack Overflow to search for answers to your questions. Like Google, answers from Stack Overflow are helpful if you check carefully to make sure the answers are recent. Also be sure to compare answers to similar questions; the most popular answer is not always the correct answer to your particular problem. Rails Hotline is a free telephone hotline for Rails questions staffed by volunteers. Youll need to carefully think about and describe your problem but sometimes theres no better help than a live expert.

References
In addition to the resources listed here, the RailsApps project offers a list of top resources for Ruby and Rails, including books and blogs. If you feel overwhelmed by all the links, remember that you can use this book to build the tutorial application without any additional resources. Right now, its important to know additional help is available when you need it. Here are suggestions for the most important additional references.

16

RailsGuides
The Rails Guides are Railss official documentation, written for intermediate-level developers who already have experience writing web applications. The Rails Guides are an excellent reference if you want to check the correct syntax for Rails code. Youll be able to use the Rails Guides after completing this tutorial.

Cheatsheets
Tobias Pfeiffer has created a useful Rails Beginner Cheat Sheet that provides a good overview of Rails syntax and commands.

API Documentation
The API documentation for Ruby and Rails shows every class and method. These are extremely technical documents (the only thing more technical is reading the source code itself). The documents offer very little help for beginners, as each class and method is considered in isolation, but there are times when checking the API documentation is the only way to know for certain how something works. Rails Documentation official API docs Rails Searchable API Doc alternative interface for the API docs apidock.com/rails Rails API docs with usage notes apidock.com/ruby Ruby API docs with usage notes

Staying Up-to-Date
Rails changes frequently and its community is very active. Changes to Rails, expert blog articles, and new gems can impact your projects, even if you dont work full-time as a Rails developer. Consequently, I urge you to stay up-to-date with news from the community. The best source of news is Peter Coopers Ruby Weekly email newsletter. It arrives each Thursday and it is free. For more frequent news, check Peter Coopers RubyFlow site which lists new blog posts from Rails developers each day. If you like podcasts, check out Ruby Rogues and Envy Labss Ruby5.

Meetups, Hack Nights, and Workshops

Id like to urge you to find ways you can work with others who are learning Rails. Peer support is really important when you face a challenge and want to overcome obstacles.

17

Most large urban areas have meetups or user group meetings for Rails developers. Try Meetup.com or google ruby rails (my city). The community of Rails developers is friendly and eager to help beginners. If you are near a Rails meetup, it is really worthwhile to connect to other developers for help and support. You may find a group that meets weekly for beginners who study together. Local user groups often sponsor hack nights or hackathons which can be evening or weekend collaborative coding sessions. You dont have to be an expert. Beginners are welcome. You can bring your own project which can be as simple as completing a tutorial. You will likely find a study partner at your level or a mentor to help you learn. If you are a woman learning Rails, look for one of the free workshops from RailsBridge or Rails Girls. These are not exclusively for women; everyone considered a minority in the tech professions is encouraged to participate; and men are included when invited by a woman colleague or friend.

Pair Programming
Learning to code is challenging, especially if you do it alone. Make it social and youll learn faster and have more fun. Theres a popular trend in the workplace for programmers to work side-by-side on the same code, sharing a keyboard and screen. Its effective, both to increase productivity and to share knowledge, and many coders love it. When programmers are not in the same office, they share a screen remotely and communicate with video chat. Look for opportunities to pair program. Its the best way to learn to code, even if your pairing partner is only another beginner. Learn more about pair programming on the site pairprogramwith.me and find a pairing partner at rubypair.com or letspair.net. Lets look at some social aspects of product development before we get into building an application.

18

Chapter 4

Plan Your Product

Tutorials from other authors focus only on coding. But Rails developers do more than code. Software development is a process that begins with planning and ends with analysis and review. Coding, testing, and deployment is at the core but youll need to learn about the entire process to succeed professionally. Thats why we look at product planning and project management. For this beginning tutorial, well introduce concepts about product planning and project management that you will encounter as a Rails developer. If you are interested in diving deeper, see the article Rails and Product Planning.

Product Owner
On your project, who is the product owner? The product owner is the voice of the customer, making sure that the team creates value for the users. If you are a solo operator, you are the one who will decide what features and functionality will be included in your application. But if youre part of a team, either in a startup, as a consultant, or in a corporate setting, it may not be clear who has responsibility for looking at the application from the point of view of the application user. Someone must decide which features and functionality are essential and which must be left out. We call this managing scope and combating feature creep. Its important to assign a product owner. Without a product owner in charge, tasks remain vague and developers have difficulty making progress. In large organizations, a product owner may be a product manager or a project manager. A product owner usually is not a management executive (though there will likely be an executive sponsor). Everyone on the team including management, developers, and stakeholders should agree to designate a product owner and give that person authority to define features and requirements.

User Stories
A product owners principal tool for product planning is the user story.

19

In the past, when software engineering primarily served government or large corporations, product planning started with requirements gathering defined as use cases, and culminated in a requirements specification. User stories are a faster, more flexible approach to product planning. User stories are a way to discuss and describe the requirements for a software application. The process of writing user stories helps a product owner identify all the features that are needed for an application. Breaking down the applications functionality into discrete user stories helps organize the work and track progress toward completion. User stories are often expressed in the following format:
As a <role> I want <goal> In order to <benefit>

Here is an example:
*Join Mailing List* As a visitor to the website I want to join a mailing list In order to receive news and announcements

A typical application has dozens of user stories, from basic sign-in requirements to the particular functionality that makes the application unique. You dont need special software to write user stories. Just use index cards or a Word document. In the next chapter, well see how you can enter user stories as tasks in a to-do list. Heres a screenshot from Lowdown, a web application that developers use for organizing user stories.

Just like Rails provides a structure for building a web application, user stories provide a structure for organizing your product plan.

20

Wireframes and Mockups

Often, before writing user stories, a product owner will make rough sketches of various web pages. Sketching is a phase where you try out ideas to clarify your vision for the application. Sketching can lead to a wireframe or a mockup. These terms are often used interchangeably but there are differences in meaning. A wireframe is a drawing showing all functional elements of a web page. It should not depict a proposed graphic design for a website, rather it should be a diagram of a web page, without color or graphics. A mockup adds graphic design to a wireframe; including branding devices, color, and placeholder content. A mockup gives an impression of the websites personality as well as proposed functionality. One of the most popular tools for creating wireframes is Balsamiq Mockups (despite the name, it produces wireframes, not mockups). There are dozens of others listed in the article Rails and Product Planning. As a product owner, writing user stories or sketching wireframes will help you refine product requirements. Some people like a visual approach with wireframes; others prefer words and narrative. Either approach will work; both are good.

Graphic Design
Very few people have skills as both a visual designer and a programmer. The tools are different; graphic designers typically use Adobe Photoshop, though web-savvy designers often create designs directly in HTML and CSS, while developers write code. If youre lucky, you will work with a skilled graphic designer as you build your web application. If you are very lucky, you may work with someone who is a user experience (UX) designer or interaction designer (IxD). Interaction design is a demanding, sophisticated discipline that requires the mindset of an anthropologist and the eye of a visual artist to find not just the most pleasing, but the most effective visual design for an application user interface. You can find interaction designers discussing their concerns on the IxDA website, including the differences between interaction design and UX design. If youre working with a graphic designer you might collaborate on a moodboard or a design brief to define the look and feel of your application. If the designer works in Photoshop, youll face the challenge of converting design layouts from Photoshop to HTML and CSS. There are service firms that do this for a fee but obviously its easier to work with a designer who can implement a layout directly in HTML and CSS. Rails can be particularly challenging when it comes to integrating graphic design with code. Rails uses a hybrid of HTML markup mixed with Ruby programming code in its view files

21

(depending on the stack youve selected, the view files can use ERB, Haml, or other syntaxes for mixing HTML and Ruby). Few designers are comfortable with Ruby code mixed with HTML so you may end up doing integration yourself. If you dont have a skilled graphic designer available to help, you can use Twitter Bootstrap or other front-end frameworks such as Zurb Foundation to quickly add an attractive design to your application. You can use DivShot, a drag-and-drop interface builder that uses Twitter Bootstrap for layout and exports HTML and CSS code ready to integrate with your Rails application. DivShot was built by an experienced Rails developer; Bootstrap Designer, Bootply, and Jetstrap are similar tools.

Software Development Process

Product planning is the initial phase of a larger software development process. You can approach this casually, and start coding with curiosity and ambition, finding your own best way to the end product, by trial and error. Most hobbyist and student developers need no other approach. When money or reputation is at stake, casual approaches to software development are risky. Compared to other forms of engineering, software development is peculiarly prone to failure. As recently as 2003, IBM stated, Most software projects fail. In fact, the Standish group reports that over 80% of projects are unsuccessful either because they are over budget, late, missing function, or a combination. Moreover, 30% of software projects are so poorly executed that they are canceled before completion. Professional software developers, being intelligent and reflexive, and driven by a desire to become more efficient, or wanting to avoid the wrath of bosses and clients, frequently look for ways to reduce risk and improve the software development process. In recent years theyve succeeded in improving the success rate of software engineering, largely due to the adoption of software development methodologies that improve the business process of producing software. If youre a hobbyist or casual programmer, you dont need to learn about software development methodologies. If you are going to be held accountable for the success or failure of a project, you should learn more about software development methodologies. If youre going to be interviewing for a job as a programmer, it pays to recognize some of the names of software development methodologies and ask whether your employer has adopted a particular approach, especially if youd like to work for a company that prides itself on being well-organized and supportive of staff development. Hiring managers may say, weve synthesized several methodologies, which may mean they are ignorant or dont give a damn, or it may mean they are prepared to thoughtfully discuss the merits of various

22

approaches to software development. Managers who can discuss software development methodologies are more likely to be concerned about the welfare of their team. Here are some software development methodologies you may hear about, with some notable characteristics: waterfall process an old and disparaged approach Agile software development an iterative and incremental approach Scrum known for sprints and daily standup meetings Extreme Programming pair programming and test-driven development As you mature as a software developer, take time to think about the process of building software and learn more about software development methodologies.

Behavior-Driven Development
There is one prominent software development methodology that is important for product planning. It is called Behavior-Driven Development (BDD), or sometimes, Behavior-Driven Design. BDD takes user stories and turns them into detailed scenarios that are accompanied by tests. Heres a screenshot from the Lowdown web application that shows how a user story can be extended from a feature to include detailed scenarios.

23

Rails developers turn these scenarios into tests and use a software tool named Cucumber to run automated test suites. With automated tests, a product owner can determine if developers have succeeded in implementing the required features. This process is called acceptance testing. Automated tests also make it easy for developers to determine if the application still works as they add features, fix bugs, or reorganize code. This process is called regression testing. On a small project like our tutorial application, you wont use BDD or Cucumber. Its easy enough to manually test the features before you deploy it. On a project where money and reputation is at stake, BDD can be very important. Every time an application is deployed, theres a chance that something could be broken. Software development is plagued with fix one thing, accidentally break another as code is refactored or improved. Manual testing cant be expected to reveal every bug. Thats why automated testing, providing coverage of every significant user-facing feature, is the only way to know if youve deployed without known bugs.

24

For an introductory book, BDD is an advanced topic. But it is important to know that user stories can be turned into automated tests when money and reputation is at risk.

25

Chapter 5

Manage Your Project

How do you know youre making progress? Are you taking care of everything that needs to be done? These questions are at the center of project management. Whether you are working alone or as part of a team, you need to define your tasks and track progress toward your goal. The previous chapter on product planning showed how user stories can be used to break down an application into discrete features. User stories can be the basis for a list of tasks.

To-Do List
You can track your tasks with a simple to-do list. Some entrepreneurs like the discipline of the GTD system (Getting Things Done) for personal productivity and time management. Our article on Rails and Project Management offers a list of popular to-do list applications, either for personal task management or team-oriented task management.

Kanban
Kanban is a method of managing projects that has been adapted from lean manufacturing for use in software development. In Japanese, Kan means visual, and ban means card or board. Imagine putting a big whiteboard on your wall and creating columns for a series of to-do lists. The columns, called swimlanes, are labelled: Backlog, Ready, Coding, Testing, Done. Each swimlane contains index cards that describe a user story or other task. To plan your work and track progress, youll move the index cards across the board from column to column. To stay focused and avoid becoming overwhelmed, youll only pick the most important user stories or tasks from the backlog column and youll limit the number of items in each column to what can be realistically accomplished in the time available. Thats the essence of kanban as it is used for software development. See the article on Rails and Project Management for a list of kanban web applications. Trello is particularly popular for task management.

26

Agile Methodologies
For a solo project or a small team, youll do fine with a simple to-do list or (even better) a kanban web application for managing your software development process. If youve got enough people to need to hire a project manager, you should look at project management software that supports teams using Agile software development methodologies. Pivotal Tracker is the best known tool but there are many other agile tools. Learn more about Agile if youre going hire developers for a startup or if you are going to work for an established company. In most successful companies, Agile processes have replaced the much-maligned waterfall process that was once the norm for software development. Our article on Rails and Project Management goes into more detail.

27

Chapter 6

Accounts You May Need

This tutorial will show you how to save your work using GitHub. You can sign up for a GitHub account for free. Well also send email from the application, and save data to Google Drive, which will require a Gmail account. A Gmail account is free. Well create a form that allows website visitors to opt-in to a mailing list. Youll need a MailChimp account, which is free. Finally, well deploy the tutorial application to Heroku which provides Rails application hosting. It costs nothing to set up a Heroku account and deploy as many applications as you want.

GitHub
Rails developers use GitHub for collaboration and remote backup of projects. For this tutorial, I suggest you get a free personal GitHub account if you dont already have one. As a developer, your GitHub account establishes your reputation in the open source community. If youre seeking a job as a developer, employers will look at your GitHub account. When you work with other developers, they may check to see what youve worked on recently. Dont be reluctant to set up a GitHub account, even if youre a beginner. It shows you are serious about learning Rails. Youll be asked to provide a username. This can be a nickname or short version of your real name (for example, your Twitter username). Youll be asked to provide an email address. Its very important that you use the same email address for your GitHub account that you use to configure Git locally (there will be more about configuring Git later). If you create a Heroku account to deploy and host your Rails applications, you should use the same email address. After you create your GitHub account, log in and look for the button Edit Your Profile. Take a few minutes to add some public information to your account. It is really important to provide your real name and a public email address. Displaying your real name on your GitHub account makes it easy for people to associate you with your work when they meet you in real life, for example at a meetup, a hackathon, or a conference. Providing a public email address makes it possible for other developers to reach you if you ask questions or submit issues. If you can, provide a website address (even just your Twitter or Facebook

28

page). In general, you wont be exposed to stalkers or spammers (except some recruiters) if you are open about yourself on GitHub. Later Ill show you how to set up and use Git and GitHub.

Gmail
The tutorial shows how the application can connect to a Gmail account to send email. We use Gmail as our example because many people already have a Gmail account. We will use your Gmail username and password to save data to Google Drive. You can get a free Gmail account if you dont already have one. Some Google accounts require 2-step verification, which sends a unique code to your mobile phone each time you log in from an unfamiliar device. If your Google account requires twofactor authentication, you have two choices: turn off 2-step verification create a new Gmail account for use with this tutorial Other services, such as Mandrill, can be used to send email from the application. Or you can connect directly to an SMTP mail server to send email. The tutorial wont show the details but Ill provide links for more information if you dont want to use Gmail.

MailChimp
This tutorial shows how website visitors can sign up to receive a newsletter provided by a MailChimp mailing list. MailChimp allows you to send up to 12,000 emails/month to a list of 2000 or fewer subscribers for free. There is no cost to set up an account. After you have set up a MailChimp account, create a new mailing list where you can collect email addresses of visitors who have asked to subscribe to a newsletter. The MailChimp Lists page has a button for Create List. The list name and other details are up to you. If you get frustrated with the complex and confusing MailChimp interface, try to remember that the friendly MailChimp monkey is laughing with you, not at you.

Heroku
Well use Heroku to host the tutorial application so anyone can reach it. To deploy an app to Heroku, you must have a Heroku account. Visit https://id.heroku.com/signup/devcenter to set up an account.

29

Be sure to use the same email address you used to register for GitHub. Its very important that you use the same email address for GitHub and Heroku accounts.

30

Chapter 7

Get Started
Before You Start
If you follow this tutorial closely, youll have a working application that closely matches the example app in the learn-rails GitHub repository. If your application doesnt work after following the tutorial, compare the code to the example app in the GitHub repository, which is known to work. The online edition of this tutorial contains a comments section at the end of the tutorial. I encourage you to offer feedback to improve this tutorial. If you find problems or wish to suggest improvements, Im eager to hear from you. Its best to create a GitHub issue but feel free to email me directly at [email protected] if you prefer.

Jumping Around
The tutorial is designed to unfold in steps, one section leading to another. You can use the book as a reference, skipping around without reading from beginning to end, but youll actually waste time as you try to pick up the pieces you missed. Its best to work through the book from start to end, allowing enough time to read the introductory chapters and then building the application. That means you should allow time to read the book before you start a new job or join a developer bootcamp. Really!

Your Computer
Mac OS X, Linux, or Windows
You can develop web applications with Rails on computers running Mac OS X, Linux, or Microsoft Windows operating systems. Most Rails developers use Mac OS X or Linux because the underlying Unix operating system has long been the basis for open source programming. Installing Rails on Windows is frustrating and painful. Readers and workshop students often tell me that theyve given up on learning Rails because installation of Ruby on Windows is

31

difficult and introduces bugs or creates configuration issues. Even when you succeed in getting Rails to run on Windows, you will encounter gems you cannot install. For these reasons, I urge you to use Nitrous.io, a browser-based development environment, on your Windows laptop.

Hosted Computing
Nitrous.io provides a hosted development environment. That means you set up an account and then access a remote computer from your web browser. The Nitrous.io service is free for ordinary use. There is no cost to set up an account. Youll only be charged if you add extra memory or computing power (which you dont need for ordinary Rails development). The Nitrous.io service gives you everything you need for Rails development, including a Unix shell with Ruby pre-installed, plus a browser-based file manager and text editor. Any device that runs a web browser will give you access to Nitrous.io, including a tablet or smartphone, though you need a broadband connection, a sizeable screen, and a keyboard to be productive. If you are using Windows, or have difficulty installing Ruby on your computer, try using Nitrous.io.

Text Editor
Youll need a text editor for writing code and editing files. I recommend Sublime Text 2 for Mac OS X, Windows, or Linux. Word processing programs, such as Microsoft Word, will not work because they introduce hidden formatting codes into text files. If you dont have a text editor, install Sublime Text now. You can find tutorials for Sublime Text on YouTube, including a popular Sublime Text 2 video from NetTutsPlus. It is not practical to explain how to set up and use a text editor in this short book, so use the instructions youll find elsewhere.

You Dont Need an IDE

Programmers who come to Rails from other platforms, such as Java or C++, often ask for recommendations for an IDE, or an integrated development environment. These are software applications that combine a text editor with built-in tools such as a debugger. A few Rails developers like JetBrains RubyMine, Aptana Studio, or Komodo but most Rails developers use only a text editor and terminal application. You dont need an IDE unless youre in the habit of using one. For a beginner, they are cumbersome and add little additional value.

32

Terminal
Youll need an application called a console or terminal emulator to run programs from your computers command line. We call the command line the shell because it is the outer layer of the operating systems internal mechanisms (which we call the kernel). On Mac OS X, you can use the Terminal application. Experienced developers often upgrade to the more powerful iTerm2 application. The Command Line Crash Course explains how to launch a terminal application. If you havent used the computers command line interface (CLI) before, spend some time with The Command Line Crash Course to become comfortable with Unix shell commands. Launch your terminal application now. Try out the terminal application by entering a shell command.
$ whoami

Dont type the $ character. The $ character is a cue that you should enter a shell command. This is a longtime convention that indicates you should enter a command in the terminal application or console. The Unix shell command Dont type the You might see:
command not found: $
$ whoami

returns your username.

prompt.

which indicates you typed the

character by mistake.

If you are new to programming, using a text editor and the shell will seem primitive compared to the complexity and sophistication of Microsoft Word or Photoshop. Software developers edit files with simple text editors and run programs in the shell. Thats all we do. We have to remember the commands we need (or consult a cheatsheet) because there are no graphical menus or toolbars. Yet with nothing more than a text editor and the command line interface, programmers have created everything that you use on your computer.

33

Getting Fancy
If you watch experienced developers at work, you may see their consoles are colorful, with lots of information shown in the prompt. Youll see Git status, current directory, and RVM gemset or Ruby version. Many developers replace the standard Bash shell with the Z shell and Oh-my-zsh. You dont have to install the Z shell to get a fancy prompt; the Bash-it utility is easy to install and gives you much of the functionality. A fancy prompt is helpful but requires some Unix skills to install. Dont worry about getting fancy now; you can try it down the road.

Installing Ruby
Your first challenge in learning Rails is installing Ruby on your computer. Frankly, this can be the most difficult step in learning Rails because no tutorial can sort out the specific configuration of your computer. Get over this hump and everything else becomes easy. The focus of this book is learning Rails, not installing Ruby, so to keep the book short and readable, Im going to give you links to articles that will help you install Ruby.

Mac OS X
See this article for installation instructions: Install Ruby on Rails Mac OS X

Ubuntu Linux
See this article for installation instructions: Install Ruby on Rails Ubuntu

Hosted Computing
Nitrous.io is a browser-based development environment. Nitrous.io is free for small projects. If you have a fast broadband connection to the Internet, this is your best choice for developing Rails on Windows. And it is a good option if you have any trouble installing Ruby on Mac or Linux because the Nitrous.io hosted environment provides everything you need, including a Unix shell with Ruby and RVM pre-installed, plus a browser-based file manager and text editor. Using a hosted development environment is unconventional but leading developers do so and it may be the wave of the future.

34

See this article for installation instructions: Install Ruby on Rails Nitrous.io

Windows
Here are your choices for Windows: Use the Nitrous.io hosted development environment Install the Railsbridge Virtual Machine or rails-dev-box Use RailsInstaller for Windows as documented in Installing Rails on Windows Nitrous.io is ideal if you have a fast Internet connection. If not, download the Railsbridge Virtual Machine or rails-dev-box to create a virtual Linux computer with Ruby 2.0 and Rails 4.0 using Vagrant. The last option, RailsInstaller, is not recommended because it does not provide an up-to-date version of Ruby or Rails. Also, RVM does not run on Windows. If you use RailsInstaller, you can still follow the tutorial; just skip the instructions that refer to RVM (though it is better to use Nitrous.io or a Vagrant virtual machine).

Understanding Version Numbers

Rails follows a convention named semantic versioning: The first number denotes a major version (Rails 4) The second number denotes a minor release (Rails 4.0) The third number denotes a patch level (Rails 4.0.1) A major release includes new features, including changes which break backward compatibility. That means switching from Rails 3.2 to Rails 4.0 will require a significant rewrite of a Rails 3.2 application. A minor release introduces new features but doesnt require a rewrite of the application. A patch release fixes bugs but doesnt introduce significant features.

Ruby 2.0 and Rails 4.0

Check that appropriate versions of Ruby and Rails are installed in your development environment. Youll need: The Ruby language (version 2.0.0 or newer)

35

The Rails gem (version 4.0 or newer) Open your terminal application and enter:
$ ruby -v

You might see:

ruby ruby-2.0.0-p247 (...)

Youve got Ruby version 2.0.0, patch level p247 (Ruby versions add an extra patch level to semantic versioning). Newer minor releases or patch levels are good and this tutorial will remain compatible. Try:
$ rails -v

You might see:

Rails 4.0.0

Versions such as

4.0.0.beta1

or

4.0.0.rc2

are beta versions or release candidates.

If you find youve installed Rails 4.0.1 or newer (a patch release), thats good. It means minor bugs have been fixed since this was written. If you find you have Rails 4.1.0 or newer (a minor release), check for a newer version of this tutorial. Minor features may have changed. You can check for the current version of Rails here. If you are running older versions of Ruby or Rails on your computer, you must install newer versions to avoid unexpected problems.

RVM
I promised that this book would introduce you to the practices of professional Rails developers. One of the most important utilities youll need in setting up a real-world Rails development environment is RVM, the Ruby Version Manager. RVM lets you switch between different versions of Ruby. Right now, that might not seem important, but as soon as a new version of Ruby is released, youll need to upgrade, and it is best to be ready by installing the current version of Ruby with RVM, so you can easily add a new version of Ruby later, and still switch back to older versions as needed.

36

RVM also helps you manage your collections of gems, by letting you create multiple gemsets. Each gemset is the collection of gems you need for a specific project. Rails changes frequently; with RVM, you can install a specific version of Rails in a project gemset, along with all the gems you need for the project. When a new version of Rails is released, you can create a new gemset with the new Rails version when you start a new project. Your old project will still have the version of Rails it needs in its own gemset. If youve followed the instructions in the article Installing Rails and installed RVM, youll be ready to handle multiple versions of Ruby, and multiple versions of Rails. Thats as it should be. Most professional Rails developers have more than one version of Ruby or Rails, and RVM makes it easy to switch. RVM will show you a list of available Ruby versions:
$ rvm list

You can see a list of available gemsets associated with the current Ruby version:
$ rvm gemset list

You will see an arrow that shows which gemset is active. You will see a Rails4.0.0 .
global

gemset as well as any others you have created, such as a gemset for

Heres how to switch between gemsets:

$ rvm gemset use global

And switch back to another:

$ rvm gemset use default

After youve worked on a few Rails applications, youll see several project-specific gemsets if you are using RVM in the way most developers do. RVM is not the only utility you can use to manage multiple Ruby versions. Some developers like Chruby, rbenv, or others. Dont be worried if you hear debates about RVM versus Chruby or rbenv; developers love to compare the merits of their tools. RVM is popular, wellsupported, and an excellent utility to help a developer install Ruby and manage gemsets; thats why we use it.

37

Project-Specific Gemset
For our learn-rails application, well create a project-specific gemset using RVM. Well give the gemset the same name as our application. By creating a gemset for our tutorial application, well isolate the current version of Rails and the gems we need for this project. Whether you use RVM or another Ruby version manager, this will introduce you to the idea of sandboxing (isolating) your development environment so you can avoid conflicts among projects. After we create the project-specific gemset, well install the Rails gem into the gemset. Enter these commands:
$ rvm use ruby-2.0.0@learn-rails --create $ gem install rails

The newest Rails version will be installed. Its absolutely necessary to create a gemset and install Rails so we can move on to creating the application in the next chapter. If you have trouble at this point, refer to the article Installing Rails or the RVM website. Linux users may need to check instructions for Integrating RVM. Lets make sure Rails is ready to run. Open a terminal and type:
$ rails -v

You should see the message Rails 4.0.0 (or something similar).

38

Chapter 8

Create the Application

In previous chapters youve gained a conceptual background. In this chapter youll begin building a Rails application.

How?
You need to get the code from this tutorial into your computer. You could just read and imagine, but really, building a working application is the only way to learn. The most obvious way is to copy and paste from this tutorial into your text editor, assuming you are reading this on your computer (not a tablet or printed pages). Its a bit tedious and error-prone but youll have a good opportunity to examine the code closely. Some students like to type in the code, character by character. If you have patience, its a worthwhile approach because youll become more familiar with the code than by copying and pasting. Dont feel shy about copying code; its how you will learn. Working programmers spend a lot of time copying code from others. At first, you will copy a lot of code. As you gain proficiency, you will copy code and adapt it, more extensively as you gain confidence and skill. Only when youve been working fulltime as a coder for months or years will you find yourself writing code from scratch; even then, when you encounter new problems, you will still look for code examples to copy and adapt.

Starter Applications
Rails provides a framework; that is, a software library that provides utilities, conventions, and organizing principles to allow us to build complex web applications. Without a framework, wed have to code everything from scratch. Rails gives us the basics we need for many websites. Still, the framework doesnt give us all the features we need for many common types of websites. For example, we might want users to register for an account and log in to access the website (user management and authentication). We might want to restrict portions of our website to just administrators (authorization). We also might want to add gems that enhance Rails to aid development (gems for testing, for example) or improve the look and feel of our application (Twitter Bootstrap). Developers often mix and match components to make a customized Rails stack.

39

Developers often use a starter application instead of assembling an application from scratch. You might call this a template but we use that term to refer to the view files that combine HTML with Ruby code to generate web pages. Most experienced developers have one or more starter applications that save time when beginning a new project. The RailsApps project was launched to provide open source starter applications so developers could collaborate on their starter applications and avoid duplicated effort. After you gain some skill with this tutorial, you might use the RailsApps starter apps to instantly generate a Rails application with features like authentication, authorization, and Twitter Bootstrap. For now, well begin with the Rails default starter application.

Where Are You?

In this tutorial, the terms folders and directories mean the same thing. The Unix The
ls pwd

command shows the present working directory, where you are.

command shows folders and files in a directory.

cd

Use the Unix

command to change directories.

Take a moment to think about where on your computer youll do your work and store your files. You may have a documents/ folder. You could make a similar folder named projects/ or code/ or workspace/ for your programming projects. Use the Unix mkdir command to create a folder or create it with your file browser. If you havent done so already, make a folder to contain your programming projects:
$ cd ~ $ pwd /Users/danielkehoe $ mkdir workspace $ cd workspace

If you are using Nitrous.io, you already have a workspace/ folder. Lets explore the
rails new

command and get started building the tutorial application.

Rails New Command

Rails provides the
rails new

command to create a basic Rails application.

We already created a project-specific gemset using RVM. Make sure its ready to use:

40 $ rvm use ruby-2.0.0@learn-rails

First, lets see our options. Type:

$ rails new --help

Youll see a help message that shows all the options for the rails new command. Its important to know that help messages are available for Rails commands. Youll see a summary of the command syntax:
Usage: rails new APP_PATH [options]

Youll see a list of command options and an explanation of what the rails new command will do:
The 'rails new' command creates a new Rails application with a default directory structure and configuration at the path you specify.

In the example, APP_PATH, or the path you specify, is the name of your project and will appear in your code as the name of the application. The rails new command creates a directory (project folder) and generates subfolders and files within it. Of all the options, the only one well use right now is the -T option which tells the rails new command not to generate a set of files for the Test::Unit testing framework. This is an example of customizing our Rails stack. In its default configuration, Rails uses the Test::Unit testing framework. Like many Rails developers, the RailsApps project uses the RSpec framework instead. I wont be showing you how to write tests in this introductory tutorial but I will show you how to download and run pre-written tests from our GitHub repository. The -T option will prepare us for that.

Building the Application

To create the Rails default starter application, type:
$ rails new learn-rails -T

This will create a new Rails application named learn-rails.

41

You may give the app a different name if you are building it for another purpose. For this tutorial, well assume the name is learn-rails. It will save you trouble to use this name. Use the -T flag to skip Test::Unit files. Later in the tutorial, well download and run test files that use the RSpec testing framework so we dont want Test::Unit files in our way. The
rails new

command will create nine folders and 53 files.

It will install 44 gems into your gemset. After you create the application, switch to its folder to continue work directly in the application:
$ cd learn-rails

This is your project directory. It is also called the application root directory. Type the ls command to show the folders and files in a directory. Soon well learn more about each of these folders and files.

Setting RVM
RVM gives us a convenient technique to make sure we are always using the correct gemset when we enter the project directory. It will create hidden files to designate the correct Ruby version and project-specific gemset. Enter this command to create the hidden files:
$ rvm use ruby-2.0.0@learn-rails --ruby-version

If you see ERROR: Gemset learn-rails does not exist, perhaps you overlooked an earlier step in the Project-Specific Gemset section (in the previous chapter) where we created the learn-rails gemset. No matter, you can create it now:
$ rvm use ruby-2.0.0@learn-rails --create --ruby-version $ gem install rails

The --ruby-version argument creates two files, .ruby-version and .ruby-gemset, that set RVM every time we cd to the project directory. Without these two hidden files, youd need to remember to enter rvm use ruby-2.0.0@learn-rails every time you start work on your project after closing the console. You can confirm youve created the two hidden files:

42 $ ls -1pa ./ ../ .gitignore .ruby-gemset .ruby-version Gemfile Gemfile.lock README.rdoc Rakefile app/ bin/ config/ config.ru db/ lib/ log/ public/ tmp/ vendor/

The a flag in the Unix ls -1pa command displays hidden files. Each hidden file is listed with a dot (period or full stop) at the beginning of the filename. Youll notice .ruby-gemset and .ruby-version . Youll also see two special files which are not files at all:
./ ../

an alias that represents the current directory an alias that represents the parent directory

Thats a brief diversion into Unix; lets try running our new Rails application.

Test the Application

Youve created a simple default web application. Its ready to run.

Launching the Web Server

You can launch the application by entering the command:
$ rails server

Youll see:

43 => Booting WEBrick => Rails 4.0.0 application starting in development on http://0.0.0.0:3000 => Run `rails server -h` for more startup options => Ctrl-C to shutdown server [...] INFO WEBrick 1.3.1 [...] INFO ruby 2.0.0 (2013-02-24) [x86_64-darwin12.2.0] [...] INFO WEBrick::HTTPServer#start: pid=38534 port=3000

The rails Ruby.

server

command launches the default WEBrick web server that is provided with

Viewing in the Web Browser

To see your application in action, open a web browser window and navigate to http://localhost:3000/. Youll see the Rails default information page.

Watching Log Messages

Notice that messages scroll in the console window when your browser requests the Rails default web page. Open the file log/development.log and youll see the same messages. When a browser sends requests to the WEBrick web server, diagnostic messages are written to the console and to the log/development.log file. These diagnostic messages are an important tool for troubleshooting when you are developing. You can keep more than one terminal window open. For convenience, you may want to keep a terminal window open for running the web server and watching diagnostic messages. In the Terminal or iTerm2 applications, Command-t opens additional console sessions in new tabs.

Stopping the Web Server

You can stop the server with Control-c to return to the command prompt. Most of the time youll keep the web server running as you add or edit files in your project. Changes will automatically appear when you refresh the browser or request a new page. There is a tricky exception, however. If you make changes to the Gemfile, or changes to configuration files, the web server must be shut down and relaunched for changes to be activated. As a rule of thumb, files that produce web pages can be changed without a restart. This includes any file in the app/ folder which creates web pages, as well as the config/routes.rb file. Changes to files that create the environment for the web application, such as gems or

44

configuration files, and are loaded at web server launch, wont be seen until the web server is restarted.

Getting Organized for Efficiency

Before we learn about the Rails directory structure, take a minute to organize your screen real estate. During development, youll jump between the console in a terminal application, your text editor, and a web browser window. As a Rails developer, youll do this constantly, so think about how you can do this efficiently. Multiple screens make it easy, but even on a laptop you can get organized for efficiency.

Heres some ideas. Open a window in the terminal application, place it on the left side of your screen, and stretch it to the maximum vertical height of your screen. Open multiple tabs in your terminal application. Keep one tabbed window open for entering shell commands (like cd or ls ) and another terminal window open for running the rails server command and viewing the log output. Place your text editor window next to the terminal window and stretch it to full vertical height. If you are using Sublime Text, you can open two editor panels side-by-side. Some developers find it helpful to leave the file browser panel open to navigate the project directory; others hide the file browser panel to save space. If you have enough screen space, leave your web browser open and place it next to your text editor. If your screen space is limited, you may have to overlap the web browser with the text editor, but position your web browser window so you can bring it to the front with a single click. Youll need multiple tabs open in your web browser. Unless you like constant distraction, close Gmail, Facebook, Twitter, and Hacker News. Open tabs for http://localhost:3000/, this tutorial, and additional references or documentation.

45

On the Mac, there are window management utilities that reposition windows with just a click or keyboard command; I use Moom but you can find others if you search for mac window management utilities. This is just a guide; Im sure you can improve upon these suggestions.

46

Chapter 9

The Parking Structure

Weve created the default Rails starter application. The
rails new

command has created a project directory for us.

It is a parking structure for our code. Unlike an ordinary parking structure, where you park anywhere you like, this garage has assigned parking. You have to park your code in the right place. This is Rails, where convention brings order to the development process. Use the Unix ls command to list the contents of the project directory. For a one-column list that shows each subdirectory (marked with a slash), well add the -1p option to the command.
$ ls -1p

Youll see:
Gemfile Gemfile.lock README.rdoc Rakefile app/ bin/ config/ config.ru db/ lib/ log/ public/ tmp/ vendor/

Now is a good time to open a file browser window and look at the contents of the project directory. On the Mac, theres a command you can use to open the graphical file browser from the console. If youre in the project directory, type open . . The period (or dot) is a Unix symbol that means the directory Im in.
$ open .

47

Youll learn more about each file and folder as you proceed through the tutorial. To get you started, here are two tables. The first describes the files and folders that are important for every beginner. The second table describes the files and folders that you can ignore.

Important Folders and Files

These folders and files are important to beginners. Gemfile Gemfile.lock
Lists all the gems used by the application. Lists gem versions and dependencies.

README.rdoc A page for documentation. app/

*config/ * Application folders and files. Configuration folders and files. Database folders and files. Files for web pages that do not contain Ruby code, such as error pages.

db/ public/

Not-So-Important Folders and Files

These folders and files are important to Rails but not important to beginners.
Rakefile bin/ Directives for the Rake utility program. Folder for binary (executable) programs.

config.ru Configuration file for Rack (a software library for web servers). lib/ log/ tmp/ vendor/ Folder for miscellaneous Ruby code. Folder for application server logfiles. Temporary files created when your application is running. Folder for Ruby software libraries that are not gems.

The App Directory

Take time to drill down into the app/ folder in the project directory. This is easiest using the file browser. You can also use your text editor. Or you can do it with Unix commands:

48 $ cd app $ ls -1p assets/ controllers/ helpers/ mailers/ models/ views/ $ cd ..

We enter the app folder, list the contents, and then use the directory dot dot) to return to the project directory.

cd ..

command (change

Most of the work of developing a Rails application happens in the app/ folder. Earlier we described Rails as a set of files organized with a specific structure. We said the structure is the same for every Rails application. The app/ directory is a good example. The six folders in the app/ directory are the same in every Rails application. This makes it easy to collaborate with other Rails developers, providing consistency and predictability. assets controllers helpers mailers models views You may recall our earlier description of Rails from the perspective of a software architect. In this folder, youll see evidence of the modelviewcontroller design pattern. Three folders named models/, views/, and controllers/ enforce the software architects separation of concerns and impart structure to our code. As you build the application, well explain the role of the MVC components in greater detail. Two folders, mailers/ and helpers/, play supporting roles. The mailers folder is for code that sends email messages. The helpers folder is for Rails view helpers, snippets of reusable code that generate HTML. Later, when we learn more about views, well say view helpers are like macros that expand a short command into a longer string of HTML tags and content. As a Rails developer, youll spend most of your time navigating this heirarchy of folders as you create and edit files. And because Rails provides a consistent structure, youll quickly find your way on any unfamiliar project.

49

Chapter 10

Time Travel with Git

Now that weve looked at our Rails project directory from the viewpoint of a programmer and software architect, lets consider the viewpoint of the time traveler. This chapter will introduce you to software source control, also called version control or revision control. The terms all have the same meaning; at first sight, the concept seems rather dull, like sorting your socks. But it makes professional software development possible and, at the core, it is essentially a form of time travel. To understand time travel, we need to understand state. Its a term youll encounter often in software development. We know about states of matter. Water can be ice, liquid, or steam. Imagine a machine with a button that, each time it is pressed, changes water from one state to another. We call this a state machine. Almost every software program is a state machine. When a program receives an input, it transitions from one state to another. Like flipping a light switch, theres no in-between. Light or dark. Ice, liquid, or steam. Or, in a web application: logged in, logged out. When we write software code, theres a lot of in-between. We look things up, we think, we type errors and we make corrections. As humans, we spend a lot of time in a flow of undetermined state. We can save our work at any time, but we may be saving typos or unfinished code that doesnt work. Every so often, we get to a point where a task is finished; weve fixed all our errors and our code runs. We want to preserve the state of our work. Thats when we need a version control system. A version control system does more than a software applications Save command. Like a Save command, it preserves the current state of our files. It also allows us to add a short note that describes the work weve done. More importantly, it archives a snapshot of the current state in a repository where it can be retrieved if needed. Heres where the time travel comes in. We can go back and recover the state of our work at any point where we committed a snapshot to the repository. In software development, travel to the past is essential because we often make mistakes or false starts and have to return to a point where we know things were working correctly. What about time travel to the future? Often we need to try out code we may decide to discard, without disturbing work weve done earlier. Version control systems allow us to explore alternative futures by creating a branch for our work. If we like what weve done in our branch, we can merge it into the main trunk of our software project. Unlike time travel in the movies, we cant travel back to any arbitrary point in the flow of time. We can only travel to past or future states weve marked as significant by checking our work into the repository.

50

Git
The dominant version control system among Rails developers is Git, created by the developer of the Linux operating system. Unlike earlier version control systems, Git is ideal for wide-scale distributed open source software development. Combined with GitHub, the social coding website, Git makes it easy to share and merge code. When you work with others on a project, your Git commit messages (the notes that accompany your snapshot) offer a narrative about the progress of the project. Well-written commit messages describe your work to co-workers or open source collaborators. GitHubs support for forking (making your own copy of a repository) makes it possible to take someone elses project and modify it without impacting the original. That means you can customize an open source project for your own needs. You can also fix bugs or add a feature to an open source project and submit a pull request for the project maintainer to add your work to the original. Fixing bugs (large or small) and adding features to open source projects are how you build your reputation in the Rails community. Your GitHub account, which shows all your commits, both to public projects and your own projects, is more important than your resum when a potential employer considers hiring you because it shows the real work you have done. Collaboration is easy when you use a branch in Git. If you and a coworker are working on the same codebase, you can each make a branch before adding to the code or making changes. Git supports several kinds of merges, so you can integrate your branch with the trunk when your task is complete. If your changes collide with your coworkers changes, Git identifies the conflict so you can resolve the collision before completing the merge. All the power of Git comes at a price. Git is difficult for a beginner to learn, largely because many of its procedures have no real-world analog. Have you noticed how time travel movies require mental gymnastics, especially when you try to make sense of alternative futures and intersecting timelines? Git is a lot like that, mostly because we use it to do things we dont ordinarily do in the real world. In this tutorial, you wont encounter Gits advanced procedures, like resolving merges or reverting to earlier versions. Well stick to the basics of archiving our work (and in one case, discarding work that weve done for practice). You can build the tutorial project without using Git. But I urge you to use Git and a GitHub account for this project, for two reasons. First, with your tutorial application on GitHub, youll show potential employers or collaborators that youve successfully built a useful, functioning Rails application. More importantly, you must get to know Git if you plan to do any serious coding, either as a professional or a hobbyist. Before I show you Git commands, I want to mention that some people use graphical client applications to manage Git. Mac OS X has GitHub for Mac, Git Tower, and other Mac Git clients. Graphical applications for Git are useful for colleagues who dont use a Terminal application, such as graphic designers or writers. Theres no need for you to install these

51

applications. Every developer Ive met uses Git from the command line. It will take effort to master Git; the commands are not intuitive. But it is absolutely necessary to become familiar with Git basics. Before you do any work on the tutorial application, Ill show you the basics of setting up and using Git.

Is Git Installed?
As a first step, make sure Git is installed on your computer:
$ which git /usr/local/bin/git $ git version git version ...

If Git is not found, install Git. See the article Rails with Git and GitHub for installation instructions.

Is Git Configured?
Make sure Git knows who you are. Every time you update your Git repository with the git commit command, Git will identify you as the author of the changes.
$ git config --get user.name $ git config --get user.email

You should see your name and email address. If not, configure Git:
$ git config --global user.name "Real Name" $ git config --global user.email "[email protected]"

Use your real name so people will associate you with your work when they meet you in real life. Theres no reason to use a clever name unless you have something to hide. Use the same email address for Git, your GitHub account, and Heroku to avoid headaches.

Create a Repository
Now well add a Git repository to our project. Its a basic step youll repeat every time you create a new Rails project.

52

Extending the time traveler analogy, initializing a Git repository is equivalent to setting up the time machine. The git init command sets up a Git repository (a repo) in the project directory. We add the Unix symbol that indicates Git should be initialized in the current directory (git init dot):
$ git init . Initialized empty Git repository in ...

It creates a hidden folder named .git/ in the project directory. You can peek at the contents:
ls -1p .git HEAD config description hooks/ info/ objects/ refs/

All Git commands operate on the hidden files. The hidden files record the changing state of your project files each time you run the git commit command. There is no reason to ever edit files inside the hidden .git/ folder (doing so could break your time machine).

GitIgnore
The hidden .git/ folder contains the Git repository with all the snapshots of your changing project. The snapshots are highly compressed, only containing records of changes, so the repository takes up very little file space relative to the project as a whole. Not every file should be included in a Git snapshot. Here are some types of files that should be ignored: log files created by the web server database files configuration files that include passwords or API keys Git gives us an easy way to ignore files. A hidden file in the project directory named .gitignore can specify a list of files that are never seen by Git. The rails new command creates a .gitignore file with defaults that include log files and database files. Later, when we add configuration files that include secrets, well update the .gitignore file. Take a look at the contents of the .gitignore file. We use the Unix the contents of the file:
cat

command to display

53 $ # # # # #
cat .gitignore See http://help.github.com/ignore-files/ for more about ignoring files. If you find yourself ignoring temporary files generated by your text editor or operating system, you probably want to add a global ignore instead: git config --global core.excludesfile '~/.gitignore_global'

# Ignore bundler config. /.bundle # Ignore the default SQLite database. /db/*.sqlite3 /db/*.sqlite3-journal # Ignore all logfiles and tempfiles. /log/*.log /tmp

For a .gitignore file that ignores more, see an example .gitignore file from the RailsApps project.

Git Workflow
Your workflow with Git will move through four distinct phases as you add or edit files.

Untracked Files
The first phase is a dirty state of untracked and changed files, before any snapshot. The git status command lists all folders or files that are not checked into the repository.
$ # # # # # # # # # # # # # #
git status On branch master Initial commit Untracked files:

(use "git add <file>..." to include in what will be committed)

.gitignore Gemfile Gemfile.lock README.rdoc Rakefile app/ bin/

54 # config.ru # config/ # db/ # lib/ # log/ # public/ # vendor/ nothing added to commit but untracked files present (use "git add" to track)

Here the git status command tells us that we have many untracked files. We have created new files and they are saved on the computers hard disk but nothing has been recorded in the Git repository.

Staging
Recording files in the Git repository takes two steps: staging and committing. There will be times when you change many files at once. For example, you may fix a bug, add a new graphic, and change a form. You might think youd like to have Git automatically record all the changes as you save each file. But the story of your project would be confusing and overly detailed. Git requires you to mark one or more files (staging) before recording the changes (committing). This gives you fine-grained control over the recorded history of your project. You can mark individual files to be staged:
$ git add Gemfile

Adding individual files allows you to selectively record the history of your project. For example, you might stage and commit a series of bug fixes before you stage and commit new features. Applying the time traveler analogy, it will be easier to travel back to look at bug fixes if they are not mixed in with new features. More often, youll mark all the files to be staged. Do so now:
$ git add -A

Running

git status

will show you a long list of files that are staged and ready to commit.
git add

There are three forms of the

git add foo.txt git add . git add -A

command:

adds a file named foo.txt

adds all new files and changed files, except deleted files adds everything, including deletions

55

If it seems nonsensical that the command git add -A adds deletions, dont worry. Like time travel, Git will stretch your understanding of what makes sense. Most often, you can simply use the
git add -A

form of the command.

Committing
Staging gives you an opportunity to organize your changes in groups before you commit. If youve only worked on one feature, youll likely stage and commit everything at once. When you make a commit, you include a message that describes the work youve done. For a time traveler, the commit message is important; you are leaving a trail to help you find your way into the past. Google will show you dozens of blog posts about writing better commit messages but common sense can be your guide. Writing fix registration form to catch blank email addresses will be more helpful than merely writing fix bugs. And if you wonder why commit messages are commonly written in the imperative not past tense (fix not fixed), its a time traveler convention. Now commit your project to the repository:
$ git commit -m "Initial commit"

The -m flag lets you add a message for the commit. The pristine state of your new Rails application is now recorded in the repo. Running
git status

will tell you nothing to commit (working directory clean). command to see your project history:

You can use the

$ git log

git log

If you get stuck in

git log

, type

to return to the command prompt.

Pushing to GitHub
Weve seen three phases of the Git workflow: untracked, staged, and committed. A fourth stage is important when you work with others: pushing to GitHub. Its also important when you access your project from more than one computer or you want an offsite backup of your work. The repositories hosted on your GitHub account establish your reputation as a Rails developer for employers and developers you may work with. Even if your first project is

56

copied from a tutorial, it shows you are serious about learning Rails and studying conscientiously. Did you create a GitHub account? Now would be a good time to add your repo to GitHub. Go to GitHub and create a new empty repository for your project. Name the repository learn-rails and give it a description. If the repository is public, hosting on GitHub is free. Dont be reluctant to go public with an unfinished or half-baked project; everyone expects projects on GitHub to be works in progress. Add GitHub as a remote repository for your project and push your local project to GitHub. Before you copy and paste the command, notice that you need to insert your own GitHub account name:
$ git remote add origin https://github.com/YOUR_GITHUB_ACCOUNT/learn-rails.git $ git push -u origin master

Now you can view your project repository on GitHub at: https://github.com/YOUR_GITHUB_ACCOUNT/learn-rails Take a look. Its an exact copy of the project on your local computer. If you havent used GitHub before, take some time to explore. GitHub is absolutely essential to all open source Rails development. You may notice that the README.rdoc file is automatically incorporated into the home page of the project repository on GitHub. For our next step, well update the README file, commit it to the local repo, and push it up to GitHub.

The README
Changing the README file is a good way to practice with Git. Its also a good habit to edit the README file whenever you create a new project. Its easy to neglect the README for little projects that youve just started. But replacing a default README file shows you are a disciplined, conscientious developer who will be a good collaborator. The new README file can be brief. Just state your intentions and acknowledge any code youve borrowed. For this project you could say, Excited to learn Rails with help from the RailsApps project! In your text editor, open the file README.rdoc and replace the contents:
Learning Rails ==

57

Learning Rails with a tutorial from the RailsApps project.

GitHub lets you add formatting using your choice of markup syntax, depending on the file extension you add to the filename: README.rdoc uses the rdoc syntax README.md uses the GitHub Flavored Markdown syntax README.textile uses the Textile syntax Well use Markdown syntax by adding the headline.
==

characters after the first line of text to force a

Theres no requirement that you use Markdown syntax in your README file. Markdown is a popular way to add formatting to improve readability. For us, changing the file to Markdown creates a practical exercise in using Git. Well use the
git mv

command to rename the file to README.md and save it.

$ git mv README.rdoc README.md

Use
$ # # # # # #

git status

to see what has changed:

git status On branch master Changes to be committed:

(use "git reset HEAD <file>..." to unstage)

renamed: README.rdoc -> README.md

You could also use the Unix mv command to rename the file. If you do so, git status will show the README.rdoc file has been deleted and a new, untracked README.md file has been created. Heres our typical workflow. Well stage, commit, and push the change to GitHub:
$ git add -A $ git commit -m "update README" $ git push origin master

Take a look at your GitHub repository (refresh the web page). Very cool! The README file has been updated.

58

The

git log

command will display your project history:

$ git log

You can read more about Git and Rails if you need more information about working with Git and GitHub for code source control. Now that youre comfortable with Git, we can begin customizing our new Rails application.

59

Chapter 11

Gems
The art of selecting gems is at the heart of Rails development. I explained earlier that gems are packages of code, software libraries, that have been developed and tested by other developers. Some gems add functionality or features to a website. Other gems play a supporting role, making development easier or implementing basic infrastructure. Gems are open source. They are available at no charge and can be freely copied and modified. It is a mark of honor to release a gem for public use, and a developers reputation can be established when a gem becomes popular and widely used. Gems are often created when a developer has used the same code as a component in more than one web application. He or she will take time to release the code as a gem. Thats how the Rails ecosystem was built, gem by gem since 2004. There is no evaluation or review process in publishing gems. Gems are hosted on a public server, rubygems.org. Gems are mostly text files (like any other Ruby code), organized in a particular format with some descriptive information (in a gemspec file), and compressed and archived as a single file. A single command, gem push , uploads a gem to the rubygems.org server for anyone to use. Over 50,000 gems have been released since rubygems.org was established. Some of these gems are used by one or two developers on their own projects. Many others have been neglected and abandoned due to lack of interest. Only a few thousand gems are popular and widely used. As a Rails developer, you must master the art of finding and evaluating gems so you can base your applications on the tried-and-true work of others. There is no single authoritative source of recommendations for gems. The Ruby Toolbox website categorizes and ranks many gems by popularity, and it is a good place to begin hunting for useful gems. Other than that, it is useful to study example applications and search for blog posts to find which gems are most often recommended. When you find an interesting gem, search Stack Overflow or Google to see what people are saying. Look at the gems GitHub repository and check: How many issues are open? How many are closed? How recent are the commits of patches or updates? Is there a CHANGELOG file? Is the gem well-documented? How many stars (people watching) or forks (people hacking)? Popular gems are likely to have many reported issues, some of which are trivial problems or feature requests. Gems that are actively maintained will have many closed issues and,

60

ideally, only a few open issues. When you find a gem that has many open issues and no recently closed issues, youve probably found a gem that has been abandoned. Also look at the commit log, which youll find on the GitHub project page in a tab at the top of the page. Regular and recent activity in the commit log indicates the gem is actively maintained.

Rails Gems
Rails itself is a gem that, in turn, requires a collection of other gems. This becomes clear if you look at the summary page for Rails on the rubygems.org site. On that page, youll see photos of the Rails core team. More importantly, youll see a list of gems that are required to use Rails: actionmailer framework for email delivery and testing actionpack framework for routing and responding to web requests activerecord framework for connections to databases activeresource framework for manipulating data activesupport utility classes and Ruby library extensions bundler utility to manage gems railties console commands and generators These are the runtime dependencies for Rails. Each of these gems has its own dependencies as well. When you install Rails, a total of 44 gems are automatically installed in your development environment.

Gems for a Rails Default Application

In addition to the Rails gem and its dependencies, a handful of other gems are included in every rails new default starter application: sqlite3 adapter for the SQLite database sass-rails enables use of the SCSS syntax for stylesheets uglifier JavaScript compressor coffee-rails enables use of the CoffeeScript syntax for JavaScript jquery-rails adds the jQuery JavaScript library turbolinks faster loading of webpages jbuilder utility for encoding JSON data

61

You may not need a SQLite database, SCSS for stylesheets, jQuery or the others, but many developers use these tools so they are included in the default starter application.

Where Do Gems Live?

When you run a Rails application, gems are loaded into the computers working memory immediately before your own custom code is loaded. Gems are handled by the Ruby interpreter no differently than your own code. Its all Ruby code, whether you or someone else wrote it. When you are building an application in Rails, you dont need to think about where gems are stored in your file system. If youre a curious person, though, you might wonder where the gems live. Run the
gem which

command and youll see:

$ gem which bundler /Users/me/.rvm/gems/ruby-2.0.0-p0@global/gems/bundler-1.3.5/lib/bundler.rb $ gem which rails /Users/me/.rvm/gems/ruby-2.0.0-p0@learn-rails/gems/railties-4.0.0/lib/rails.rb

Gems are files saved to the computers disk storage. If you use RVM, they are saved to a hidden .rvm folder in your user directory. A global subfolder contains the Bundler gem. If youve followed the instructions in the Get Started chapter to install Rails, the projectspecific learn-rails subfolder contains the Rails gem. If you use Chruby or Rbenv instead of RVM, your gems will be stored in a different location. Youll never move or delete gems directly. Instead youll manage gems using the Bundler utility. The key to Bundler is the Gemfile.

Gemfile
Every Rails application has a Gemfile. Earlier, I described Rails from the viewpoint of the gem hunter, the developer who wants to assemble an application from the best open source components he or she can find. To the gem hunter, the Gemfile is the most important file in the application. It lists each gem that the developer wants to use. The Gemfile provides the information needed by the Bundler utility to manage gems. Bundlers bundle install command reads the Gemfile, then downloads and saves each listed gem to the hidden gem folder. Bundler checks to see if the gem is already installed and only downloads gems that are needed. Bundler checks for the newest gem version and records the version number in the Gemfile.lock file. Bundler also downloads any gem dependencies and records the dependencies in the Gemfile.lock file. Between the Gemfile, with its list of

62

gems that will be used by the application, and the Gemfile.lock file, with its list of dependencies and version numbers, you have a complete specification of every gem required to run the application. More importantly, when other developers install your application, Bundler will automatically install all the gems (including dependencies and correct versions) needed to run the application. When you deploy the application to production for others to use, automated deployment scripts (such as those used by Heroku) install all the required gems. Bundler provides a bundle update command when we want to replace any gems with newer versions. If you run bundle update , any new gem versions will be downloaded and installed and the Gemfile.lock file will be updated. Be aware that updating gems can break your application, so only update gems when you have time to test and resolve any issues. You can run bundle outdated to see which gems are available in newer versions. If you want to prevent your fellow developers (or yourself) from accidentally updating gems, you can specify a gem version number for any gem in the Gemfile. The Gemfile gives fine-grained control over rules for updating:
gem 'rails', '4.0.0'

is absolute: only version 4.0.0 will be used is optimistic: any version newer than 4.0.0 will be used is pessimistic

gem 'rails', '>= 4.0.0' gem 'rails', '~> 4.0.0'

Pessimistic versioning needs some explanation. ~> 4.0.0 means use any version greater than 4.0.0 and less than 4.1 (any patch version can be used). ~> 4.0 means use any version greater than 4.0 and less than 5.0 (any minor version can be used). In general, during development we only lock down any gem versions in the Gemfile if we know newer versions introduce problems. The exception is the Rails gem itself. We always specify the version of Rails we are using for development. Lets take a look at the Gemfile created by the
rails new

command.

Gemfile for a Rails Default Application

Open the Gemfile with your text editor:
source 'https://rubygems.org' # Bundle edge Rails instead: gem 'rails', github: 'rails/rails' gem 'rails', '4.0.0' # Use sqlite3 as the database for Active Record gem 'sqlite3' # Use SCSS for stylesheets

63 gem 'sass-rails', '~> 4.0.0' # Use Uglifier as compressor for JavaScript assets gem 'uglifier', '>= 1.3.0' # Use CoffeeScript for .js.coffee assets and views gem 'coffee-rails', '~> 4.0.0' # See https://github.com/sstephenson/execjs#readme for more supported runtimes # gem 'therubyracer', platforms: :ruby # Use jquery as the JavaScript library gem 'jquery-rails' # Turbolinks makes following links in your web application faster. Read more: https://github.com/rails/turbolinks gem 'turbolinks' # Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder gem 'jbuilder', '~> 1.2' group :doc do # bundle exec rake doc:rails generates the API under doc/api. gem 'sdoc', require: false end # Use ActiveModel has_secure_password # gem 'bcrypt-ruby', '~> 3.0.0' # Use unicorn as the app server # gem 'unicorn' # Use Capistrano for deployment # gem 'capistrano', group: :development # Use debugger # gem 'debugger', group: [:development, :test]

The first line, source 'https://rubygems.org' , directs Bundler to use the rubygems.org server as a source for any gems. Notice that the second uncommented line directs Bundler to use Rails and specifies the version number. Its important to specify which version of Rails we are using. Rails changes frequently and newer versions may not work as we expect. Its also wise to specify the Ruby version were using. This is needed for automated deployment scripts such as those used by Heroku. We can add that to the Gemfile:
ruby '2.0.0'

64

In the Gemfile youll see the gems for a Rails default application, such as sqlite3, which we described earlier. Other gems are commented out (the lines begin with the # character). These are suggestions and we can ignore them or remove them. We wont use a database for our application but well keep the gem 'sqlite3' entry. Configuring Rails for no database is complicated; it is easier to keep the sqlite3 gem and not use it. The gem 'sdoc' line is useful only when using documentation so we can remove it.
rake doc:rails

command to generate API

If you are developing your application on a computer using the Linux operating system, you may need to uncomment and use the statement gem 'therubyracer', platforms: :ruby . Linux doesnt have a built-in JavaScript interpreter so you must install Node.js in your environment or else add the therubyracer gem to each project Gemfile. If you remove the extra clutter in the Gemfile it will look like this:
source 'https://rubygems.org' ruby '2.0.0' gem 'rails', '4.0.0' # Rails defaults gem 'sqlite3' gem 'sass-rails', '~> 4.0.0' gem 'uglifier', '>= 1.3.0' gem 'coffee-rails', '~> 4.0.0' gem 'jquery-rails' gem 'turbolinks' gem 'jbuilder', '~> 1.2'

Adding Gems
Ive identified several gems that will be useful for our tutorial application. I learned of these gems from a variety of different sources: Ruby Toolbox RailsCasts RubyFlow various blog posts example code and starter apps on GitHub recommendations from colleagues

65

Were adding these gems at the beginning of our development process since we already know which gems well need. On a real project, youll often discover useful gems and add them to the Gemfile during the ongoing process of development. Here are gems well add to the Gemfile: activerecord-tableless helps to use Rails without a database bootstrap-sass Twitter Bootstrap for CSS and JavaScript figaro configuration framework gibbon access to the MailChimp API google_drive use Google Drive spreadsheets for data storage high_voltage for static pages like about simple_form forms made easy Well also add utilities that make development easier: better_errors helps when things go wrong quiet_assets suppresses distracting messages in the log Open your Gemfile and replace the contents with the following: Gemfile
source 'https://rubygems.org' ruby '2.0.0' gem 'rails', '4.0.0' # Rails defaults gem 'sqlite3' gem 'sass-rails', '~> 4.0.0' gem 'uglifier', '>= 1.3.0' gem 'coffee-rails', '~> 4.0.0' gem 'jquery-rails' gem 'turbolinks' gem 'jbuilder', '~> 1.2' # learn-rails gem 'activerecord-tableless' gem 'bootstrap-sass', '~> 2.3.2.2' gem 'figaro' gem 'gibbon' gem 'google_drive' gem 'high_voltage' gem 'simple_form', '>= 3.0.0.rc' group :development do

66 gem 'better_errors' gem 'quiet_assets' end

Notice that weve placed the better_errors and quiet_assets gems inside a group. Specifying a group for development or testing ensures a gem is not loaded in production, reducing the applications memory footprint. Rails let you specify groups for development, test, or production. Each time you edit the Gemfile, run
bundle install

and restart your web server.

Install the Gems

Now that youve edited the Gemfile, you need to install the required gems on your computer:
$ bundle install

Every time you add gems to your Gemfile, youll run bundle install . It downloads the gems you need from the rubygems.org server and saves them to a hidden directory that is managed by the RVM gemset youve specified. Well see all the gems and their dependencies:
Fetching gem metadata from https://rubygems.org/........ Fetching gem metadata from https://rubygems.org/.. Resolving dependencies... Using rake (10.0.4) Using i18n (0.6.4) Installing minitest (4.7.4) . . . (many more gems not shown... you get the idea) . . . Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.

You can use your text editor to view the contents of Gemfile.lock and you will see a detailed listing of every gem and each dependency, with version numbers. Theres no reason to edit a Gemfile.lock file; if it is ever in error, delete it and run bundle install to recreate it.

67

Run

gem list

to see all the gems that are loaded into the development environment:

$ gem list

The list of gems loaded in the environment and specified in the Gemfile.lock will be the same. Heres how it works. RVM makes a place for the gems to be stored (the RVM gemset); the Gemfile lists the gems you want to use; bundle install reads the Gemfile and installs the gems into the RVM gemset; the Gemfile.lock file records dependencies and version numbers; and gem list shows you the gems that are in the gemset and available for use.

Git
Lets commit our changes to the Git repository and push to GitHub.
$ git add -A $ git commit -m "add gems" $ git push origin master

After your first use of If you get a message:

git push origin master

, you can use the shortcut

git push

fatal: Not a git repository (or any of the parent directories): .git

It indicates you are in a folder that has not been initialized with Git. You are probably not in your project directory. Use the Unix command pwd to see where you are. If you get a message:
fatal: 'origin' does not appear to be a git repository fatal: The remote end hung up unexpectedly

It shows that you cant connect to GitHub to push the changes. To investigate, enter:
$ git remote show origin

It is not absolutely necessary to use GitHub for this tutorial. Were only using it so youll be familiar with the workflow of professional development. Were ready to configure the application.

68

Chapter 12

Configure
In our tutorial application, well need to save an account name and password for a Gmail account so we can send email from the application and save data to a Google Drive spreadsheet. Well also need to store an API key to access MailChimp, which well use to add visitors email addresses to a mailing list. Rails is known for its convention over configuration guiding principle. As applied, the principle reduces the need for many configuration files. Its not possible to eliminate all configuration files, however. Many applications require configuration of settings such as email account credentials or API keys for external services. Remote Git repositories such as GitHub are a place to store and share code. But you shouldnt save email account credentials or private API keys to a shared Git repository where others can see them. Operating systems (Linux, Mac OS X, Windows) provide mechanisms to set local environment variables, as does Heroku and other deployment platforms. Environment variables can be accessed from Rails applications and provide an ideal place to set configuration settings that must remain private. With a bit of Unix skill, most developers can set environment variables using the Unix shell. For applications from the RailsApps project, we take a hybrid approach and use the figaro gem that lets us set environment variables from the Unix shell or from a simple configuration file. For our tutorial, well show how to set up configuration settings using the figaro gem. You can read the article Rails Environment Variables if youd like learn about the figaro gem or explore other approaches.

Configuration File
The tutorial application uses the figaro gem to set environment variables. Weve already installed the figaro gem in the Gemfile and run bundle install . The figaro gem uses a generator to set up the necessary files. Run:
$ rails generate figaro:install

Rails provides the rails generate command to be used by gems that need to modify Rails files or install configuration files.

69

Using the rails generate command, the figaro gem generates a config/application.yml file and lists it in your .gitignore file. The .gitignore file prevents the config/application.yml file from being saved in the Git repository so your credentials are kept private. The figaro generator will create a file with some example entries which we will replace. Well set credentials for your Gmail and MailChimp accounts. Use your text editor to replace the file config/application.yml with this:
# Add account credentials and API keys here. # See http://railsapps.github.io/rails-environment-variables.html # This file should be listed in .gitignore to keep your settings secret! # Each entry sets a local environment variable and overrides ENV variables in the Unix shell. GMAIL_USERNAME: Your_Username GMAIL_PASSWORD: Your_Password MAILCHIMP_API_KEY: Your_MailChimp_API_Key MAILCHIMP_LIST_ID: Your_List_ID DOMAIN_NAME: example.com OWNER_EMAIL: [email protected]

Replace the placeholders in the config/application.yml file with real credentials. Make sure there is a space after each colon and before the value for each entry. Also, if any value contains non-alphanumeric characters (punctuation marks), you must enclose the value in quotation marks. If you dont, youll get an error when starting the web server. All configuration values in the config/application.yml file are available anywhere in the application as environment variables. Well use the environment variables to configure the tutorial application to send email.

Gmail
For the Gmail username and password, enter the credentials you use to log in to Gmail when you check your inbox. If you dont have a Gmail account, you can sign up for an account with Mandrill instead and follow instructions in the article Send Email with Rails.

MailChimp
When visitors sign up to receive a newsletter, well add them to a MailChimp list. Add an environment variable for the MailChimp API key: MAILCHIMP_API_KEY . Log in to MailChimp to get your API key. Click your name at the top of the navigation menu, then click Account

70

Settings. Click Extras, then API keys. You have to generate an API key; MailChimp doesnt create one automatically. Youll need to create a MailChimp mailing list in preparation for our Mailing List chapter. Have you already created a MailChimp mailing list? If not, the MailChimp Lists page has a button for Create List. The list name and other details are up to you. Well need the MAILCHIMP_LIST_ID for the mailing list youve created. To find the list ID, on the MailChimp Lists page, click the down arrow for a menu and click Settings. At the bottom of the List Settings page, youll find the unique ID for the mailing list.

Domain Name
If you already have a custom domain name youll use when you deploy the application, you can replace example.com now. If not, leave example.com in place for now. Later, if you follow the tutorial to deploy the application to Heroku, youll replace example.com with the unique name youve given your application on Heroku. Youll have to wait until you deploy to know the name youll use on Heroku. Well use the domain name variable when we configure email for delivery in production.

Owner Email
Youll send email messages to this address when a visitor submits a contact request form. Replace [email protected] with an email address where you receive mail.

Configure Email
Email messages are visible in the console and the log file when you test the application. If you dont want to actually send email, you can skip this step. But its more fun when your application can actually send email. You can learn more in the article Send Email with Rails.

Connect to an Email Server

Web servers dont send email. Our Rails application has to connect to an email server (also known as a mail transfer agent or mail relay). In the early days of the Internet, an experienced system adminstrator could set up an SMTP server to distribute email. Now, because of efforts to reduce spam, it is necessary to use an established email service to ensure deliverability. For convenience during development, you can use your own Gmail account. In production, for high volume transactional email and improved deliverability, its best to use a service such as Mandrill or Mailgun. See the article Send Email with Rails.

71

We need to configure Rails so the application can connect with an email server. For our tutorial application, well connect to Gmail to send email. In the file config/environments/development.rb, near the end of the file, find the statement:
config.assets.debug = true

Immediately following, add this:

config.action_mailer.smtp_settings = { address: "smtp.gmail.com", port: 587, domain: ENV["DOMAIN_NAME"], authentication: "plain", enable_starttls_auto: true, user_name: ENV["GMAIL_USERNAME"], password: ENV["GMAIL_PASSWORD"] }

Its important to add these changes in the body of the configuration file, before the end keyword. The order isnt important but dont add the configuration statements after the keyword.

end

Notice that we are using the ENV["GMAIL_USERNAME"] and ENV["GMAIL_PASSWORD"] environment variables that we set in the config/application.yml file. We could hard code a username and password here but that would expose confidential data if your GitHub repository is public. Using environment variables from the config/application.yml file keeps your secrets safe.

Perform Deliveries in Development

If you want to send real messages when you test the application in development mode, modify the file config/environments/development.rb. After the code you just added, add the statement:
# Send email in development mode. config.action_mailer.perform_deliveries = true

This changes the configuration to send email when youre working on the application. Make sure any code youve added to the config/environments/development.rb file is placed before the final end keyword. If you add code after the final end keyword, your application will fail with errors when you start the web server.

72

Later, after we add a contact form to the tutorial application, the application will be ready to send email messages.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "add configuration" $ git push

Were ready to create a home page for the application.

73

Chapter 13

Static Pages and Routing

A Rails application can deliver static web pages just like an ordinary web server. The pages are delivered fast and no Ruby code is required. Well look at simple static pages and learn about Rails routing before we explore the complexities of dynamic web pages in Rails.

Add a Home Page

Make sure you are in your project directory. Start the application server:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Youll see the Rails default information page. Use your text editor to create and save a file public/index.html:
<h1>Hello World</h1>

Refresh the browser window and youll see the Hello World message. The Rails application server looks for any pages in the public folder by default. If no filename is specified in the URL, the server will attempt to respond with a file named index.html. This is a convention that dates to 1993; if no filename was specified, one of the first web servers ever built (the NCSA httpd server) would return a list of all files in the directory, unless a file named index.html was present. Since then, index.html has been the default filename for a home page.

Routing Error
What happens when no file matches the requested web address? Enter the URL http://localhost:3000/about.html in your browser. Youll see an error page that shows a routing error.

74

Add an About Page

Use your text editor to create and save a file public/about.html:
<h1>About</h1>

Visit the URL http://localhost:3000/about.html in your browser. Youll see the new About page. By the way, youve just done test-driven development (TDD).

Introducing TDD
With test-driven development, a developer tests behavior before implementing a feature, expecting to see an error condition. Then the developer implements the feature and sees a successful result to the test. Thats exactly what youve done, in the simplest way. Beginners tend to think TDD is scary and complicated. Now that youve experienced a simple form of TDD, maybe it wont be intimidating. Real TDD means writing tests in Ruby before implementing features, but the principle is the same.

Introducing Routes
The guiding principle of convention over configuration governs Rails routing. If the web browser requests a page named index.html, Rails will deliver the page from the public folder by default. No configuration is required. But what if you want to override the default behavior? Rails provides a configuration file to control web request routing. Remove the public/index.html file:
$ rm public/index.html

Now lets set the About page as the home page. Open the file config/routes.rb. Remove all the comments and replace the file with this:
LearnRails::Application.routes.draw do root to: redirect('/about.html') end

75

Notice the name of the application LearnRails is included in the file. When you created the application, I suggested you use the name learn-rails . If you gave the project a different name, youll have to modify the config/routes.rb file accordingly. This snippet of Rails routing code takes any request to the application root (http://localhost:3000/) and redirects it to the about.html file (which is expected to be found in the public folder). There is no need to restart your application server to see the new behavior. If you need to start the server:
$ rails server

Visit the page http://localhost:3000/. Youll see the About page. Youve just seen an example of Rails magic. Some developers complain that the convention over configuration principle is black magic. Its not obvious why pages are delivered from the public folder; it just happens. If you dont know the convention, you could be left scratching your head and looking for the code that maps http://localhost:3000/ to the public/index.html file. The code is buried deep in the Rails framework. However, if you know the convention and the technique for overriding it, you have both convenience and power at your disposal.

Using the About Page

Weve created an About page so we can learn about routing. For the next chapter, well use the static About page to investigate how a web application works. Later in the tutorial well create a new About page using a different approach.

76

Chapter 14

Request and Response

Youve configured the tutorial application, created static pages, and seen the magic of Rails routing. In this chapter, well investigate the web request-response cycle and look at the model-viewcontroller design pattern so youll be prepared to build a dynamic home page.

Investigating the Request Response Cycle

Remember, at its core, the World Wide Web is nothing more than web browsers that request files from web servers. Web browsers make requests. A web server responds to a request by sending an HTML file. Depending on the headers in the HTML file, the web browser may make additional requests and get additional CSS, JavaScript, and image files. The beauty and simplicity of the World Wide Web architecture, as conceived by Tim Berners-Lee in 1990, is that there is nothing but a request from a web browser and a response from a web server. Some web pages now include streaming video, or music, requiring an open pipe between the web server and the web browser, but even so, an initial requestresponse cycle delivers the page that sets up the stream. We can reduce the mystery of how the web works to its simplest components when we investigate the request-response cycle. Well see that everything that happens in a web application takes place within the flow of the request-response cycle. Lets look at the request-response cycle.

Inside the Browser

We can see the actual request, and the actual response, by using the diagnostic tools built into the web browser.

77

Start the application server if it is not already running:

$ rails server

Developers use various web browsers during development. Ill provide instructions for Chrome. Some developers prefer Mozilla Firefox and Apple Safari but Google Chrome is the most popular. Even if you prefer one of the others, try this in Chrome, so you can follow along with the text. Start our investigation by putting Chrome into Incognito Mode with Command-Shift-N. Alternatively, you can clear the browser cache. This clears any files that were previously cached by the browser. The Developer Tools View is your primary diagnostic tool for front-end (browser-based) development, including CSS and JavaScript. In Chrome on Mac OS X, press Command-Option-I to open the Developer Tools View in a section of the browser window. Alternatively, you can find the menu item under View/ Developer/Developer Tools. In Chrome on Windows or Linux platforms, press Shift-Ctrl-I or select Menu/Tools/ Developer Tools. Select the Network tab in the Developer Tools View. Initiate the request-response cycle by visiting the About page at http://localhost:3000/ about.html. In the Developer Tools View, youll see files received by the browser from the web server. There is only one: about.html. This is the file that the browser evaluates to display a web page.

78

Click the about.html file icon. Then click the tab Headers. The diagnostic window shows the entire request sent to the server and the entire response received by the browser.

79

The request is composed of: request URL (http://localhost:3000/about.html) request method (GET) request headers (including cookies and User Agent identifer) The response is composed of status code (200 OK or 304 Not Modified) response headers (including date/time and server identifier) HTML You can see the HTML sent to the browser by clicking the Preview or Response tabs in the diagnostic view. Now try requesting the home page by entering the URL http://localhost:3000/.

80

Youll see the server returns two files. The first, localhost, contains a redirect code 301 Moved Permanently that tells the browser to request the about.html file. The second file is the about.html file. You may see the status code 200 OK the first time the file is requested. On subsequent requests, youll see the 304 Not Modified code, indicating that the file hasnt changed and the browser should use the file that has been previously cached. Heres the point of the exercise: The browsers diagnostic view shows all the data exchanged between the browser and server. Youre looking at everything that passes through the plumbing.

Inside the Server

The browsers diagnostic view doesnt show you what happens on the server. For that, go to the server logs or the console window.
Started GET "/" for 127.0.0.1 at ...

Notice how the diagnostic messages in the console window match the headers in the browser diagnostic view. The browsers Request Method:GET matches the servers Started GET. The browsers Request URL:http://localhost:3000/ matches the servers / for 127.0.0.1 (localhost is at IP address 127.0.0.1). Notice there are no console log messages for pages delivered from the public folder. Soon well see much more in the console window, after weve built a dynamic web page that is assembled by the application server.

Model View Controller

Now that weve investigated the request-response cycle, lets dig deeper to understand what happens inside the Rails application server in response to a browser request. Here is a diagram that shows what happens in the server during the request-response cycle.

81

You learned earlier that, from the perspective of a software architect, Rails is organized to conform to the modelviewcontroller software design pattern. This enforces separation of concerns to keep code manageable and organized. The MVC design pattern is optimal for web applications and is a central organizing principle for Rails. The MVC design pattern originated in the design of desktop applications. Model classes manipulated data; view classes created the user interface; and a controller class responded to user interaction. Some computer scientists feel the architecture of web applications doesnt quite match the original MVC design pattern of desktop applications. We can see the reason for the quibble in the next diagram. The diagram shows the MVC architecture as part of the Rails software stack. At the base of the stack is the web browser. A request flows upward through the layers and encounters the router which dispatches the request to an appropriate controller. In a Rails application, there is a single routing file, config/routes.rb, and multiple controllers, models, and views.

Considering the importance of the router, perhaps we should call our Rails architecture the RCMV, or Routing-Controller-Model-View, pattern. Despite the quibble about nomenclature, the architecture is well understood and used by all Rails developers.

82

Heres the step-by-step walk-through of what happens. When the web browser makes a request, a router component will check the config/routes.rb file and determine which controller should handle the request, based on the web address and HTTP protocol. The controller will obtain any needed data from a model. After obtaining data, the controller will render a response combining data from the model with a view component that provides markup and layout. The response is an HTML file that the controller assembles for the browser to display. The model, view, and controller are files you create containing Ruby code. Each file has a certain structure and syntax based on foundation model, view, and controller classes defined in the Rails framework. The model, view, and controller classes you create will inherit behavior from parent classes that are part of the framework, so you will have less code to write yourself. In most Rails applications, a model obtains data from a database, though some models obtain data from a remote connection to another server. For example, a User model might retrieve a user name and email address from a local database. A User model could also obtain a users recent tweets from Twitter or a users hometown from Facebook. The controller can obtain data from more than one model if necessary. A controller can have more than one action. For example, a User controller might have actions to display a list of users, or add or delete a user from a list. The config/routes.rb file matches a web request to a controller action. In the software architects terminology, each action is a method of the controller class. We use the terms action and method interchangeably when we talk about a Rails controller; to be precise, controller actions are implemented as methods. In practice, Rails developers try to limit controllers to seven standard actions: index , show , new , create , edit , update and destroy actions. A controller that offers these actions is said to be RESTful (a term that refers to representational state transfer, another software design abstraction). Its not important to understand the abstract principles of RESTful design; recognizing the term and knowing that Rails controllers have seven standard actions is sufficient for beginners. A view file combines Ruby code with HTML markup. Typically there will be a view file associated with each controller action that displays a page. An index view might show a list of users. A show view might provide details of a users profile. View files look much like ordinary HTML files but typically contain data in the form of Ruby variables. Often youll see Ruby statements such as blocks that iterate through lists to create tables. Following the separation of concerns principle, it is considered good practice to limit Ruby code in view files to only displaying data; anything else belongs in a model. Not every controller action has its own view file. In many controllers, on completion, the destroy action will redirect to the index view, and create will redirect to either show or new . This conceptual overview will be easier to grasp when you actually see the code for a model, view, and controller. Well create model, view, and controller files in the next chapter.

83

Remove the About Page

Weve been using the static About page to investigate the request-response cycle. Were done, so delete the file public/about.html:
$ rm public/about.html

Make sure youve removed the public/index.html file as suggested earlier:

$ rm public/index.html

Now well look at ways to implement the home page using the full power of Rails.

84

Chapter 15

Dynamic Home Page

Earlier, we saw how Rails can deliver simple static web pages. Here well build a dynamic home page, illustrating basic concepts youll need to understand Rails. Well use the model-view-controller design pattern as we build our new home page.

User Story
Well plan our work with a user story:
*Birthday Countdown* As a visitor to the website I want to see the owner's name I want to see the owner's birthdate I want to see how many days until the owner's next birthday In order to send birthday greetings

This silly home page will help us explore Rails and learn about the Ruby language. Our goal is to build a practical web application that you can really use. Later well replace this silly home page with a useful web page that encourages visitors to sign up for a mailing list.

The Name Game

Much of the art of programming lies in choosing suitable names for our creations. Well need a model as a source for data about the site owner. Choosing the most obvious name, well call it the Owner model: Owner the file will be app/models/owner.rb What about a name for the controller that will render our home page? How about Home controller or Welcome controller? Those names are acceptable. But if we consider our user story, the name Visitors controller is best. A visitor is the actor, so Visitors controller is appropriate:

85

VisitorsController the file will be app/controllers/visitors_controller.rb Later well see this is a good choice because well create a Visitor model to handle data about the website visitor. In Rails, there is often a model with the same name as a controller (though a controller can use data from multiple models).

Naming Conventions
Rails is picky about class names and filenames. Thats because of the convention over configuration principle. By requiring certain naming patterns, Rails avoids complex configuration files. Before we look at class and filename conventions, heres a note about typographic terminology: a string is a sequence of characters youre looking at an example of lowercase strings separated by spaces (words!) titlecase means there is an Initial Capital Letter in a string CamelCase contains a capital letter in the middle of a string snake_case combines words with an underscore character instead of a space When you write code, youll follow rules for class names:
class Visitor < ActiveRecord::Base

the model class name is capitalized and singular for a controller, combine a pluralized

class VisitorsController < ApplicationController

model name with Controller in CamelCase Here are the rules for filenames. They are always lowercase, with words separated by underscores (snake_case): the model filename matches the model class name, but lowercase, for example app/ models/visitor.rb the controller filename matches the controller class name, but snake_case, for example app/controllers/visitors_controller.rb the views folder matches the model class name, but plural and lowercase, for example app/views/visitors At first the rules may seem arbitrary, but with experience they will make sense. The rule about no capital letters or spaces in filenames has its origins in computer antiquity. If you stray from these naming conventions, youll encounter unexpected problems and frustration.

86

Routing
Well create the route before we implement the model and controller. Open the file config/routes.rb. Replace the contents with this:
LearnRails::Application.routes.draw do root to: 'visitors#new' end

Any request to the application root (http://localhost:3000/) will be directed to the VisitorsController new action. Notice that the name of the application is contained in the config/routes.rb file. Earlier, I recommended using learn-rails as the name of the application so you will not need to change the code here. Dont be overly concerned about understanding the exact syntax of the code. It will be become familiar soon and you can look up the details in the reference documentation, RailsGuides: Routing from the Outside In. In general, when you change a configuration file you must restart your application server. However, the config/routes.rb file is an exception. You dont need to restart the server after changing routes. If you need to start the server:
$ rails server

Visit the page http://localhost:3000/. Youll see an error message because we havent implemented the controller. The error message, uninitialized constant VisitorsController, means Rails is looking for a VisitorsController and cant find it.

Model
Most Rails models obtain data from a database. When you use a database, you can use the rails generate model command to create a model that inherits from the ActiveRecord class and knows how to connect to a database. Our tutorial application doesnt need a database. Instead of inheriting from ActiveRecord, we create a Ruby class with methods that return the owners name, birthdate, and days remaining until his birthday. This simple class provides an easy introduction to Ruby code. Create a file app/models/owner.rb:

87 class Owner def name name = 'Foobar Kadigan' end def birthdate birthdate = Date.new(1990, 12, 22) end def countdown today = Date.today birthday = Date.new(today.year, birthdate.month, birthdate.day) if birthday > today countdown = (birthday - today).to_i else countdown = (birthday.next_year - today).to_i end end end

This is your first close look at Ruby code. The oddest thing youll see is the owners name, Foobar Kadigan. Everything else will make sense with a bit of explanation. Keep in mind that we are using a text file to create an abstraction that we can manipulate in the computers memory. Software architects call these abstractions objects. In Ruby, everything we create and manipulate is an object. To distinguish one object from another, we define it as a class, give it a class name, and add behavior in the form of methods. The first line class Owner defines the class and assigns a name. At the very end of the file, the end keyword completes the class definition. We define three methods, starting with
def name def

(for method definition) and ending with

end

end

def birthdate def countdown

end end

Each method contains simple Ruby code that assigns data to a variable. Later, well retrieve the data for use in our view file by instantiating the class and calling a method. Dont be discouraged by the software architects terminology; the concepts are simple and well soon see everything in action. Ruby makes it easy for a method to return data when called; the value assigned by the last statement will be delivered when the method is called.

88

Looking more closely at the Ruby code inside the method definitions, youll see Ruby uses the = (equals) sign to assign values to a variable. The variable is named on the left side of the equals sign; a value is assigned on the right side. We call the equals sign an assignment operator. We can assign any value to a variable, including a string (a series of characters that can be a word or name) such as Foobar Kadigan. Ruby recognizes a string when characters are enclosed in single or double quotes. Not surprisingly, a number also can be assigned to a variable, either a whole number (an integer) or a decimal fraction (a float). More interestingly, any Ruby object can be assigned to a variable. That helps us move around any object very easily, giving us access to the objects class methods anywhere we use the variable. We can create our own objects, as we have by creating the Owner class. Or we can use the library of objects that are supplied with Ruby. Rubys prefabricated objects are defined by the Ruby API (application programming interface); essentially the API is a catalog of prebuilt classes that are building blocks for any application. The Rails API gives us additional classes that are useful for web applications. Learning the syntax of Ruby code gets you started with Ruby programming; knowing the API classes leads to mastery of Ruby. The Date class is provided by the Ruby API. It is described in the Ruby API reference documentation. The Date class has a Date.new method which instantiates (creates) a new date when supplied with year, month, and day parameters. You can see this syntax when we assign Date.new(1990, 9, 22) to the birthdate variable. Our
countdown

method contains the most complex code in the class.

First, we set a variable today with todays date. The Date.today method creates an object that represents the current date. When the Date.today method is called, Ruby gets the current date from the computers system clock. Next we create a birthday variable and assign a new date that combines todays year with the month and day of the birthdate . This gives us the date of Foobar Kadigans birthday this year. The Date class can perform complex calendar arithmetic. The variables birthdate and today are instances of the Date class. We can use a greater-than operator to determine if Foobar Kadigans birthday is in the future or the past. The if ... else ... end structure is a conditional statement. If the birthday is in the future, we subtract today from birthday to calculate the number of days remaining until the owners birthday, which we assign to the countdown variable. If the birthday has already passed, we apply a next_year method to the birthday to get next years birthday. Then we subtract today from birthday.next_year to calculate the number of days remaining until the owners birthday, which we assign to the countdown variable. The result might be fractional so we use the utility method to_i to convert the result to a whole number (integer) before assigning it to the countdown variable.

89

This shows you the power of programming in Ruby. Notice that I needed 16 paragraphs and over 600 words to explain 15 short lines of code. We used only seven Ruby abstractions (class definition, method definition, variable assignment, String class, Date class, conditional statement, and integer conversion) but they represent thousands of lines of code in the Ruby language implementation. With knowledge of Ruby syntax and the Ruby API, a few short lines of code in a text file gives us amazing ability. In an upcoming chapter, well look more closely at the syntax and keywords of the Ruby language. But without knowing more than this, we can build a simple web application. Lets see how we can put this functionality to use on a web page.

View
The Owner model provides the data we want to see on the Home page. Well create the markup and layout in a View file and add variables that present the data. View files go in folders in the app/views/ directory. In a typical application, one controller can render multiple views, so we make a folder to match each controller. You can make a new folder using your file browser or text editor. Or use the Unix mkdir command:
$ mkdir app/views/visitors

Create a file app/views/visitors/new.html.erb:

<h3>Home</h3> <p>Welcome to the home of <%= @owner.name %>.</p> <p>I was born on <%= @owner.birthdate %>.</p> <p>Only <%= @owner.countdown %> days until my birthday!</p>

Weve created a visitors/ folder within the app/views/ directory. This directory is for any views associated with the Visitors controller. We have only a single new view but if we had more views, theyd go in the app/views/visitors/ folder. We name our View file new.html.erb, adding the .erb file extension so that Rails will use the ERB templating engine to interpret the markup. There are several syntaxes that can be used for a view file. In this tutorial, well use the ERB syntax that is most commonly used by beginners. Some experienced developers prefer to add gems that provide the Haml or Slim templating engines. As you might guess, a View that uses the Haml templating syntax would be named new.html.haml. Our HTML markup is minimal, using only the <h3> and <p> tags. The only ERB markup we add are the <%= ... %> delimiters. This markup allows us to insert Ruby code which will be

90

replaced by the result of evaluating the code. In other words, on the page as Foobar Kadigan.

<%= @owner.name %>

will appear

You may have noticed that we refer to the Owner model with the variable @owner . It will be clear when we create the Visitors controller why we use this syntax (a variable name that begins with the @ character is called an instance variable). Obviously, if all we wanted to do was include the owners name on the page, it would be easier to simply write the text. The Rails implementation becomes useful if the name is retrieved from a database or created programmatically. We can better see the usefulness of the Owner model when we look at the use of <%= @owner.countdown %> . There is no way to display a calculation using only static HTML, so Rails gives us a way to display the birthday countdown calculation. If youre a programmer, you might wonder why we only output the variable on the page. Since we can use ERB to embed any Ruby code, we could perform the calculation right on the page by embedding <%= (Date.new(today.year, @owner.birthdate.month, @owner.birthdate.day) - Date.today).to_i %> . If youve used JavaScript or PHP, you may have performed calculations like this, right on the page. Rails would allow us to do so, but the practice violates the separation of concerns principle that encourages us to perform complex calculations in a model and only display data in the view. Before we can display the home page, we need to create the Visitors controller.

Controller
The Visitors controller is the glue that binds the Owner model with the VisitorsController#new view. Note: When we refer to a controller action, we use the notation VisitorsController#new, joining the controller class name with the action (method) that renders a page. The # character is only a documentation convention. Note: VisitorsController will be the class name and visitors_controller.rb will be the filename. The class name is written in camelCase (with a hump in the middle, like a camel) so we can combine two words without a space. Unix commands get messy when filenames include spaces so we create a filename that combines two words with an underscore. Create a file app/controllers/visitors_controller.rb:
class VisitorsController < ApplicationController def new @owner = Owner.new

91 end end

We define the class and name it class VisitorsController , inheriting behavior from the ApplicationController class which is defined in the Rails API. We only need to define the new method. We create an instance variable named @owner and assign an instance of the Owner model. Any instance variables (variables named with the @ character) will be available in the corresponding view file. If we dont instantiate the Owner model, well get an error when the controller new action attempts to render the view because we use the @owner instance in the view file. Keep in mind the purpose of the controller. Each controller action (method) responds to a request by obtaining a model (if data is needed) and rendering a view. Youve already created a view file in the app/views/visitors folder. The new action of the VisitorsController renders the template app/views/visitors/new.html.erb. The new method is deceptively simple. Hidden behavior inherited from the ApplicationController does all the work of rendering the view. We can make the hidden code explicit if we wish to. It would look something like this:
class VisitorsController < ApplicationController def new @owner = Owner.new render 'visitors/new' end end

This is an example of Rails magic. Some developers complain this is black magic because the convention over configuration principle leads to obscurity. Rails often offers default behavior that looks like magic because the underlying implementation is hidden in the depths of the Rails code library. This can be frustrating when, as a beginner, you want to understand whats going on. Revealing the hidden code, we see that invoking the new method calls a render method supplied by the ApplicationController parent class. The render method searches in the app/ views/visitors directory for a view file named new (the file extension .html.erb is assumed by default). The code underlying the render method is complex. Fortunately, all we need to do is define the method and instantiate the Owner model. Rails takes care of the rest.

92

As a beginner, simply accept the magic and dont confound yourself trying to find how it works. As you gain experience, you can dive into the Rails source code to unravel the magic.

Scaffolding
This tutorial aims to give you a solid foundation in basic concepts. The modelviewcontroller pattern is one of the most important. Ive found the best way to understand modelviewcontroller architecture is to create and examine the model, view, and controller files. As you continue your study of Rails, youll find other tutorials that use the scaffolding shortcut. For example, Rails Guides: Getting Started with Rails includes a section Getting Up and Running Quickly with Scaffolding which shows how to use the rails generate scaffold command to create model, view, and controller files in a single operation. Students often use scaffolding to create simple Rails applications. In practice, Ive observed that working Rails developers seldom use scaffolding. Theres nothing wrong with it; it just seems that scaffolding doesnt offer much that cant be done as quickly by hand.

Test the Application

Weve created a model, view, and controller. Now lets run the application. Enter the command:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Youll see our new home page.

93

Its a very simple web page but it uses Ruby to calculate the countdown to the birthday. And the underlying code conforms to the conventions and stucture of Rails.

Git
At this point, you might have the Rails server running in your console window. Were going to run a git command in the console now. You might think you have to enter Control-c to shut down the server and get the command prompt. But thats not necessary. You can open more than one console window. Your terminal application lets you open multiple tabs so you can easily switch between windows without using a lot of screen real estate. If you havent tried it, now is a good time. It is convenient to have a console window open for the server and another for various Unix commands. Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "dynamic home page" $ git push

Now lets take a look at troubleshooting.

94

Chapter 16

Troubleshoot
In the last chapter, we built a dynamic home page and learned about the modelviewcontroller architecture of Rails. There was a lot to learn, but the code was simple, and I hope it worked the first time you tried it. Before we do any more work on our tutorial application, we need to learn about troubleshooting and debugging. As a software developer, youll spend a lot of time with code that doesnt work. Youll need tools and techniques to diagnose problems.

Git
In this chapter well make changes to the application just for troubleshooting. Before you get started, make sure the work youve done is committed to your git repository. Use the git status command to check:
$ git status

You should see:

# On branch master nothing to commit (working directory clean)

If git status reports any uncommitted changes, go back to the last step in the previous chapter and commit your work to the git repository before continuing. At the end of this chapter, were going to throw away the work weve done in this chapter. We dont want to accidentally throw away work from the previous chapter so make sure it is committed to the repository.

Interactive Ruby Shell

There will be times when you want to try a snippet of Ruby code just to see if it works. Your tool will be IRB, the Interactive Ruby Shell. IRB is a Ruby interpreter that runs from the command line. It executes any Ruby code and provides an immediate response, allowing you to experiment in real-time.

95

Lets try it.

$ irb 2.0.0p0 :001 >

The command irb launches the program and displays a prompt that show your Ruby version, a line number, and an arrow. If you enter a valid Ruby expression, the interpreter will display the result of evaluating the expression. Try simple arithmetic:
2.0.0p0 :001 > n = 2 => 2 2.0.0p0 :002 > n + 2 => 4

Wow! You are using your computer for simple math. Maybe you can delete the calculator app from your phone. IRB will evaluate any Ruby expression and helps you quickly determine if syntax and logic is correct.

IRB for Blocks of Code

At first glance, it appears IRB works on just one line of code. Actually, IRB can handle multiple lines of code. Try it:
2.0.0p0 => 10 2.0.0p0 2.0.0p0 2.0.0p0 2.0.0p0 2.0.0p0 big => nil 2.0.0p0 :001 > n = 10 :002 > if n < 10 :003?> puts "small" :004?> else :005 > puts "big" :006?> end

:007 >

Here we set n = 10 and then enter a conditional statement line-by-line. After we enter the final end , IRB interprets the code and outputs the result. Youll often enter more than one line of code in IRB. If you find yourself frustrated because youve entered typos and had to enter the same code repeatedly, you can use IRB to load code youve saved in a file:

96 2.0.0p0 :001 > load './mytest.rb'

Quitting IRB
It can be very frustrating to find you are stuck inside IRB. Unlike most shell commands, you cant quit with Control-c. Enter Control-d or type exit to quit IRB:
$ irb 2.0.0p0 :001 > exit

Learn More About IRB

Heres an entertaining way to learn about IRB: Whys (Poignant) Guide to Ruby Heres a more conventional way to learn about IRB: The Pragmatic Programmers Guide

Beyond IRB
If you ask experienced Rails developers for help with IRB, theyll often recommend you switch to Pry. Pry is a powerful alternative to the standard IRB shell for Ruby. As you gain experience, you might take a look at Pry to see what the enthusiasm is all about. But for now, as a beginner trying out a few lines of Ruby code, theres no need to learn Pry.

Rails Console
IRB only evaluates expressions that are defined in the Ruby API. IRB doesnt know Rails. Itd be great to have a tool like IRB that evaluates any expression defined in the Rails API. The tool exists; its called the Rails console. It is particularly useful because it loads your entire Rails application. Your application will be running as if the application was waiting to respond to a web request. Then you can expose behavior of any pieces of the web application.
$ rails console Loading development environment (Rails 4.0.0) 2.0.0p0 :001 >

97

The Rails console behaves like IRB but loads your Rails development environment. The prompt shows it is ready to evaluate an expression. Lets use the Rails console to examine our Owner model:
2.0.0p0 :001 > myboss = Owner.new => #<Owner:0x007fe885163aa8>

Weve created a variable named myboss and created a new instance of the Owner class. The Rails console responds by displaying the unique identifier it uses to track the object. The identifier is not particularly useful, except to show that something was created. If youre unsure about the difference between an instance and a class, weve just seen that we can make one or more instances of an object by calling the Owner.new method. When we specify the Owner class, the class definition is loaded into the computers working memory (our development environment) from the class definition file on disk. Then we can use the Owner.new method to make one or more instances of the Owner class. Each instance is a unique object with its own data attributes but the same behavior as other objects instantiated from its class. Lets assign the name of our boss to a variable called
2.0.0p0 :002 > name = myboss.name => "Foobar Kadigan"
name

Our variable myboss is an instance of an by returning the owners name.

Owner

class so it responds to the method

Owner.name

We want to show respect to our boss so well perform some string manipulation:
2.0.0p0 :003 > name = 'Mr. ' + name => "Mr. Foobar Kadigan"

Were done for now. When we quit the Rails console or shut down the computer the Owner class definition remains stored on disk but the instances disappear. The bits that were organized to create the variable name will evaporate into the ether. Actually, the bits are still there, in the form of logic states in the computers chips, but they have no meaning until another program uses them. Enter Control-d or type
exit

to quit the Rails console.

You wont use the Rails console often but it is important to know it is available.

98

Rails Logger
As you know, a Rails application sends output to the browser that makes a web request. On every request, it also sends diagnostic output to the server log file. Depending on whether the application is running in the development environment or in production, the log file is here: log/development.log log/production.log In development, everything written to the log file appears in the console window after you run the rails server command. Scrolling the console window is a good way to see diagnostics for every request. Heres what you see when you visit the application home page:
Started GET "/" for 127.0.0.1 at ... Processing by VisitorsController#new as HTML Rendered visitors/new.html.erb within layouts/application (48.8ms) Completed 200 OK in 233ms (Views: 211.5ms | ActiveRecord: 0.0ms)

Heres the best part. You can add your own messages to the log output by using the Rails logger. Lets try it out. Modify the file app/controllers/visitors_controller.rb:
class VisitorsController < ApplicationController def new Rails.logger.debug 'DEBUG: entering new method' @owner = Owner.new Rails.logger.debug 'DEBUG: Owner name is ' + @owner.name end end

Visit the home page again and youll see this in the console output:
Started GET "/" for 127.0.0.1 at ... Processing by VisitorsController#new as HTML DEBUG: entering new method DEBUG: Owner name is Foobar Kadigan Rendered visitors/new.html.erb within layouts/application (0.2ms) Completed 200 OK in 8ms (Views: 4.6ms | ActiveRecord: 0.0ms)

99

If you really needed to do so, you could add a logger statement at every step in the application. You could see how the application behaves, step by step. And you could print the value of every variable at every step. Youll never need diagnostics at this level of detail in Rails, but the logger is extremely useful when you are trying to understand unexpected behavior. Lets add logger statements to the
class Owner def name name = "Foobar Kadigan" end def birthdate birthdate = Date.new(1990, 9, 22) end def countdown Rails.logger.debug 'DEBUG: entering Owner countdown method' today = Date.today birthday = Date.new(today.year, birthdate.month, birthdate.day) countdown = (birthday - today).to_i end end
Owner

model. Modify the file app/models/owner.rb:

We added the

Rails.logger.debug

statement to the

Owner.countdown

method.

Visit the home page and heres what youll see in the console output:
Started GET "/" for 127.0.0.1 at ... Processing by VisitorsController#new as HTML DEBUG: entering new method DEBUG: Owner name is Foobar Kadigan DEBUG: entering Owner countdown method Rendered visitors/new.html.erb within layouts/application (0.3ms) Completed 200 OK in 7ms (Views: 4.2ms | ActiveRecord: 0.0ms)

Youll often need to get inside the model or controller to see whats happening. The Rails logger is the best tool for the job. Here are some tricks for the Rails logger. In a controller, you can use the method Rails.logger (both class and method).
logger

on its own. In a model, you have to write

100

You can use any of the methods logger.debug , logger.info , logger.warn , logger.error , or logger.fatal to write log messages. By default, youll see any of these messages in the development log. Log messages written with the logger.debug method will not be recorded in a production log file. If you want your log messages to stand out, you can add formating code for color:
Rails.logger.debug "\033[1;34;40m[DEBUG]\033[0m " + 'will appear in bold blue'

For more about the Rails logger, see the RailsGuide: Debugging Rails Applications.

Revisiting the Request-Response Cycle

Earlier, when we investigated the request-response cycle, we looked in the server log to see the response to the web browser request. Now, with debug statements in the controller and model, well see messages showing the servers traverse of the model-view-controller architecture.
Started GET "/" for 127.0.0.1 at ... Processing by VisitorsController#new as HTML DEBUG: entering new method DEBUG: Owner name is Foobar Kadigan DEBUG: entering Owner countdown method Rendered visitors/new.html.erb within layouts/application (0.3ms) Completed 200 OK in 5ms (Views: 4.2ms | ActiveRecord: 0.0ms)

Notice how the diagnostic messages in the console window match the headers in the browser diagnostic view. The browsers Request Method:GET matches the servers Started GET. The browsers Request URL:http://localhost:3000/ matches the servers / for 127.0.0.1 (localhost is at IP address 127.0.0.1). The browsers Status Code: 200 matches the servers Completed 200 OK (you might have to clear the browsers cache if the browser is showing 304 Not Modified). We can see evidence of the model-view-controller architecture. Processing by VisitorsController#new shows the program flow entering the controller. Our debug statements show we enter the new method and reveal the value of the Owner name. The next debug statement reveals the flow has passed to the Owner model. A diagnostic message shows the controller has rendered the visitors/new.html.erb view file. Finally, the Completed 200 OK message indicates the response has been sent to the browser, followed by a sequence of CSS and JavaScript files. As we learned, the model-view-controller architecture is an abstract design pattern. Weve seen it reflected in the file structure of the Rails application directory. Now we can see it as activity in the server log.

10

101

The Stack Trace

The Rails logger is extremely useful if you want to insert messages to show program flow or display variables. But there will be times when program flow halts and the console displays a stack trace. Lets deliberately create an error condition and see an error page and stack trace. Modify the file app/controllers/visitors_controller.rb:
class VisitorsController < ApplicationController def new Rails.logger.debug 'DEBUG: entering new method' @owner = Owner.new Rails.logger.debug 'DEBUG: Owner name is ' + @owner.name DISASTER end end

Visit the home page and youll see an error page:

10

102

Youll see this error page because weve installed the better_errors gem. Without the better_errors gem, youd see the default Rails error page which is quite similar. In the console log, the stack trace will show everything that happens before Rails encounters the error:
Started GET "/" for 127.0.0.1 at ... Processing by VisitorsController#new as HTML DEBUG: entering new method DEBUG: Owner name is Foobar Kadigan Completed 500 Internal Server Error in 10ms NameError - uninitialized constant VisitorsController::DISASTER: app/controllers/visitors_controller.rb:7:in `new' . . .

To save space, Im only showing the first line of the stack trace. Ive eliminated about sixty lines from the stack trace. Dont feel bad if your reaction to a stack trace is an immediate, TMI! Indeed, it is usually Too Much Information. There are times when it pays to carefully read through the stack trace line by line, but most often, only the first line of the stack trace is important. In this case, both the error page and the first line of the stack trace show the application failed (barfed) when it encountered an uninitialized constant at line 7 of the app/ controllers/visitors_controller.rb file in the index method. Its easy to find line 7 in the file and see that is exactly where we added a string that Rails doesnt understand. The point of this exercise is to encourage you to read the first line of the stack trace and use it to diagnose the problem. Im always surprised how many developers ignore the stack trace, probably because it looks intimidating.

Raising an Exception
As you just saw, you can purposefully break your application by adding characters that Rails doesnt understand. However, there is a better way to force your program to halt, called raising an exception. Lets try it. Modify the file app/controllers/visitors_controller.rb:
class VisitorsController < ApplicationController def new

10

103 Rails.logger.debug 'DEBUG: entering new method' @owner = Owner.new Rails.logger.debug 'DEBUG: Owner name is ' + @owner.name raise 'Deliberate Failure' end end

You can throw an error by using the raise keyword from the Ruby API. You can provide any error message youd like in quotes following raise . Heres the console log after you try to visit the home page:
Started GET "/" for 127.0.0.1 at ... Processing by VisitorsController#new as HTML DEBUG: entering new method DEBUG: Owner name is Foobar Kadigan Completed 500 Internal Server Error in 22ms RuntimeError - Deliberate Failure: app/controllers/visitors_controller.rb:7:in `new' . . .

Before we continue, lets remove the deliberate failure. Modify the file app/controllers/ visitors_controller.rb:
class VisitorsController < ApplicationController def new Rails.logger.debug 'DEBUG: entering new method' @owner = Owner.new Rails.logger.debug 'DEBUG: Owner name is ' + @owner.name end end

Rails and the Ruby API provide a rich library of classes and methods to raise and handle exceptions. For example, you might want to display an error if Foobar Kadigans birthdate is in the future. Rails gives you various exception handlers to display errors in production so users will see a helpful web page explaining the error.

10

104

Git
Theres no need to save any of the changes we made for troubleshooting. You could go to each file and carefully remove the debugging code you added. But theres an easier way. Check which files have changed:
$ git status # Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: app/controllers/visitors_controller.rb # modified: app/models/owner.rb # no changes added to commit (use "git add" and/or "git commit -a")

Use Git to revert your project to the most recent commit:

$ git reset --hard HEAD

The Git command git reset --hard HEAD discards any changes youve made since the most recent commit. Check the status to make sure:
$ git status # On branch master nothing to commit (working directory clean)

Weve cleaned up after our troubleshooting exercise.

10

105

Chapter 17

Just Enough Ruby

Experienced Rails developers debate whether beginners should study Ruby before learning Rails. By all means, if you love the precision and order of programming languages, dive into the study of Ruby from the beginning. But most people dont delay starting Rails while learning Ruby; realistically, youll retain more knowledge of Ruby if you learn it as you build things in Rails. That is the approach weve taken in this book. Youve already built a simple Rails application and used Ruby as you did so.

Reading Knowledge of Ruby

What you need, more than anything, when you start working with Rails, is reading knowledge of Ruby. With a reading knowledge of Ruby youll avoid feeling overwhelmed or lost when you encounter code examples or work through a tutorial. Later, as you tackle complex projects and write original code, youll need to know enough of the Ruby language to implement the features you need. But as a student, youll be following tutorials that give you all the Ruby you need. Your job is to recognize the language keywords and use the correct syntax when you type Ruby code in your text editor. To that end, this chapter will review the Ruby keywords and syntax youve already learned. And youll extend your knowledge so youll be prepared for the Ruby youll encounter in upcoming chapters.

Ruby Example
To improve your reading knowledge of Ruby, well work with an example file that contains a variety of Ruby expressions. We wont use this file in our tutorial application, so youll delete it at the end of this chapter. But well approach it as real Ruby code, so make a file and copy the code using your text editor. First we have to consider where the file should go. It will not be a model, view, controller, or any other standard component of Rails. Rails has a place for miscellaneous files that dont fit in the Rails API. Well create the file in the lib/ folder. Thats the folder youll use for any supporting Ruby code that doesnt fit elsewhere in the Rails framework.

10

106

Create a file lib/example.rb:

class Example < Object # This is a comment. attr_accessor :honorific attr_accessor :name attr_accessor :date def to_s @name end def initialize(name,date) @name = name @date = date.nil? ? Date.today : date end def titled_name @honorific ||= 'Esteemed' titled_name = "#{@honorific} #{@name}" end def december_birthdays born_in_december = [ ] famous_birthdays.each do |name, date| if date.month == 12 born_in_december << name end end born_in_december end private def famous_birthdays birthdays = { 'Ludwig van Beethoven' => Date.new(1770,12,16), 'Dave Brubeck' => Date.new(1920,12,6), 'Buddy Holly' => Date.new(1936,9,7), 'Keith Richards' => Date.new(1943,12,18) } end end

In some ways, this Ruby code is like a poem from Lewis Carroll:

10

107
'Twas brillig, and the slithy toves Did gyre and gimble in the wabe; All mimsy were the borogoves, And the mome raths outgrabe. "Beware the Jabberwock, my son! The jaws that bite, the claws that catch! Beware the Jubjub bird, and shun The frumious Bandersnatch!"

The poem corresponds to the rules of English syntax but is nonsense. The code follows the rules of Ruby syntax, and unlike the poem, uses meaningful words. But it is unclear how the author intends anyone to use the code. We know that Foobar Kadigan was born in December. Perhaps the code could be used to display a list of famous people who were also born in December. If youre beginning a career as a Rails developer, this wont be the last time you look at code and wonder what the author was intending. In this case, I just want to give you some code that illustrates typical Ruby syntax and structure.

Ruby Keywords
When reading Ruby code, the first challenge is determining which words are Ruby keywords and which were made up by the developer. Code is only strings of characters. But some strings have special meaning for everyone and all others are arbitrary words that only have meaning to an individual developer. As you gain experience, youll recognize Ruby keywords because youve seen them before. Youll also recognize a developers made-up words because of their position relative to other words and symbols. Some made-up words will be obvious because they are just too idiosyncratic to be part of the Ruby language. For example, youll rightly guess that myapp or fluffycat are not part of the Ruby language. If youre reading a Lewis Carroll poem, you could look up words in a dictionary to see if you find them. There is only one way to be sure which words are part of the Ruby language: Check the Ruby API. As an exercise, pick one of the words from the example code that you think might be a Ruby keyword and search the API to find it.

10

108

If you want to be a diligent student, you can check every keyword in the example code to find out whether it is in the Ruby API. It is more practical to learn to recognize Ruby keywords, which well do next.

API Documentation
The Ruby API documentation lists every keyword in the language: Ruby API the official Ruby API apidock.com/ruby Ruby API docs with usage notes

Object-Oriented Terminology
Software architects use a common vocabulary to talk about programming languages: class instance or object method attribute or property inheritance class hierarchy There are three ways to learn what these words mean. You can memorize the definitions. You can write code and intuitively grasp the meanings. Or you can gain an understanding by applying metaphors.

Houses
For example, some programming textbooks attempt to explain a class like this: A blueprint for a house design is like a class definition. All the houses built from that blueprint are objects of that class. A given house is an instance.

Vehicles
Or: The concept of vehicle is like a class. Vehicles can have attributes, like color or number of doors. They have behavior, or methods, like buttons that turn on lights or honk a horn. The concepts of truck or car are also classes, inheriting common characteristics from the concept vehicle. The blue car in your driveway with four doors is an instance of the class car.

10

109

Cookies
I like the cookie metaphor the best. A class definition is like a cookie cutter. Bits in the computer memory are like cookie dough. The cookie cutter makes as many individual cookies as you want. Each cookie is an instance of the cookie class, with the same shape and size as the others. Cookies are objects. You can decorate each cookie with sprinkles, which are attributes that are unique to each instance. Some cookies get red sprinkles, some get green, but the shape remains the same. Running a program is like baking. The cookies change state from raw to cooked. Sticking a toothpick in a cookie is like calling a method. The method returns a result that tells you about the state: Is it done?

Limitations of Metaphors
Metaphors are imperfect. If baking was like running a program, all the cookies would disappear as soon as the oven was turned off. When a software program contains a car model, it doesnt fully model cars in the physical world. It represents an abstraction of characteristics a programmer deems significant. Most classes in software APIs dont model anything in the real world. They typically represent an abstraction, like an Array or a Hash, which inherits characteristics from another abstraction, for example, a Collection. Given the limitations of metaphors, maybe it is easier to simply say that software allows us to create abstractions that are made real and then manipulated and transformed. Terminology such as class and instance describe the abstractions and the relationships among them.

Definitions
Here are definitions for some of the terms we encounter when we consider Rails from the perspective of a software architect: abstraction a concept that has a relationship to other concepts

10

110

class an abstraction that encapsulates data and behavior class definition written code that describes a class instance or object a unique version of a class that exists only while a program is running inheritance a way to make a class by borrowing from another class class hierarchy classes that are related by inheritance method a way to get a result from an object attribute or property data that can be set or retrieved from the object variable a name that can be assigned a value or object expression or statement any combination of variables, classes, and methods that returns a result Some of these terms are abstractions that are made real in the Ruby API (such as class and method); others are just terms that describe code, much like we use terms such as adjective or noun to talk about the grammar of the English spoken language.

Ruby Files
When we write code, we save it in files. Rails provides a directory structure with assigned parking so that Ruby files are automatically loaded when you start the web server. Our miscellaneous example file goes in the lib/ folder. By convention, Ruby files end with the file extension .rb.

Using IRB
In the Troubleshooting chapter, you used IRB (the Interactive Ruby Shell) to try out Ruby code. You can use IRB to try out the example code in the console.

11

111 $ irb 2.0.0p0 :001 > load 'lib/example.rb' => true 2.0.0p0 :002 > ex = Example.new('Daniel',nil) => #<Example:... @name="Daniel", @date=#<Date: 2013-09-03 ((...)>> 2.0.0p0 :003 > list = ex.december_birthdays => ["Ludwig van Beethoven", "Dave Brubeck", "Keith Richards"]

Entering the

load

directive and the filename brings the code into IRB. creates an object from the
Example

The statement The

ex = Example.new('Daniel',nil)

class.

ex.december_birthdays

method returns an array of of names.

Remember you can use Control-d to exit from IRB. Now, for practice, well read the Ruby code.

Classes
You dont have to create classes to program in Ruby. If you only write simple utilities, you wont need classes. Classes are used to organize your code and make your software more modular. For the software architect, classes make it possible to create a structure for complex software programs. To use Rails, youll use the classes and methods that are defined in the Rails API. There is one class at the apex of the Ruby class hierarchy: BasicObject . BasicObject is a very simple class, with almost no methods of its own. The Object class inherits from BasicObject . All classes in the Ruby and Rails APIs inherit behavior from Object . Object provides basic methods such as nil? and to_s (to string) for every class that inherits from Object . We create a class
Example

and inherit from

Object

with the

<

inherits from operator:

class Example < Object . . . end

In Ruby, all classes inherit from the Object class, so we dont need to explicitly subclass from Object as we do here. The example just shows it for teaching purposes. The
end

statement indicates all the preceding code is part of the

Example

class.

11

112

Comments
Ruby ignores everything that is marked as a comment. Use comments for notes to yourself or other programmers.
# This is a comment.

You can also turn code into comments if you dont want the code to run. This is a common trick when you want to turn off some part of your code but you dont want to delete it just yet, because you are trying out alternatives.

Attributes
In Ruby, attributes are also called properties. Classes can have attributes, which we can set and get. That is, we can establish a value for an attribute and retrieve the value by specifying the attribute name. Attributes are a convenient way to push data to an object and pull it out later. Here we use the attr_accessor directive to specify that we want to enable access to name and date attributes.
attr_accessor :honorific attr_accessor :name attr_accessor :date
honorific

If we use attr_accessor to establish attributes, we can use the attribute names as methods. For example, we could write:
ex = Example.new('Daniel',nil) my_name = ex.name

In Ruby, attributes or properties are just a specialized form of methods.

Methods
Classes give organization and structure to a program. Methods get the work done. Any class can have methods. Methods are a series of expressions that return a result (a value). We say methods describe the class behavior.

11

113

A method definition begins with the keyword

def to_s @name end

def

and (predictably) ends with

end

Here we are overriding the

to_s

(to string) method from the parent

Object

class.

Ordinarily, the to_s method returns the objects class name and an object id. Here we will return the string assigned to the variable @name . Most times you wont override the to_s (to string) method. This example shows how you can override any method inherited from a parent class.

Dot Operator
The dot is the method operator. This tiny punctuation symbol is a powerful operator in Ruby. It allows us to call a method to get a result. Sometimes we say we send a message to the object when we invoke a method, implying the object will send a result. We see it in the expressions
date.nil?

and

Date.today

.
String

We can apply method chaining to objects. For example, upcase (among many others). We could write:
nonsense = 'foobar' => "foobar" reversed = nonsense.reverse => "raboof" capitalized = reversed.upcase => "RABOOF"

has methods

reverse

and

It is easier to use method chaining and write:

'foobar'.reverse.upcase => "RABOOF"

Methods often are called on variables (such as date ) which are instances of a class. Some classes, such as Date , provide class methods which can be called directly on the class without instantiating it first.

11

114

Question and Exclamation Methods

Youll see question marks and exclamation points (sometimes called the bang character) used in method names. These characters are simply a naming convention for Ruby methods. The question mark indicates the method will return a boolean value (true or false). The bang character indicates the method is dangerous. In some cases it means the method will change the object rather just return a result. In Rails an exclamation point often means the method will throw an exception on failure rather than failing silently.

Method Parameters
Methods are useful when they operate on data. If we want to send data to a method, we define the method and indicate it will accept parameters. Parameters are placeholders for data values. The values that are passed to a method are arguments. Parameters are empty placeholders and arguments are the actual values. In practice, parameters and arguments are terms that are used interchangeably and not many developers will notice if you mix up the terms. Here we define a method
initialize

that takes

name

and

date

arguments.

def initialize(name,date)

Ruby is clever with method parameters. You can define a method and specify default values for parameters. You can also pass extra arguments to a method if you define a method that allows optional parameters. This makes methods very flexible. We separate our parameters with commas. For readability, we enclose our list of parameters in parentheses. In Ruby, parentheses are always optional but they often improve readability.

Initialize Method
Objects are created from classes before they are used. As I suggested earlier, class definitions are cookie cutters; the Ruby interpreter uses them to cut cookies. When we call the new method, we press the cookie cutter into the dough and get a new object. All the cookies will have the same shape but they can be decorated differently, by sprinkling attributes of different values. The
initialize

method is one of the ways we sprinkle attributes on our cookie.

11

115 def initialize(name,date)

When we want to use an Example object and assign it to a variable, we will instantiate it with @Example.new(name,date) . The new method calls the initialize method automatically. If we dont define an initialize method, the new method still works, inherited from Object , so we can always instantiate any class.

Variable
In Ruby, everything is an object. We can assign any object to a variable. The variable works like an alias. We can use a variable anywhere inside a method as if it were the assigned object. The variable can be assigned a string, a numeric value, or an instance of any class (all are objects).
name

You can assign a new value to a variable anywhere in your method. You can assign a different kind of object if you want. You can take away someones name and give them a number. We can create a variable player , assign it the string 'Jackie Robinson' , replace the value with an integer 42 , or even a date such as Date.new(1947,4,15) .

Symbol
Obviously, we see many symbols when we read Ruby code, such as punctuation marks and alphanumeric characters. But symbol has a specific meaning in Ruby. It is like a variable, but it can only be assigned a value once. After the initial assignment, it is immutable; it cannot be changed. You will recognize a symbol by the colon that is always the first character.
:name

Symbols are efficient and fast because the Ruby interpreter doesnt have to work to check their current values. Youll often see symbols used in Rails where you might expect a variable.

11

116

Instance Variable
An ordinary variable only retains its assigned value within its most immediate surroundings. If you assign a variable inside a method, the variable only can be used inside the method. Often you want a variable to be useful throughout a class, in any method. You can declare an instance variable by using an @ (at) sign as the first character of the variable name. The instance variable can be used by any method after the class is instantiated.
@name = name

In a Rails controller, youll often see a model assigned to an instance variable. Earlier we saw @owner = Owner.new when we instantiated an Owner model. We use an instance variable when we want a model to be available to the view template. Rails beginners learn the simple rule that you have to use the @ (at) sign if you want a variable to be available in the view. Intermediate Rails developers learn that the variable with the @ (at) sign is called an instance variable and is only available within the scope of the instance (practically speaking, to other methods in the class definition). That leads to a question: Why is an instance variable available inside a view? There is a good reason. A Rails view is NOT a separate class. It is a template and, under the hood, it is part of the current controller object. From the viewpoint of a programmer, a Rails controller and a view are separate files, segregated in separate folders. From the viewpoint of a software architect, the controller is a single object that evaluates the template code, so an instance variable can be used in the view file. Remember the story of the six blind men and the elephant? This example shows us that the programmer and the software architect have different perspectives on a Rails application. Understanding Rails requires an integration of multiple points of view.

Double Bar Equals Operator

Ive suggested that the best way to get help is to use Google or Stack Overflow to look for answers. But thats difficult when you dont know what symbols are called. Try googling ||= and youll get no results. Instead, try googling bar bar equals ruby or double pipe equals ruby and youll find many explanations of the or equals operator. This is an example of mysterious shorthand code youll often find in Rails. ||= is used for conditional assignment. In this case, we only assign a value to the variable if no value has been previously assigned.

11

117 @honorific ||= 'Esteemed'

It is equivalent to this conditional expression:

if not x x = y end

Conditional assignment is often used to assign a default value when no other value has been assigned.

Conditional
Conditional logic is fundamental to programming. Our code is always a path with many branches. When the Ruby interpreter encounters an if keyword, it expects to find an expression which evaluates as true or false (a boolean). If the expression is true, the statements following the condition are executed. If the expression is false, any statements are ignored, unless there is an an alternative is executed.
if date.month == 12 . . . end
else

, in which case

Sometimes youll see unless instead of following if the condition is false.

if

, which is a convenient way of saying execute the

In Ruby, the conditional expression can be a simple comparison, as illustrated above with the == (double equals) operator. Or if can be followed by a variable that has been assigned a boolean value. Or you can call a method that returns a boolean result.

Ternary Operator
A basic conditional structure might look like this:

11

118 if date.nil? @date = Date.today else @date = date end

We test if date is undefined (nil). If nil, we assign todays date to the instance variable @date . If date is already assigned a value, we assign it to the instance variable @date . This is useful in the initialize(name,date) method in our example code because we want to set todays date as the default value for the instance variable @date if the parameter date is nil. Ruby developers like to keep their code tight and compact. So youll see a condensed version of this conditional structure often, particularly when a default value must be assigned. This compact conditional syntax is named the ternary operator because it has three components. Here is the syntax:
condition ? value_if_true : value_if_false

Here is the ternary operator we use in our example code:

@date = date.nil? ? Date.today : date

This is another example of Ruby syntax that you must learn to recognize by sight because it is difficult to interpret if you have never seen it before.

Interpolation
Rubyists love to find special uses for orthography such as hashmarks and curly braces. It seems Rubyists feel sorry for punctuation marks that dont get much use in the English language and like to give them new jobs. We already know that we can assign a string to a variable:
name = 'Foobar Kadigan'

We can also perform string addition to concatenate strings. Here we add an honorific, a space, and a name:
@honorific = 'Mr.' @name = 'Foobar Kadigan'

11

119 titled_name = @honorific + ' ' + @name => "Mr. Foobar Kadigan"

Single quote marks indicate a string. In the example above, we enclose a space character within quote marks so we add a space to our string. You can eliminate the ungainly mix of plus signs, single quote marks, and space characters in the example above. Use double quote marks and you can perform interpolation, which gives a new job to the hashmark and curly brace characters:
@honorific = 'Mr.' @name = 'Foobar Kadigan' titled_name = "#{@honorific} #{@name}" => "Mr. Foobar Kadigan"

The hashmark indicates any expression within the curly braces is to be evaluated and returned as a string. This only works when you surround the expression with double quote marks. Interpolation is cryptic when you first encounter the syntax, but it streamlines string concatenation.

Access Control
Any method you define will return a result. Sometimes you want to create a method that only can be used by other methods in the same class definition. This is common when you need a simple utility method that is used by several other methods. Use the keyword private to indicate the method should not be accessed by a call to the object from outside the instance. Any methods that follow the keyword private are only used by other methods in the same object.
private

You often see private methods in Rails. Ruby provides a protected keyword as well, but it is seldom seen in Rails applications. Protected methods can be invoked only by objects of the defining class and its subclasses.

11

120

Hash
Our example code includes a private method named famous_birthdays that returns a collection of names and birthdays of famous musicians. Computers have always been calculation machines but they are just as important in managing collections. One important type of collection is named a Hash. A Hash is a data structure that associates a key to some value. You retrieve the value based upon its key. This construct is called a dictionary, an associative array, or a map in other languages. You use the key to look up a value, as you would look up a definition for a word in a dictionary. Youll recognize a Hash when you see curly braces (again, Rubyists give a job to underutilized punctuation marks).
birthdays = { 'Ludwig van Beethoven' => Date.new(1770,12,16), 'Dave Brubeck' => Date.new(1920,12,6), 'Buddy Holly' => Date.new(1936,9,7), 'Keith Richards' => Date.new(1943,12,18) }

Rubyists also like to create novel uses for mathematical symbols. The combination of an = (equals) sign and > (greater than) sign is called a hashrocket. The => (hashrocket) operator associates a key and value pair in a Hash. Ruby 1.9 introduced a new way to associate key and value pairs in a Hash:
birthdays = { beethoven: Date.new(1770,12,16), brubeck: Date.new(1920,12,6), holly: Date.new(1936,9,7), richards: Date.new(1943,12,18) }

Here, instead of using a string as the key, we are using Ruby symbols, which enable faster processing. The : (colon) character associates the key and value. Youll still see the hashrocket when a string is used as a key. Whether with colons or hashrockets, youll often see Hashes used in Rails.

12

121

Array
An Array is a list. Arrays can hold objects of any data type. In fact, arrays can contain a mix of different objects. For example, an array can contain a string and another array (this is an example of a nested array). An array can be instantiated with square brackets:
born_in_december = [ ]

We can populate the array with values when we create it:

my_list = ['apples', 'oranges']

If we dont want to use quote marks and commas to separate strings in a list, we can use the %w syntax:
my_list = %w( apples oranges )

We can add new elements to an array with a

my_list = Array.new => [] my_list.push 'apples' => ["apples"] my_list.push 'oranges' => ["apples", "oranges"]

push

method:

In our example code, we use the

born_in_december << name

<<

shovel operator to add items to the array:

A Ruby array has close to a hundred available methods, including operations such as and sort . See the Ruby API for a full list.

size

Iterator
Of all the methods available for a Ruby collection such as Hash or Array, the iterator may be the most useful. Youll recognize an iterator when you see the
each

method applied to a Hash or Array:

12

122 famous_birthdays.each

The each keyword is always followed by a block of code. Each item in an Array, or keyvalue pair in a Hash, is passed to the block of code to be processed.

Block
You can recognize a block in Ruby when you see a way to process each item when an iterator such as In our example, we iterate over the
do ... end each

structure. A block is a common is applied to a Hash or Array.

famous_birthdays

hash:

famous_birthdays.each do |name, date| . . . end

Within the two pipes (or bars), we assign the key and value to two variables. The block is like an unnamed method. The two variables are available only within the block. As each key-value pair is presented by the iterator, the variables are assigned, and the statements in the block are executed. In our example code, we evaluate each date in the famous_birthdays hash to determine if the musician was born in December. When we find a December birthday, we add the name of the musician to the born_in_december array:
famous_birthdays.each do |name, date| if date.month == 12 born_in_december << name end end

Computer scientists consider a block to be a programming language construct called a closure. Ruby has other closures, including the proc (short for procedure) and the lambda. Though blocks are common youll seldom see procs or lambdas in ordinary Rails code. They are more common in the Rails source code where advanced programming techniques are used more frequently. The key point to know about a block (or a proc or a lambda) is that it works like a method. Though you dont see a method definition, you can use a block to evaluate a sequence of statements and obtain a result.

12

123

Rails and More Keywords

Our example file only offers a sample of a few of the keywords and constructs you will see in Ruby code. I hope it will advance your Ruby literacy, so youll have an easier time reading Ruby code. Nothing in our example file is Rails. The code only uses keywords from the Ruby API. Rails has its own API, with hundreds of classes and methods. The Rails API uses the syntax and keywords of the Ruby language to construct new classes and create new keywords that are specific to Rails and useful for building web applications. We say Ruby is a general-purpose language because it can be used for anything. Rails is a domain-specific language (DSL) because it is used only by people building web applications (in this sense, domain means area or field of activity). Ruby is a great language to use for building a DSL, which is why it was used for Rails. Unlike some other programming languages, Ruby easily can be extended or tweaked. For example, developers can redefine classes, add extra methods to existing classes, and use the special method_missing method to handle method calls that arent previously defined. Software architects call this metaprogramming which simply means clever programming that twists and reworks the programming language. When you add a gems to a Rails project, youll add additional keywords. Some of the most powerful gems add their own DSLs to your project. For example, the Cucumber gem provides a DSL for turning user stories into automated tests. Adding Rails, additional gems, and DSLs provides powerful functionality at the cost of complexity. But it all conforms to the syntax of the Ruby language. As you learn to recognize Ruby keywords and language structures, youll be able to pick apart the complexity and make sense of any code.

More Ruby
To develop your proficiency as a Rails developer, I hope you will make an effort to learn Ruby as you learn Rails. Dont be lazy; when you encounter a bit of Ruby you dont understand, make an effort to find out what is going on. Spend time with a Ruby textbook or interactive course when you work on Rails projects.

Online
TryRuby.org free browser-based interactive tutorial from Code School Codecademy Ruby Track free browser-based interactive tutorials from Codecademy

12

124

Ruby Monk free browser-based interactive tutorial from C42 Engineering Ruby Koans free browser-based interactive exercises from Jim Weirich and Joe OBrien Ruby in 100 Minutes free tutorial from JumpstartLab Code Like This free tutorials by Alex Chaffee RailsBridge Ruby

Books
Learn To Program free ebook by Chris Pine Learn To Program expanded $18.50 ebook by Chris Pine Learn Code the Hard Way free from Zed Shaw and Rob Sobers Beginning Ruby by Peter Cooper Programming Ruby by Dave Thomas, Andy Hunt, and Chad Fowler Eloquent Ruby by Russ Olsen

Newsletters
Practicing Ruby $8/month for access to over 90 helpful articles on Ruby

Screencasts
RubyTapas $9/month for access to over 100 screencasts on Ruby

Git
Theres no need to save the file lib/example.rb file we created to learn Ruby. You can simply delete the file:
$ rm lib/example.rb

Or use Git to revert your project to the most recent commit:

$ git reset --hard HEAD

12

125

The Git command git reset --hard HEAD discards any changes youve made since the most recent commit. Check the status to make sure:
$ git status # On branch master nothing to commit (working directory clean)

Weve cleaned up after our Ruby exercise. From here on, were done with silly code examples. No more fooling around. With the next chapter, we start building a real-world Rails website.

12

126

Chapter 18

Layout and Views

In previous chapters we created a dynamic home page and learned techniques for troubleshooting. In this chapter well look closely at view files, particularly the application layout, so we can organize the design of our web pages. In the next chapter well learn how to add CSS stylesheets to complete the graphic design of our web pages. This chapter covers a lot of ground, so take a break before jumping in, or pace yourself to absorb it all.

Application Layout
Weve already created the view file for our home page. The file app/views/visitors/new.html.erb looks like this:
<h3>Home</h3> <p>Welcome to the home of <%= @owner.name %>.</p> <p>I was born on <%= @owner.birthdate %>.</p> <p>Only <%= @owner.countdown %> days until my birthday!</p>

The first line in the file contains an HTML heading tag,

<h3>

, with headline text, Home.

When you used the browser diagnostic view to see the HTML file received by the server, you saw this:
<!DOCTYPE html> <html> <head> <title>LearnRails</title> <link data-turbolinks-track="true" href="/assets/application.css?body=1" media="all" rel="stylesheet" /> <script data-turbolinks-track="true" src="/assets/jquery.js?body=1"></script> ></script> <script data-turbolinks-track="true" src="/assets/jquery_ujs.js?body=1"></script> ></script> <script data-turbolinks-track="true" src="/assets/turbolinks.js?body=1"></script> ></script> <script data-turbolinks-track="true" src="/assets/application.js?body=1"></script> ></script> <meta content="authenticity_token" name="csrf-param" /> <meta content="NRPrgfuj5GAyylNpNxQaMHDypcOsu6dmh5DT1yET6hQ=" name="csrf-token" />

12

127 </head> <body> <h3>Home</h3> <p>Welcome to the home of Foobar Kadigan.</p> <p>I was born on 1990-09-22.</p> <p>Only 126 days until my birthday!</p>

</body> </html>

The HTML file is more than twice the size of the view file. Where did all the extra HTML come from? If youve built websites before, youll recognize the HTML file conforms to the HTML5 specification, with a DOCTYPE , <head> and <body> tags, and miscellaneous tags in the HEAD section, including a title and various CSS and JavaScript assets. The additional tags come from the default application layout file. Open the file app/views/layouts/application.html.erb:
<!DOCTYPE html> <html> <head> <title>LearnRails</title> <%= stylesheet_link_tag "application", media: "all", "data-turbolinks-track" => true %> <%= javascript_include_tag "application", "data-turbolinks-track" => true %> <%= csrf_meta_tags %> </head> <body> <%= yield %> </body> </html>

Youll see that Rails has combined the Visitors#New view with the default application layout file. Static pages delivered from the public folder do not use the default application layout. But every page generated by the model-view-controller architecture in the app/ folder incorporates the default application layout, unless you specify otherwise. The default application layout is where you put HTML that you want to include on every page of your website.

12

128

Remember when we looked at the hidden code in the controller that renders a view? The controller uses the render method to combine the view file with the application layout:
class VisitorsController < ApplicationController def new @owner = Owner.new render 'visitors/new' end end

Here the render method combines the app/views/visitors/new.html.erb view file with the app/views/layouts/application.html.erb: application layout. You could tell the controller to render the view without any application layout:
render 'visitors/new', :layout => false

Or you could specify an alternative layout file, for example app/views/layouts/ special.html.erb:
render 'visitors/new', :layout => 'special'

An alternative layout can be useful for special categories of pages, such as administrative pages or landing pages. We wont use alternative layouts in this tutorial application, but its good to know they are an option. The reference RailsGuides: Layouts and Rendering in Rails explains more about using alternative layouts.

Yield
How does the
render

method insert the view file in the application layout?

yield

Notice that the default application layout contains the Ruby keyword

The yield keyword is replaced with a view file that is specific to the controller and action, in this case, the app/views/visitors/new.html.erb view file. The content from the view is inserted where you place the
yield

keyword.

12

129

Rails provides other ways to insert content into a layout file. For example, the content_for method is helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content. For example, you could create an application layout that includes a sidebar. This is just an example, so dont add it to the application you are building:
<!DOCTYPE html> <html> <head> <title>LearnRails</title> <%= stylesheet_link_tag "application", media: "all", "data-turbolinks-track" => true %> <%= javascript_include_tag "application", "data-turbolinks-track" => true %> <%= csrf_meta_tags %> </head> <body> <div class="main"> <%= yield %> </div> <div class="sidebar"> <%= yield :sidebar %> </div> </body> </html>

This view file provides both the main content and a sidebar:
<% content_for :sidebar do %> <h3>Contact Info</h3> <p>Email: [email protected]</p> <% end %> <h3>Main</h3> <p>Welcome!</p>

Again, dont add this to your application. Im just offering it as an example of multiple statements. The reference RailsGuides: Layouts and Rendering in Rails explains more about using and content_for .

yield

yield

View Helpers
Lets look more closely at the application layout file. As we might expect, we see HTML tags, enclosed in angle brackets (sometimes called chevrons).

12

130

We also see ERB <%= ... %> delimiters. Earlier, we saw that the delimiters allow us to insert Ruby expressions which are replaced by the result of evaluating the code. In the application layout file, the <%= ... %> delimiters dont include anything that looks like Ruby code. For example, we see <%= csrf_meta_tags %> which seems to be neither HTML nor anything from the Ruby API. In fact, this expression is Ruby code, but it is from the Rails API and only found in Rails applications. Ruby is an ideal choice for a web application development platform such as Rails because it can easily be used to create a domain-specific language (or DSL). Much of Rails is a domainspecific language. The Smalltalk programming language was famous for its mantra Code should read like a conversation. Ruby, which borrows much from Smalltalk, makes it easy to add new words to the conversation. We can add new keywords that produce complex behaviour, creating entire new APIs such as Rails. Ruby makes it easy for the Rails core team to add keywords such as csrf_meta_tags that are additions to the Ruby language. In this case, Rubys ability to produce a domain-specific language gives us Rails view helpers. Think of Rails view helpers as macros to generate HTML. You may have used macros to automate a series of commands in World of Warcraft or other games. If youre an office worker, you may have used macros in Microsoft Word or Excel. A Rails view helper is a keyword that expands into a longer string of HTML tags and content. In this case, the
csrf_meta_tags

view helper expands into two lines of HTML:

<meta content="authenticity_token" name="csrf-param" /> <meta content="NRPrgfuj5GAyylNpNxQaMHDypcOsu6dmh5DT1yET6hQ=" name="csrf-token" />

But why? It turns out that almost any website that accepts user input via a form is vulnerable to a security bug (an exploit) named a cross-site request forgery. To prevent rampant CSRF exploits, the Rails core team includes the csrf_meta_tags view helper in the default application layout. Rails provides a number of similar features that make websites more secure. A Rails view file becomes much less mysterious when you realize that many of the keywords you see are view helpers. Strange new keywords may be part of the Rails API. Or they may be provided by gems youve added (gem developers often use the Ruby DSL capability to create new keywords). Think of it this way: Ruby gives developers the power to create an unlimited number of new HTML tags. These tags are not really HTML because they are not part of the HTML specification. But they serve as shortcuts to produce complex snippets of HTML and content.

Basic Boilerplate
So far weve seen the standard HTML
DOCTYPE

<head>

, and

<body>

tags.

13

131

Weve seen the Weve seen the

yield

keyword. delimiters surrounding the

<meta> csrf_meta_tags

<%= ... %>

view helper:

csrf_meta_tags

generates

tags that prevent cross-site request forgery

Finally, notice the

<%= ... %>

delimiters surrounding other Rails helper methods:

<link>

stylesheet_link_tag

generates an HTML

tag for CSS tag for JavaScript

javascript_include_tag

generates an HTML

<script>

These are tags that add CSS and JavaScript to the web page. Later in this chapter, well take a closer look at the view helpers that add CSS and JavaScript.

Adding Boilerplate
Webmasters who build static websites are accustomed to setting up web pages with boilerplate, or basic templates for a standard web page. The well-known HTML5 Boilerplate project has been recommending best practice tweaks to web pages since 2010. Very few of the HTML5 Boilerplate recommendations are relevant for Rails developers, as Rails already provides almost everything required. There is only one boilerplate item you should add: the viewport metatag. If you want to learn more, the article HTML5 Boilerplate for Rails Developers looks at the recommendations.

Viewport
The viewport metatag improves the presentation of web pages on mobile devices. Setting a viewport tells the browser how content should fit on the devices screen. Apples developer documentation on Configuring the Viewport provides details. The
viewport

metatag looks like this:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Dont add the viewport metatag just yet; Ill explain all the pieces and then well add everything we need at the end of this chapter.

Title and Description

If you want to maximize traffic to your website, you should make your web pages searchengine friendly. That means adding title and description metatags. Google uses contents of the

13

132

title tag to display titles in search results. And it will sometimes use the content of a description metatag in search results snippets. See Googles explanation of how it uses Site Title and Description. Good titles and descriptions improve clickthrough from Google searches. Later in the tutorial, well see how to use a content_for statement to set a title and description for a page. Title and description looks like this:
<title><%= content_for?(:title) ? yield(:title) : "Learning Rails" %></title> <meta name="description" content="<%= content_for?(:description) ? yield(:description) : "Learning Rails" %>">

The code is complex if you havent seen Ruby before. It uses the Ruby ternary operator which maximizes compactness at the price of introducing obscurity. Its a fancy conditional statement that says, if content_for?(:title) is present in the view file, use yield(:title) to include it, otherwise just display Learning Rails. Well add the this chapter.
viewport

metatag, title, and description to the application layout at the end of

Asset Pipeline
The Rails asset pipeline utility is one of the most powerful features of the platform. It offers convenience to the developer and helps organize an application; more importantly, it improves the speed and responsiveness of any complex website. If youre going to do any front-end development with CSS or JavaScript in Rails, you must understand the Rails asset pipeline. Heres how it works. When building non-Rails websites, webmasters add JavaScript to a page using the <script> tag. For every JavaScript file, they add an additional <script> tag, so a page HEAD section looks like this:
<!DOCTYPE html> <html> <head> <title>Page that uses multiple JavaScript files</title> <script src="jquery.js" type="text/javascript"></script> ></script> <script src="jquery.plugin.js" type="text/javascript"></script> ></script> <script src="custom.js" type="text/javascript"></script> ></script> </head>

The same is true for CSS files in non-Rails websites. You add a <link> tag for each stylesheet file. With multiple stylesheets, the HEAD section of your application layout might look like this:

13

133 <!DOCTYPE html> <html> <head> <title>Page that uses multiple CSS files</title> <link href="core.css" rel="stylesheet" type="text/css" /> <link href="site.css" rel="stylesheet" type="text/css" /> <link href="custom.css" rel="stylesheet" type="text/css" /> </head>

Without the asset pipeline, every time you create a JavaScript or CSS file, you must modify the application layout file. The asset pipeline simplifies this. The asset pipeline consists of two folders: app/assets/javascripts/ app/assets/stylesheets/ Any JavaScript and CSS file you add to these folders is automatically added to every page. In development, when the web browser makes a page request, the files in the asset pipeline folders are combined together and concatenated as single large files, one for JavaScript and one for CSS. If you examine the application layout file, youll see the tags that perform this service:
<%= stylesheet_link_tag "application", media: "all", "data-turbolinks-track" => true %> <%= javascript_include_tag "application", "data-turbolinks-track" => true %>

The HTML delivered to the browser looks like this:

<link href="/assets/application.css" media="all" rel="stylesheet" type="text/css" /> <script src="/assets/application.js" type="text/javascript"></script> ></script>

Using the asset pipeline, there is no need to modify the application layout file each time you create a new JavaScript or CSS file. Create as many files as you need to organize your JavaScript or CSS code and youll automatically get one single file delivered to the browser. Theres a big performance advantage with the asset pipeline. Requesting files from the server is a time-consuming operation for a web browser, so every extra file request slows down the browser. The Rails asset pipeline eliminates the performance penalty of multiple <script> or <link> tags. The Rails asset pipeline also compresses JavaScript and CSS files for faster page loads. The asset pipeline is an example of a Rails convention that helps developers build complex websites. It is not needed for a simple website that uses a few JavaScript or CSS files. But it is beneficial on bigger projects.

13

134

Later in the tutorial, well use the asset pipeline to add CSS and JavaScript to our application.

Navigation Links
Every website needs navigation links. For our application, well want links for Home, About, and Contact. You can add navigation links directly to your application layout but many Rails developers prefer to create a partial template a partial to better organize the default application layout. A partial is similar to any view file, except the filename begins with an underscore character. Save the file in any view folder and use the render keyword to insert the partial. Heres an example of using the render keyword with a hypothetical file named app/views/ layouts/_footer.html.erb:
<%= render 'layouts/footer' %>

Notice that you specify the folder within the app/views/ directory with a truncated version of the filename. The render method doesnt want the _ underscore character or the .html.erb file extension. That can be confusing; it makes sense when you remember that Rails likes convention over configuration and economizes on extra characters when possible. Theres no rule against using raw HTML in our view files, so we could create a partial for navigation links that uses the HTML <a> anchor tag like this:
<ul class="nav"> <li><a href="/">Home</a></li> <li><a href="/about">About</a></li> <li><a href="/contact">Contact</a></li> </ul>

Rails gives us another option, however. We can use the Rails link_to view helper instead of the HTML <a> anchor tag. The Rails link_to helper eliminates the crufty <> angle brackets and the unnecessary href="" . More importantly, it adds a layer of abstraction, using the routing configuration file to form links. This is advantageous if we make changes to the location of the link destinations. Earlier, when we created a static About page, we first set the config/routes.rb file with a route to the About page: root to: redirect('/about.html') . Later we removed the static About page and set the config/routes.rb file with a route to the dynamic home page: root to: 'visitors#new' . If we used the raw HTML <a> anchor tag, wed have to change the raw HTML everywhere we had a link to the home page. Using the Rails link_to helper, we name a route and make any changes once, in the config/routes.rb file.

13

135

When you use the Rails link_to helper, youll avoid the problem of link maintenance that webmasters face on static websites. Some webmasters like to use absolute URLs, specifying a host name in the link, for example http://www.example.com/about.html . Absolute URLs are a headache when moving the site, for example from staging.example.com to www.example.com . The problem is avoided by using relative URLs, such as /about.html , about.html , or even ../about.html . But relative URLs are fragile, and moving files or directories often results in overlooked and broken links. Instead, with the Rails link_to helper, you always get the destination location specified in the config/routes.rb file. Using the
link_to

helper, create a file app/views/layouts/_navigation.html.erb:

<ul class="nav"> <li><%= link_to 'Home', root_path %></li> <li><%= link_to 'About', page_path('about') %></li> <li><%= link_to 'Contact', page_path('contact') %></li> </ul>

Here the link_to helper takes two parameters. The first parameter is the string displayed as the anchor text ( 'Home' ). The second parameter is the route. In this case, the route root_path has been set in the config/routes.rb file. The two other routes, page_path('about') and page_path('contact') , are set automatically by the high_voltage gem. We can add the navigation links partial to our application layout with the expression:
<%= render 'layouts/navigation' %>

Well add this to the application layout at the end of this chapter.

Flash Messages
Rails provides a standard convention to display alerts (including error messages) and other notices (including success messages), called a flash message. The name comes from the term flash memory and should not be confused with the Adobe Flash web development platform that was once popular for animated websites. The flash message is documented in the RailsGuides: Action Controller Overview. Heres a flash message you might see after logging in to an application:

It is called a flash message because it appears on a page temporarily. When the page is reloaded or another page is visited, the message disappears.

13

136

Typically, you will see only one flash message on a page. But there is no limit to the number of flash messages that can appear on a page. Flash messages are created in a controller. For example, we could add messages to the home page by modifying the VisitorsController like this:
class VisitorsController < ApplicationController def new @owner = Owner.new flash[:notice] = 'Welcome!' flash[:alert] = 'My birthday is soon.' end end

We havent yet updated our application layout to handle flash messages so this is only an illustration. But if you try this after completing this chapter, youll see two flash messages appear on the page. Rails provides the flash object so that messages can be created in the controller and displayed on the rendered web page. In this example, we create a flash message by associating the object flash[:notice] with the string 'Welcome!' . We can assign other messages, such as flash[:alert] or even flash[:warning] . In practice, Rails uses only :notice and :alert as flash message keys so it is wise to stick with just these.

Flash and Flash Now

You can control the persistence of the flash message by choosing from two variants of the Flash directive. Use
flash.now

render :new

in the controller when you immediately render a page, for example with a directive. With flash.now , the message will vanish after the user clicks any links.

Use the simple variant, flash , in the controller when you redirect to another page, for example with a redirect_to root_path directive. If you use flash.now before a redirect, the user will not see the flash message because flash.now does not persist through redirects or links. If you use the simple flash directive before a render directive, the message will appear on the rendered page and reappear on a subsequent page after the user clicks a link. In our example above, we really need to use the provides a hidden render method.
flash.now

variant because the controller

13

137 class VisitorsController < ApplicationController def new @owner = Owner.new flash.now[:notice] = 'Welcome!' flash.now[:alert] = 'My birthday is soon.' end end

Using flash.now will make sure the message only appears on the rendered page and will not persist after a user follows a link to a new page. If this is confusing, dont worry. Just make a mental note that if you see a sticky flash message that wont go away, you need to use flash.now instead of flash .

Explaining the Ruby Code

If youre new to programming in Ruby, it may be helpful to learn how the works.
flash

object

The flash object is a Ruby hash (also known as an associative array). A hash is a data structure that associates a key to some value. You retrieve the value based upon its key. This construct is called a dictionary in other languages, which is appropriate because you use the key to look up a value, as you would look up a definition for a word in a dictionary. Hash is a type of collection. Presumably, the Rails core contributors who implemented the code chose to use a collection so that a page could be given multiple flash messages. Because we have a collection with (possibly) multiple messages, we need to retrieve each message one at a time. In Ruby, all collections support an iterator method named each . Iterators return all the elements of a collection, one after the other. The iterator returns each key-value pair, item by item, to a block. In Ruby, a block is delimited by do and end or { } braces. You can add any code to a block to process each item from the collection. Here is simple Ruby code to iterate through a flash object, outputting each flash message in an HTML div tag and applying a CSS class for styling:
flash.each do |key, value| puts '<div class="' + key + '">' + value + '</div>' end

In this simple example, we use each to iterate through the flash hash, retrieving a key and value that are passed to a block to be output as a string. Weve chosen the variable names

13

138

and value but the names are arbitrary. In the next example, well use name and variables for the key-value pair. The output string will appear as HTML like this:
key

msg

as

<div class="notice">Welcome!</div> <div class="alert">My birthday is soon.</div>

Create a Partial for Flash Messages

Flash messages are a very useful feature for a dynamic website and could be used on any page. Well add code to output flash messages within the application layout. Code for flash messages can go directly in your application layout file or you can create a partial. Add a partial for flash messages by creating a file app/views/layouts/_messages.html.erb like this:
<% flash.each do |name, msg| %> <% if msg.is_a?(String) %> <div class="alert alert-<%= name == :notice ? "success" : "error" %>"> <a class="close" data-dismiss="alert">&#215;</a> <%= content_tag :div, msg, :id => "flash_#{name}" %> </div> <% end %> <% end %>

Weve improved on our simple Ruby example in several ways. First, weve added if msg.is_a?(String) as a test to make sure we only display messages that are strings. Second, weve used the Rails content_tag view helper to create the HTML div . The content_tag helper eliminates the messy soup of angle brackets and quote marks we used to create the HTML output in the example above. Finally, instead of applying a CSS class for styling, weve applied a CSS id and combined the word flash with notice or alert to make the CSS ID. Its appropriate to apply an ID instead of a class because there should be only a single flash message on the page (classes are used for multiple elements). Well add the partial to the application layout at the end of this chapter.

HTML5 Elements
To complete our application layout, well add a few structural elements to make it easy to apply CSS styling. These elements are not unique to a Rails application and will be familiar to anyone who has done front-end development.

13

139

Well add a container div to the page. This is a common technique among front-end designers, particularly useful for adding margins or borders to the page layout. The HTML5 specification provides <header> and <footer> elements that add structure to a web page. The tags dont add any new behavior but make it easier to determine the structure of the page and apply CSS styles. The <header> tag is typically used for branding or navigation and the <footer> tag typically contains links to copyright information, legal disclaimers, or contact information. Finally well wrap our yield in a <main role="main"> element. The <main> tag is among the newest HTML5 elements (see the W3C specification for details). From the specification: The main content area of a document includes content that is unique to that document and excludes content that is repeated across a set of documents such as site navigation links, copyright information, site logos. The specification recommends, Authors are advised to use ARIA role=main" attribute on the main element until user agents implement the required role mapping." Well follow the advice of the specification and wrap our unique content in the <main> tag. Lets put this all together for our updated application layout.

Updated Application Layout

Now well put everything together that weve discussed. Modify the file app/views/layouts/application.html.erb to include everything weve discussed in this chapter:
<!DOCTYPE html> <html> <head> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title><%= content_for?(:title) ? yield(:title) : "Learning Rails" %></title> <meta name="description" content="<%= content_for?(:description) ? yield(:description) : "Learning Rails" %>"> <%= stylesheet_link_tag "application", media: "all", "data-turbolinks-track" => true %> <%= javascript_include_tag "application", "data-turbolinks-track" => true %> <%= csrf_meta_tags %> </head> <body> <div id="container"> <header> <%= render 'layouts/navigation' %> <%= render 'layouts/messages' %> </header> <main role="main"> <%= yield %>

13

140 </main> <footer> </footer> </div> </body> </html>

Weve added the

viewport

metatag, replaced the title, and added a description.

Weve added the partials for navigation links and flash messages. Finally weve added HTML5 structural elements. Our application layout is completefor now. In the next chapter, well revise it to support styling with Twitter Bootstrap.

Test the Application

Lets run the application to see how it looks with the new application layout. The web server may already be running. If not, enter the command:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. If you experimented with adding flash messages Welcome and My birthday is soon, youll see the messages when you visit the home page. Remove the code for the flash messages from the Visitors controller before continuing to the next chapter. Our home page now has navigation links. The links are broken because we havent yet created About and Contact pages. Well add those soon. Next well add CSS to improve the design.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "update application layout" $ git push origin master

14

141

Chapter 19

Stylesheets and Themes

This chapter touches on front-end development and design using CSS. Ill show you how to add CSS to a Rails application, including Twitter Bootstrap for a simple theme. There are three approaches to front-end design for your Rails application. One approach is to purchase a pre-designed theme for your website. You may have visited ThemeForest or other theme galleries that offer pre-built themes for a few dollars each. These huge commercial galleries offer themes for WordPress, Tumblr, or CMS applications such as Drupal or Joomla. They dont offer themes for Rails and it is not easy to adapt one of their themes for a Rails application. However, Ill provide links to a few small commercial sites offering themes pre-built for Rails applications. A second approach is to use Twitter Bootstrap or Zurb Foundation. (Which one? See Framework Fight). You can use these front-end frameworks to quickly add attractive CSS styling to your application. Many developers dont have the skill or resources to customize the design. Consequently, sites that use Twitter Bootstrap or Zurb Foundation look very similar. If thats your situation, its okay, really! Its better to have a decent site with the clean look of Twitter Bootstrap than to leak ugliness onto the web. A third approach is to implement a unique design, built from scratch using CSS or customized from a framework such as Twitter Bootstrap or Zurb Foundation. If youve got strong design skills, or can partner with an experienced web designer, this gives you a custom design that expresses the purpose and motif of your website. Ill give you some links for theme galleries and then well add Twitter Bootstrap to our tutorial application.

Themes
Rails developers are not a large market for commercial theme galleries because many Rails projects can afford custom design. And unlike WordPress, Rails projects implement such a great variety of sites that no theme can be prepackaged to accommodate all Rails projects. That said, a few consultants recently have introduced themes that can be used on Rails projects. RailsThemes.com from Eliza Brock, Anthony Panozzo, and Luke Flener Dressed Rails Themes from Marc-Andr Cournoyer Railsview.com from Richardson Dackam

14

142

The WrapBootstrap marketplace offers themes that can be adapted for Rails. One offering built on Twitter Bootstrap is packaged as a Rails gem: RailsStrap by Leon Touroutoglou The Bootswatch site offers free themes for Twitter Bootstrap that can be adapted for Rails. If you want the retro look of the 1990s web, use: Geo for Bootstrap Youve got to see it. Believe it or not, websites used to look like that. Even if you use a prepackaged theme, youll need to know how to set up CSS stylesheets in Rails. And youre likely to need Twitter Bootstrap. Well look at the asset pipeline for CSS and Twitter Bootstrap next.

Asset Pipeline for CSS

In the previous chapter, I introduced the Rails asset pipeline. The asset pipeline helps web pages display faster in the browser by combining all CSS files into a single file (it does the same for JavaScript). Your CSS stylesheets get concatenated and compacted for delivery to the browser when you add them to this directory: app/assets/stylesheets/ The default Rails starter application contains one file in the directory: app/assets/stylesheets/application.css Open the file in your text editor and youll see this:
/* * This is a manifest file that'll be compiled into application.css, which will include all the files * listed below. * * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/ stylesheets, * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path. * * You're free to add application-wide styles to this file and they'll appear at the top of the

14

143 * compiled file, but it's generally better to create a new file per style scope. * *= require_self *= require_tree . */

The app/assets/stylesheets/application.css file serves two purposes. First, you can add any CSS rules to the file that you want to use anywhere on your website. Second, the file serves as a manifest, providing a list of files that should be concatenated and included in the single CSS file that is delivered to the browser. Its bad practice to place all your CSS in the app/assets/stylesheets/application.css file (unless your CSS is very limited). Instead, structure your CSS in multiple files. CSS that is used on only a single page can go in a file with a name that matches the page. Or, if sections of the website share common elements, such as themes for landing pages or administrative pages, make a file for each theme. How you organize your CSS is up to you; the asset pipeline lets you organize your CSS so it is easier to develop and maintain. Just add the files to the app/assets/stylesheets/ folder. Its not obvious from the name of the app/assets/stylesheets/application.css file that it serves as a manifest file as well as a location for miscellaneous CSS rules. For most websites, you can ignore its role as a manifest file. In the comments at the top of the file, the *= require_self directive indicates that any CSS in the file should be delivered to the browser. The *= require_tree . directive (note the Unix dot operator) indicates any files in the same folder, including files in subfolders, should be combined into a single file for delivery to the browser. If your website is large and complex, you can remove the *= require_tree . directive and specify individual files to be included in the file that is generated by the asset pipeline. This gives you the option of reducing the size of the application-wide CSS file that is delivered to the browser. For example, you might segregate a file that includes CSS that is used only in the sites administrative section. In general, only large and complex sites need this optimization. The speed of rendering a single large CSS file is faster than fetching multiple files.

Rename the application.css File

Its a good idea to rename the app/assets/stylesheets/application.css file as app/assets/ stylesheets/application.css.scss. Youll add the .scss file extension. This will allow you to use the advantages of an improved syntax for your application stylesheet. Rename the file now:
$ git mv app/assets/stylesheets/application.css app/assets/stylesheets/application.css.scss

14

144

CSS Styling with Sass

Ordinary CSS is not a programming language so CSS rules are verbose and often repetitive. The Sass project extends CSS to give it more powerful programming language features. With Sass, your stylesheets can use variables, mixins, and nesting of CSS rules. You can create a variable such as $blue: #3bbfce and specify colors anywhere using the variable, for example, border-color: $blue . Mixins are like variables that let you use snippets of reusable CSS. Nesting eliminates repetition by layering CSS selectors. Sass has two syntaxes. The most commonly used syntax is known as SCSS (for Sassy CSS), and is a superset of the CSS syntax. This means that every valid CSS stylesheet is valid SCSS as well. SCSS files use the extension .scss. The Sass project also offers a second, older syntax with indented formatting that uses the extension .sass. Well use the SCSS syntax. You can use Sass in any file by adding the file extension .scss. The asset pipeline will preprocess any .scss file and expand it as standard CSS. For more on the advantages of Sass and how to use it, see the Sass website or the Sass Basics RailsCast from Ryan Bates.

Adding Twitter Bootstrap

Twitter Bootstrap and other CSS front-end frameworks are toolkits that provide the kind of structure and convention that make Rails popular for back-end development. Twitter Bootstrap provides a standard grid for layout plus dozens of reusable components for common page elements such as navigation, forms, and buttons. Visit the Bootsnipp.com gallery for dozens of additional page elements and code snippets. The Bootstrap Hero site offers a Big Badass List of Useful Twitter Bootstrap Resources.

Twitter Bootstrap Gem

Several options are available for installing Twitter Bootstrap in a Rails application. Gems are available for either the native Bootstrap LESS language or the Sass language that is the default for CSS files in Rails. Sass is a default for CSS development in Rails so I recommend using Thomas McDonalds bootstrap-sass gem to add Twitter Bootstrap. In your Gemfile, youve already added:
gem 'bootstrap-sass', '~> 2.3.2.2'

and previously run

$ bundle install

14

145

Add Twitter Bootstrap CSS

Add a file app/assets/stylesheets/bootstrap_and_overrides.css.scss containing:
@import "bootstrap"; body { padding-top: 60px; } @import "bootstrap-responsive";

The file app/assets/stylesheets/bootstrap_and_overrides.css.scss is automatically included and compiled into your Rails application.css file by the *= require_tree . statement in the app/assets/stylesheets/application.css.scss file. The file will import both basic Bootstrap CSS rules and the Bootstrap rules for responsive design (allowing the layout to resize for various devices and screen sizes). The CSS rule body { padding-top: 60px; } applies an additional CSS rule to accommodate the Bootstrap navigation bar heading created by the navbar-fixed-top class in the header tag in the layout below. You could add the Bootstrap @import code to the app/assets/stylesheets/application.css.scss file. However, I recommend adding the separate app/assets/stylesheets/ bootstrap_and_overrides.css.scss file. You may wish to modify the Twitter Bootstrap CSS rules; placing changes to Twitter Bootstrap CSS rules in the bootstrap_and_overrides.css.scss file will keep your CSS better organized.

Add Twitter Bootstrap JavaScript

On this project, well use Twitter Bootstrap for CSS only. But well set up the Twitter Bootstrap JavaScript component in case you choose to extend the project. Include the Twitter Bootstrap JavaScript files by modifying the file app/assets/javascripts/ application.js:
//= //= //= //= //= require jquery require jquery_ujs require turbolinks require bootstrap require_tree .

Youll see you need to add the directive

//= require bootstrap

before

//= require_tree .

Like the application.css.scss file, the application.js file is a manifest that allows a developer to designate the JavaScript files that will be combined for delivery to the browser.

14

146

CSS Example
Well add a nice gray box as a background to page content. This gives us an example of adding a CSS rule that will be used on every page of the application. Add this to your app/assets/stylesheets/application.css.scss file for a gray background:
.content { background-color: #eee; padding: 20px; margin: 0 -20px; -webkit-border-radius: 0 0 6px 6px; -moz-border-radius: 0 0 6px 6px; border-radius: 0 0 6px 6px; -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15); -moz-box-shadow: 0 1px 2px rgba(0,0,0,.15); box-shadow: 0 1px 2px rgba(0,0,0,.15); }

The CSS code applies styling to a .content class. It sets background color, a border and shadow, padding and margin. Its complicated by accommodating differences among web browsers.

Default Application Layout with Twitter Bootstrap

In the last chapter, we configured the default application layout with HTML5 elements, navigation links, and flash messages. Now that weve installed Twitter Bootstrap, we can style the page with Bootstraps built-in CSS components. You can choose from dozens of Bootstrap CSS components; well use the navigation components with the Bootstrap 12-column grid. Replace the contents of the file app/views/layouts/application.html.erb with this:
<!DOCTYPE html> <html> <head> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title><%= content_for?(:title) ? yield(:title) : "Learning Rails" %></title> <meta name="description" content="<%= content_for?(:description) ? yield(:description) : "Learning Rails" %>"> <%= stylesheet_link_tag "application", :media => "all" %> <%= javascript_include_tag "application" %> <%= csrf_meta_tags %> </head> <body>

14

147 <header class="navbar navbar-fixed-top"> <nav class="navbar-inner"> <div class="container"> <%= render 'layouts/navigation' %> </div> </nav> </header> <main role="main"> <div class="container"> <div class="content"> <div class="row"> <div class="span12"> <%= render 'layouts/messages' %> <%= yield %> </div> </div> <footer> </footer> </div> </div> </main> </body> </html>

We wrap the navigation partial classes.

render 'layouts/navigation'

with the Bootstrap navigation

We wrap both the flash messages partial render 'layouts/messages' and the main page content rendered by yield with Bootstrap row and span classes. We also apply the content class for the nice gray box around the main page content.

Set up SimpleForm with Twitter Bootstrap

One of the requirements for our tutorial application is a contact form. We could set up styling for the form when we implement the contact page, but it is convenient to set up form styling now, as we would if we were adding multiple forms to the site. Rails provides a set of view helpers for forms. They are described in the RailsGuides: Rails Form Helpers document. But, as youve learned, Rails has more than one stack, and most developers use an alternative set of form helpers named SimpleForm, provided by the SimpleForm gem. The SimpleForm helpers are more powerful, easier to use, and offer an option for styling with Twitter Bootstrap. The SimpleForm and Twitter Bootstrap Demo shows what you can expect. In your Gemfile, youve already added:

14

148 gem 'simple_form', '>= 3.0.0.rc'

and previously run

$ bundle install

Run the generator to install SimpleForm with a Twitter Bootstrap option:

$ rails generate simple_form:install --bootstrap

which installs several configuration files:

config/initializers/simple_form.rb config/initializers/simple_form_bootstrap.rb config/locales/simple_form.en.yml lib/templates/erb/scaffold/_form.html.erb

You previously used the rails generate command to set up configuration files with the Figaro gem. Any gem that needs default files can use the rails generate command to run a simple script that creates files. Here the SimpleForm gem uses the generator command to create files for initialization and localization (language translation). SimpleForm can be customized with settings in the initialization file. Well use the defaults.

Test the Application

Lets see how the application looks with Twitter Bootstrap. The web server may already be running. If not, enter the command:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. The links are broken because we havent yet created About and Contact pages. Well add those next.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "stylesheets" $ git push

14

149

Chapter 20

Add Pages
Lets begin adding pages to our web application. There are three types of web pages in a Rails application. Weve looked at two types so far: static pages in the public/ folder that contain no Ruby code dynamic pages such as our home page that use the application layout Theres another type of web page that is required on many websites. It has static content; that is, no dynamic data is needed on the page. But it uses the default application layout to maintain consistency in the website look and feel. We classify this type of page as a: static view that uses the application layout Examples include: About page Legal page FAQ page Its possible to place these pages in the public/ folder and copy the HTML and CSS from the default application layout but this leads to duplicated code and maintenance headaches. And dynamic elements such as navigation links cant be included. For these reasons, developers seldom create static pages in the public/ folder. Alternatively, a dynamic page can be created that has no model, a nearly-empty controller, and a view that contains no instance variables. This solution is quite common for static views that use the application layout. This solution is implemented so frequently that many developers create a gem to encapsulate the functionality. Were going to use the best-known of these gems, the high_voltage gem created by the Thoughtbot consulting firm. First well use the HighVoltage gem to create an About Page. Then well begin an exercise to create a Contact page. Initially well use the HighVoltage gem. Then well add a controller to process the form. And finally well discard the page we created with the HighVoltage gem and replace it with a full model-view-controller implementation. The process will show the difference between an older form of web application architecture and a newer Rails way.

14

150

HighVoltage Gem
We can add a page using the HighVoltage gem almost effortlessly. The gem implements Rails convention over configuration so well that there is nothing to configure. There are alternatives to its defaults which can be useful but we wont need them; visit the GitHub home page for the high_voltage gem if you want to explore all the options. In your Gemfile, youve already added:
gem 'high_voltage'

and previously run

$ bundle install

Views Folder
Create a folder app/views/pages:
$ mkdir app/views/pages

Any view files we add to this directory will automatically use the default application layout and appear when we use a URL that contains the filename. The HighVoltage gem contains all the controller and routing magic required for this to happen. Lets try it out.

About Page
Create a file app/views/pages/about.html.erb:
<% content_for :title do %>About<% end %> <h3>About Foobar Kadigan</h3> <p>He was born in Waikikamukau, New Zealand. He left New Zealand for England, excelled at the University of Mopery, and served in the Royal Loamshire Regiment. While in service, he invented the kanuten valve used in the processing of unobtainium for industrial use. He founded Acme Manufacturing, later acquired by the Advent Corporation, to commercialize the product. Mr. Kadigan is now retired and lives in Middlehampton where he raises Griadium frieda.</p> <p>His favorite quotation is:</p> <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>

15

151

Our simple About view will be combined with the default application layout by the HighVoltage gem. We include a
content_for

Rails view helper that passes a page title to the application layout.

Contact Page
For the initial version of the Contact page, create a file app/views/pages/contact.html.erb:
<% content_for :title do %>Contact<% end %> <h3>Contact</h3>

This is a placeholder page well use to test the navigation link weve already created. We include a
content_for

Rails view helper that passes a page title to the application layout.

Routing for the HighVoltage Gem

The HighVoltage gem provides a PagesController. Youll never see it; it is packaged inside the gem. In addition to providing a controller, the HighVoltage gem provides default routing so any URL with the form http://localhost:3000/pages/about will obtain a view from the app/ views/pages directory. Like the PagesController, the code that sets up the route is packaged inside the gem. If we wanted to add the route explicitly to the file config/routes.rb, the file would look like this:
LearnRails::Application.routes.draw do get "/pages/*id", to: 'pages#show' root to: 'visitors#new' end

Again, you dont need to add the code above because the HighVoltage gem already provides the route. For details about the syntax of routing directives, refer to RailsGuides: Routing from the Outside In. You can use a Rails route helper to create a link to any view in the app/views/pages directory like this:

15

152 link_to 'About', page_path('about')

We already have links to the About and Contact pages in the navigation partial so we can test the application immediately.

Test the Application

The web server may already be running. If not, enter the command:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Links to the pages About and Contact should work.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "add 'about' and 'contact' pages" $ git push

There is nothing more we need for our About page. In the next chapter, well explore two different implementations for the Contact page.

15

153

Chapter 21

Contact Form
Forms are ubiquitous on the web, to the degree we seldom notice how often they are used for data entry, whether were logging into a website or posting a blog comment. A contact form is common on many websites. If you think about it, contact forms are often unnecessary; simply displaying an email address is sufficient, more convenient, and easier to implement. But building a contact form is an excellent way to learn how to handle user data input. Well pretend that our odd client, Mr. Foobar Kadigan, insists that he needs a contact form on his website. Were not backing the tutorial application with a database so we wont store the contact data after the information is submitted. Instead, in a subsequent chapter well learn how to send the contents of the form by email to the website owner.

The Old Way and the Rails Way

In this chapter, well explore two ways to implement a contact form. The first way will be familiar to anyone who has used PHP or similar web platforms. It is an obvious and straightforward way to handle a form. As we look closer, well see the approach has limitations. Well discard our first approach and rebuild the Contact page, discovering how the Rails way is more powerful. You may wonder why Im going to show you two different ways to implement the contact form. First, it is worthwhile to see there is more than one way to implement a web application. Maturity as a software developer means imagining different approaches and evaluating your options. With this exercise, youll contrast two approaches and see how we make choices about software architecture. More importantly, it is not always obvious why we do things in a Rails way. It would be easy to simply walk you through the steps to build a contact form without showing you alternative implementations (thats how most tutorials do it). But youll gain a deeper understanding of Rails by building the contact form in a less sophisticated fashion and then seeing the more elegant Rails approach.

User Story
Lets plan our work with a user story:

15

154 *Contact Page* As a visitor to the website I want to fill out a form with my name, email address, and some text In order to send a message to the owner of the website

Our first step will be to create a route to a controller that will process the submitted form.

Routing
Were going to create a ContactsController to process the submitted form data. Every form must have a destination URL that receives the form submission. We need to set a route to generate the destination URL. Open the file config/routes.rb. Replace the contents with this:
LearnRails::Application.routes.draw do post 'contact', to: 'contacts#process_form' root to: 'visitors#new' end

The route post 'contact', to: 'contacts#process_form' will create a route helper that generates a URL and hands off the request to a controller:
contact_path contacts

route helper

name of the controller (ContactsController) a controller action well create

process_form

http://localhost:3000/contact URL generated by the route helper

POST

HTTP method to submit form data

rake routes

You can run the

$ rake routes Prefix Verb contact POST root GET page GET

command to see our routes in the console:

URI Pattern /contact(.:format) / /pages/*id

Controller#Action contacts#process_form visitors#new high_voltage/pages#show

The output of the routes we need.

rake routes

command is somewhat cryptic but confirms weve created the

For details about the syntax of routing directives, refer to RailsGuides: Routing from the Outside In.

15

155

The route wont work; we need to create a ContactsController. But first well create the form.

Adding a Form to the Contact Page

Youll recall that we set up the SimpleForm gem when we added Twitter Bootstrap to our application. The SimpleForm gem provides Rails view helpers for forms. Youll remember that we described Rails view helpers as macros to generate HTML. The SimpleForm gem gives us view helpers to generate all the HTML required by complex forms. Forms require some of the most complex HTML a developer will encounter, so the SimpleForm gem is truly worthwhile. You can see a demonstration of SimpleForm and Twitter Bootstrap for all the possible form elements. Lets add the code for a contact form to the Contact page. Replace the contents of the file app/views/pages/contact.html.erb:
<% content_for :title do %>Contact<% end %> <h3>Contact</h3> <%= simple_form_for :contact, url: contact_path do |form| %> <%= form.input :name, autofocus: true %> <%= form.input :email %> <%= form.input :content, as: :text, :input_html => { :class => "span6" } %> <%= form.button :submit, 'Submit', class: 'btn-primary' %> <% end %>

The code is compact but complex. We see several elements:

content_for

is a view helper that passes a page title to the application layout is the view helper for the form

simple_form_for

The simple_form_for view helper instantiates a form object which we assign to a variable named form . SimpleForm offers many standard form elements, such as text fields and submit buttons. Each element is available as a method call on the form object. The view helper
simple_form_for

requires parameters and a block.

Every form needs a name and a route in the application that will handle processing of the form data. The parameters are:
contact url

the name of the form

a destination for the form data

Later, when we change this form to accommodate the Rails way, well replace these two parameters with a single instance variable. The magic of Rails will generate the name of the

15

156

form and the destination URL from the instance variable. For now, to implement the old way, we supply the name of the form and the destination URL. The simple_form_for view helper accommodates a Ruby block. The block begins with do and closes with end . The code inside the block works just like code inside a method. In this case, the form object is passed to the block and methods belonging to the form object are called to produce HTML output. Inside the block, the a name field an email field a content field a submit button Each of the form methods takes various parameters, such as:
autofocus as: :text input_html class form

object methods generate HTML for:

displays the cursor in the field displays a multiline text area adds any HTML such as a CSS class

applies a CSS class to modify a buttons appearance

The structure of the form is clearly visible in the code. The form begins with a simple_form_for helper and closes with the end keyword. Each line of code produces an element in the form such as a field or a button. This is a common structure for a Rails view helper and it will soon become familiar.

Controller
We need code to process the form data. The form data is sent to the server as a POST request attached to a URL. As weve learned, in Rails we use controllers to respond to browser requests. For this implementation, well create a ContactsController to process the submitted form data. Create a file app/controllers/contacts_controller.rb:
class ContactsController < ApplicationController def process_form Rails.logger.debug "DEBUG: params are #{params}" flash[:notice] = "Received request from #{params[:contact][:name]}" redirect_to root_path

15

157 end end

The ContactsController inherits the behavior of the base ApplicationController. We create a process_form method to respond when the form is submitted. Later well learn that process_form doesnt fit the Rails way. Well use it for now. Before we look closely at the code for the params hash.
process_form

method, we need to learn about the

Params Hash
Take a close look at these two lines:
Rails.logger.debug "DEBUG: params are #{params}" flash[:notice] = "Received request from #{params[:contact][:name]}"

Notice the

params

object.

Earlier we learned about the Ruby Hash class. It is a data structure for key/value pairs and Hash instances are ideal for storing form data. Each field on the form can be mapped as label and data, or key and value, and stored in a Hash. Rails does all the work of extracting the form data from the browsers POST request. Rails creates a hash with the form field data mapped to the form field labels and gives the hash the name of the form. Heres the hash as pure Ruby code:
contact = {name: 'Daniel' , email: '[email protected]', contents: 'hi!'}

Rails goes a step further and nests the form hash inside another hash named As pure Ruby code, the
params

params

hash looks like this:

params = {controller: 'contacts', action: 'process_form', contact: {name: 'Daniel' , email: '[email protected]', content: 'hi!'} }

The

params

hash includes these elements (plus others we wont cover):

current controller

15

158

current action form data (our

contact

hash)

You will see the contents of the params hash in the console log after you submit the form. Well look at the console log when we test the implementation.

Process_form Method
Now that we know about the
params

hash, take a look again at the

process_form

method:

def process_form Rails.logger.debug "DEBUG: params are #{params}" flash[:notice] = "Received request from #{params[:contact][:name]}" redirect_to root_path end

We use a logger.debug method to reveal the form data in our console log by revealing the contents of the params hash. Then we extract the data posted to the name field of the form and construct a flash message. A hash containing the data from the contact form is nested inside the params hash. We can retrieve the value of the name field with the expression params[:contact][:name] . We use double quotes and string interpolation to form the message using the #{...} syntax that evaluates a Ruby expression and combines it with a string. Finally we use the
redirect_to

directive to render the home page.

We havent actually sent the contact data to anyone. Well add code for that later, after we refactor the controller to be a better example of the Rails way. Before we do that, lets test the current implementation. Weve already set up routing for the new controller.

Test the Application

If you need to start the server:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Click the Contact link; then fill out and submit the form.

15

159

You should see the flash message Received request from on the home page. If you see the message My birthday is soon you need to delete your earlier experiment from the Visitors controller. Notice what appears in the console log:
Started POST "/contact" for 127.0.0.1 at ... Processing by ContactsController#process_form as HTML Parameters: {"utf8"=>"", "authenticity_token"=>"rQJfWNurHbEI3RBj/ myfUkcbkeX5cgQ06y4y91Jqthw=", "contact"=>{"name"=>"Daniel Kehoe", "email"=>"[email protected]", "content"=>"Looking forward to your birthday!"}, "commit"=>"Submit"} DEBUG: params are{"utf8"=>"", "authenticity_token"=>"rQJfWNurHbEI3RBj/ myfUkcbkeX5cgQ06y4y91Jqthw=", "contact"=>{"name"=>"Daniel Kehoe", "email"=>"[email protected]", "content"=>"Looking forward to your birthday!"}, "commit"=>"Submit", "action"=>"process_form", "controller"=>"contacts"} Redirected to http://localhost:3000/ Completed 302 Found in 0ms (ActiveRecord: 0.0ms)

The console log is our most important tool for debugging. Lets analyze what we see: Started POST shows the server is responding to an HTTP POST request /contact the path portion of the URL for 127.0.0.1 the IP address for localhost at timestamp Processing by ContactsController the controller process_form the controller action (the method that handles the request) as HTML not XML or some other markup Parameters: the
params

hash containing all the submitted data

utf8=>"" a Rails workaround to set the language encoding in Internet Explorer authenticity token prevents CSRF security exploits contact a hash containing the form data commit the Submit label from the button DEBUG our debug message containing the form data Redirected to http://localhost:3000/ responded by displaying the home page Completed 302 Found HTTP response status code 302 indicating a redirection in 0ms time required to process the request

15

160

Thats a lot of data. For now, we really only care about the form data buried in the hash.

params

You can see that we really dont need the debug message because the console log shows us the contents of the params hash.

The Validation Problem

It looks like weve got everything we need to handle a form submission. As a next step, we could implement code to send an email message using form data extracted from the params hash. But consider a potential problem. What if the email address is poorly formed? The visitor will think the message has been sent but it will never be delivered. Or what if the name field or message is blank? Its not just a problem for the hapless visitor. An evildoer could repeatedly click the submit button, filling Foobar Kadigans email inbox with endless empty messages. We need validation of the form data before we process it. We could dig into the Rails String API and look for a way to test if the string is empty or contains only whitespaces. And we could raise an Exception if the string is blank. Heres what validation code could look like. We wont use this code (because theres a better way to do this):
class ContactsController < ApplicationController def process_form if params[:contact][:name].blank? raise 'Name is blank!' end if params[:contact][:email].blank? raise 'Email is blank!' end if params[:contact][:content].blank? raise 'Message is blank!' end message = "Received request from #{params[:contact][:name]}" redirect_to root_path, :notice => message end end

We would need additional code to test for invalid email addresses (it will be a complex regex, or regular expression). And we would need a nicer way of showing the error to the visitor

16

161

(right now, raising the exception displays an error message that makes it appear the application is broken). If we were implementing this on another web application platform, we might go further down this path, googling for code examples, and implementing a lengthy but bulletproof validation function. Rails offers a better way.

Implementing the Rails Way

Our initial implementation of the contact form is consistent with the earliest approach to web application development, an approach that originated in 1993 with a specification for CGI, the Common Gateway Interface. Before CGI, every page on the web existed only as a static HTML file. CGI made it possible to run a program, or CGI script, that dynamically generated HTML. In the early years of the web, every web URL matched either an HTML file or a CGI script. This is the page paradigm of the web. So far, were following the page paradigm. Our Contact page hosts the form. Clicking the submit button makes a request to another page that is actually a program that returns HTML. Until the late 1990s, this is how the web worked. But soon after the introduction of CGI, developers began exploring the possibility of running a single program (an application server) that responds to any URL, parsing the URL to establish routing, and generating pages dynamically. This was the genesis of the web application paradigm. Its how Rails works. The web application paradigm frees us from one-to-one correspondence of a URL with a single file or script. It allows us to refactor our code into object-oriented classes and methods that can be inherited rather than duplicated, which means we dont repeat the same code on every page that processes a form. The web application paradigm makes it possible to use the model-view-controller architecture. Instead of looking at the web as URLs that return pages, we see requests that are routed to controllers that render views. We can segregate any code that manipulates data into a model class, instead of mixing HTML with data manipulation in a single script. With the web application paradigm, we can have a generic model class that isolates the code that connects to a database or validates form data. We can create models that inherit the generic behavior from a parent class and get a database connection or validation for free. Unlike the page paradigm, well avoid duplicating validation code every time we need to process a form. Consider our
process_form

method again:

class ContactsController < ApplicationController def process_form if params[:contact][:name].blank? raise 'Name is blank!'

16

162 end if params[:contact][:email].blank? raise 'Email is blank!' end if params[:contact][:content].blank? raise 'Message is blank!' end message = "Received request from #{params[:contact][:name]}" redirect_to root_path, :notice => message end end

Our segregation of concern philosophy suggests that validation belongs in a model, since validation is a type of data manipulation (strictly speaking, a test of data integrity). Furthermore, it would be nice to make the validation tests generic so they could be used to validate data submitted from any form. Rails, as a framework, provides all this for us.

ActiveRecord
Rails extracts and generalizes common code that every website requires. The code that websites need for access to databases is abstracted into the Rails ActiveRecord class. ActiveRecord includes code from the ActiveModel class that handles interaction with forms and data validation. The ActiveRecord class interfaces with SimpleForm to provide sophisticated validation and error handling. We can inherit behavior from the ActiveRecord class to add validation and error handling to any model we create. SimpleForm will recognize ActiveRecord methods if we provide a model as an argument to the SimpleForm view helper. SimpleForm will give the form a name that matches the model name. And SimpleForm will automatically generate a destination URL for the form based on the model name. More significantly, SimpleForm will add sophisticated error handling to the form. If a visitor doesnt enter a name or submits an invalid email address, and we declare in our model that we require validation, SimpleForm will highlight the invalid field and display an inline message indicating the problem. Compared to what weve implemented so far, this kind of error handling provides a vastly superior user experience. Instead of displaying a message that the application failed, the form will be redisplayed with the problem marked and noted. Now that weve seen the advantages of the Rails way, lets re-implement our contact form using the model-view-controller architecture.

16

163

Model
When we build database-backed applications with Rails, we base our models on a parent class named ActiveRecord. We are not using a database for our tutorial application, so well use the activerecord-tableless gem to disable the database features of ActiveRecord. Note: Theres another way to create a model without a database using only the ActiveModel class, described in the RailsCasts: ActiveModel screencast. Either approach is fine; were using the activerecord-tableless gem because a tableless implementation using ActiveModel requires an understanding of Ruby modules, get and set methods, and object initialization. Its just easier to use the activerecord-tableless gem. Lets set up a model that inherits from ActiveRecord. Create a file app/models/contact.rb:
class Contact < ActiveRecord::Base has_no_table column :name, :string column :email, :string column :content, :string validates_presence_of :name validates_presence_of :email validates_presence_of :content validates_format_of :email, :with => /\A[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}\z/i validates_length_of :content, :maximum => 500 end

We give the model the name Contact and inherit from the ActiveRecord class. We use the has_no_table directive from the activerecord-tableless gem to disable database features of ActiveRecord. We specify attributes (data fields) for the model by using the column keyword from the activerecord-tableless gem. These match the fields in the contact form. ActiveRecord gives us validation methods named validates_presence_of , validates_format_of , and validates_length_of . We check that name , email , and content exist (no blanks are allowed). We provide a complex regex, or regular expression, to test if the email address is valid. Finally, we declare that the message content cannot exceed 500 characters. The model is elegant. We describe the fields we need and state our validation requirements. ActiveRecord does all the rest.

16

164

Lets change our contact form to use our new model.

Remove the Contact Page

Were implementing a model-view-controller architecture for our Contact feature. That means we have a Contact model, a ContactsController, and well need view files in the app/ views/contacts/ folder. Start by removing the file app/views/pages/contact.html.erb.
$ rm app/views/pages/contact.html.erb

In a minute, well replace it with a file in the app/views/contacts/ folder. Lets create the app/views/contacts/ folder:
$ mkdir app/views/contacts/

Change Navigation Links

Now that weve removed the file app/views/pages/contact.html.erb, well change the navigation links. Change the file app/views/layouts/_navigation.html.erb:
<ul class="nav"> <li><%= link_to 'Home', root_path %></li> <li><%= link_to 'About', page_path('about') %></li> <li><%= link_to 'Contact', new_contact_path %></li> </ul>

Our new route new_contact_path doesnt yet exist. Well complete our move to the modelview-controller architecture by adding the appropriate routes. Next well add a new Contact page.

Create a New Contact Page

Earlier, I said SimpleForm configures itself if we provide a model that inherits from ActiveRecord. SimpleForm gives the form a name that matches the model name. And SimpleForm generates a destination URL based on the model name.

16

165

Well soon create a controller that assigns the Contact model to the @contact instance variable. Well use that as an argument for the SimpleForm view helper: simple_form_for @contact do |form| ... end . Well also add an
error_notification

method provided by the form object.

Create a file app/views/contacts/new.html.erb:

<% content_for :title do %>Contact<% end %> <h3>Contact</h3> <%= simple_form_for @contact do |form| %> <%= form.error_notification %> <%= form.input :name, autofocus: true %> <%= form.input :email %> <%= form.input :content, as: :text, :input_html => { :class => "span6" } %> <%= form.button :submit, 'Submit', class: 'btn-primary' %> <% end %>

The form is the same as we used before, but were now providing only one argument, the @contact instance variable, to the SimpleForm view helper. Thats enough to generate the form name and destination URL. SimpleForm uses the @contact instance variable to name the form, set a destination for the form data (the ContactsController#create action), and initialize each field in the form using attributes from the Contact model. Setting the values for the form fields from the attributes in the model is called binding the form to the object and you can read about it in the RailsGuides: Form Helpers article. Weve added the error_notification method which provides all the error handling. The method call is very simple but the results will be impressive. Well need a controller and routing to complete our model-view-controller architecture. But first, well detour to learn about seven standard controller actions.

Seven Controller Actions

Consider all the possibilities for managing a list. Its a list of anything: users, inventory, thingamajigs. We use a web application to manage the list, so well fill out a form to record each item in our list. The web application offers seven features to help us manage our records: index display a list of all items show display a record of one item new display an empty form

16

166

create save a record of a new item edit display a record for editing update save an edited record destroy delete a record You can manage any list using these seven actions. There are a few extra actions that are helpful, such as: pagination displaying a portion of a list sorting displaying the list in a different order bulk edit changing multiple items at once But seven basic actions are all you need for managing any list of items. The Rails way is about taking advantage of structure and convention to leverage the power of the framework. The ApplicationController contains code to implement each of the seven standard actions. When we create a controller that inherits from the ApplicationController, we get these standard actions for free. Thats why our new method in our VisitorsController was so simple. The controller knew to render a view file named new.html.erb from the views/ visitors/ folder because of behavior inherited from the ApplicationController. Just like the Rails directory structure provides consistency to make it easy for any Rails developer to collaborate with other Rails developers, relying on the seven standard controller actions makes it easy for other team members to understand how your controllers work. When necessary, you will add other controller actions. For example, imagine youve built a subscription website. When a users subscription ends, you may not want to destroy the subscriber record. Instead you might add a controller expire or suspend action that marks the subscriber record as expired so you can continue to access the subscribers contact information for customer service or renewal offers. To the extent you can, use the seven standard controller actions and be cautious about adding more. Earlier, I said our ContactsController process_form method isnt suitable for the Rails way. With our model-view-controller architecture, we can piggyback on the ApplicationController to display our empty contact form and process the form when it is submitted. Well use only two of the seven standard controller actions: new display the empty contact form create validate and process the submitted form

16

167

Our ContactsController will know to render a view from the app/views/contacts/ new.html.erb file when we call the controller new method. We wont piggyback on behavior from the ApplicationController create method. But well implement a create method because, by convention, the form will submit the data to the controllers create method. SimpleForm will create a destination URL that corresponds to the ContactsController#create action.

Controller
Replace the contents of the file app/controllers/contacts_controller.rb:
class ContactsController < ApplicationController def new @contact = Contact.new end def create @contact = Contact.new(secure_params) if @contact.valid? # TODO save data # TODO send message flash[:notice] = "Message sent from #{@contact.name}." redirect_to root_path else render :new end end private def secure_params params.require(:contact).permit(:name, :email, :content) end end

Weve dropped the old school create methods.

process_form

method and added the Rails way

new

and

The controller new action will instantiate an empty Contact model, assign it to the @contact instance variable, and render the app/views/contacts/new.html.erb view. Weve already created the view file containing the form.

16

168

SimpleForm will set a destination URL that corresponds to the ContactsController#create action. The create method will instantiate a new Contact model using the data from the form (we take steps to avoid security vulnerabilities firstmore on that later). The ActiveRecord parent class provides a method valid? which we can call on the Contact model. Our conditional statement if @contact.valid? checks each of the validation requirements weve set in the model. If all the Contact fields are valid, we can save data (not yet implemented), send a message (not yet implemented), prepare a flash message, and redirect to the home page. Notice that we dont need to dig into the params hash for the visitors name; it is now available as @contact.name directly from the model. If any validation fails, the controller create action will render the app/views/contacts/ new.html.erb view. This time, appropriate error messages are set and the form objects error_notification method will highlight the invalid field and display a matching prompt. Youre looking at the tightly bound interaction of the Rails way model, view, and controller. The only element we are missing is routing. But first, lets look closer at the steps we take to avoid security exploits.

Mass-Assignment Vulnerabilities
Rails protects us from a class of security exploits called mass-assignment vulnerabilities. Rails wont let us initialize a model with just any parameters submitted on a form. Suppose we were creating a new user and one of the user attributes was a flag allowing administrator access. A malicious hacker could create a fake form that provides a user name and sets the administrator status to true. Rails forces us to white list each of the parameters used to initialize the model. We create a method named secure_params to screen the parameters sent from the browser. The params hash contains two useful methods we use for our screening:
require(:contact)

makes sure that

params[:contact]

is present

permit(:name, :email, :content)

our white list

With this code, we make sure that params[:contact] only contains :name, :email, :content . If other parameters are present, they are stripped out. Rails will raise an error if a controller attempts to pass params to a model method without explicitly permitting attributes via permit . In older versions of Rails (before Rails 4.0), the mass-assignment exploit was blocked by using a white list of acceptable parameters with the attr_accessible keyword in a model.

16

169

Youll see this code in examples and tutorials that were written before Rails 4.0 introduced strong parameters in the controller.

Private Methods
If you paid close attention to the code you added to the Contacts controller, you may have noticed the keyword private above the secure_params method definition. This is a bit of software architecture that limits access to the secure_params method (plus any more methods we might add beneath it). Very simply, adding the private keyword restricts access to the secure_params method so only methods in the same class can use it. You might be puzzled; after all, how else could it be accessed? We havent explored calling methods from other classes, so Ill just say that without the private keyword, the secure_params method could be used from code anywhere in our application. In this case, we apply the private keyword because we want to be sure the secure_params method is only used in the ContactsController class. Its just a bit of best practice and for now, you can simply learn that secure_params method should be a private method. Now lets look at routing for controllers that are built the Rails way.

Routing
Rails routing is aware of the seven standard controller actions. In fact, it takes only one keyword (with one parameter) to generate seven different routes for any controller. The keyword is resources and supplying a name that matches a model and controller provides all seven routes. Open the file config/routes.rb. Replace the contents with this:
LearnRails::Application.routes.draw do resources :contacts, only: [:new, :create] root to: 'visitors#new' end

Here weve added

resources :contacts, only: [:new, :create]

. .

We only want two routes so weve added the restriction The

new

only: [:new, :create]

route has these properties:

new_contact_path

route helper

16

170

contacts new

name of the controller (ContactsController)

controller action

http://localhost:3000/contacts/new URL generated by the route helper The

GET

HTTP method to display a page route has these properties: route helper

create

contacts_path contacts create

name of the controller (ContactsController)

controller action

http://localhost:3000/contacts URL generated by the route helper

POST

HTTP method to submit form data

rake routes

You can run the

command to see these in the console:

$ rake routes Prefix Verb contacts POST new_contact GET root GET page GET

URI Pattern /contacts(.:format) /contacts/new(.:format) / /pages/*id

Controller#Action contacts#create contacts#new visitors#new high_voltage/pages#show

The output of the

rake routes

command shows weve created the routes we need.

Were ready to test the model-view-controller implementation of the Contact feature.

Test the Application

If you need to restart the server:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Click the Contact link; then fill out and submit the form. You should see the flash message Message sent from on the home page. Try submitting the form with a blank name. Youll see a warning message, Cant be blank, pointing to the name field.

17

171

Try submitting the form with an invalid email address such as me@foo. The form will redisplay with a message, Some errors were found, please take a look and next to the email field, is invalid. Combining SimpleForm error handling with ActiveModel validation is powerful. If a field is required but blank, SimpleForm will use JavaScript to point to the error before the form is submitted. If validation fails after the form is submitted, the page will redisplay and SimpleForm will display an appropriate error message.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "contact form" $ git push

Weve built a sophisticated Contact form. Now lets implement code to store the data in a Google Drive spreadsheet.

17

172

Chapter 22

Spreadsheet Connection
In the last chapter, we added a contact form to the website. When a visitor submits the form, we display an acknowledgment message. Now we want to capture the data for later analysis or review. Weve purposely chosen not to implement a database application so we can focus on web application basics. Though many Rails applications are backed by databases, a database adds complexity to a Rails application. One of the requirements that adds complexity is authentication and authorization. If data is stored in an application database, we have to implement access control so only an administrator can view it. Fortunately, Google Drive (formerly known as Google Docs) gives us an easy way to store and access our visitor data without a database. Its an elegant solution. We can use the Google Drive API (application programming interface) to save form data to a spreadsheet that is stored in Google Drive. We dont have to implement authentication and authorization in our application because Google Drive already manages user access. Our application will send the data to a spreadsheet and our imaginary client, Mr. Foobar Kadigan, can access the data on Google Drive. Like other computer-literate people in business, Mr. Kadigan has experience with spreadsheets. Making data available in a spreadsheet makes it easy for an administrator or a website owner to analyze or review the data.

User Story
Lets plan our work with a user story:
*Save Data to a Spreadsheet* As the owner of the website I want all contact requests saved in a spreadsheet In order to analyze the data

To implement the user story, lets create a feature that saves the data to Google Drive.

Google Drive Gem

Well use the google_drive gem to connect to the spreadsheet and save data.

17

173

The google_drive gem is a Ruby library to read and write data to spreadsheets in Google Drive. It provides convenient Ruby methods to wrap the Google Spreadsheets API. You can see all the features of the google_drive gem by reviewing the google_drive gem API. In your Gemfile, youve already added:
gem 'google_drive'

and previously run

$ bundle install

The google_drive gem requires a username and password to access your Google Drive account. In the Configure chapter, we set this in the config/application.yml file. You may have set up your Google account for 2-step verification, which sends a unique code to your mobile phone each time you log in from an unfamiliar device. If your Google account requires two-factor authentication, you can turn off 2-step verification or create a new Gmail account for use with this tutorial.

Implementation
We will use the API from the google_drive gem to write code that saves data to the spreadsheet. But where should we put the code? At first glance, it looks like it could be added to the controller. But is there somewhere else to put the code? When you ask such a question, you are putting on the cape of the software architect. Your decision will be both practical and aesthetic, aligning (hopefully) with tried-and-true software design patterns, and impacting the maintainability of the code. More than any other area of programming, this challenge requires skills honed by experience and informed by reading and discussion with peers. Given a choice of several places to insert the new code, the beginner might say, Does it really matter? and make an arbitrary decision. But to the experienced software engineer, the decision is at the heart of the craft. Lets consider our options. In this case, the form data is received by the controller. It would be a small extra step to add code to the Contacts controller create method to connect to Google Drive to save the visitors email address and contact message. The code will work, though seasoned Rails developers will raise an eyebrow. Why?

17

174

Skinny Controller, Fat Model

If you think about it, saving data to Google Drive is a data operation, and all data manipulation should be handled by a model. Rails is opinionated, which means there is often a Rails way that is preferred to other approaches. One of the slogans of the Rails way is skinny controller, fat model. The slogan exists to remind developers that separation of concerns makes more modular, maintainable programs. Data manipulation goes in a model. Controllers should contain only enough code to instantiate a model and render a web page. Consequently, well add a method to the Contacts model named update_spreadsheet that will use the google_drive gem to connect to Google Drive and save the data. Well call the @contact.update_spreadsheet method from the Contacts controller create method.

Modify the Contact Model

Well add our spreadsheet code to the Contact model. Replace the contents of the file app/models/contact.rb:
class Contact < ActiveRecord::Base has_no_table column :name, :string column :email, :string column :content, :string validates_presence_of :name validates_presence_of :email validates_presence_of :content validates_format_of :email, :with => /\A[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}\z/ i validates_length_of :content, :maximum => 500 def update_spreadsheet connection = GoogleDrive.login(ENV["GMAIL_USERNAME"], ENV["GMAIL_PASSWORD"]) ss = connection.spreadsheet_by_title('Learn-Rails-Example') if ss.nil? ss = connection.create_spreadsheet('Learn-Rails-Example') end ws = ss.worksheets[0] last_row = 1 + ws.num_rows ws[last_row, 1] = Time.new ws[last_row, 2] = self.name ws[last_row, 3] = self.email ws[last_row, 4] = self.content

17

175 ws.save end end

Well call the new

update_spreadsheet

method from the controller. class.

The google_drive gem gives us a

GoogleDrive

Create a connection to Google Drive by passing your credentials to the login method. Heres where we use the environment variables we set in the config/application.yml file using the figaro gem. We look for a spreadsheet named Learn-Rails-Example. The first time we attempt to save data, the spreadsheet will not exist, so we use the create_spreadsheet method to create it. If it already exists, the spreadsheet_by_title method will find it. A single spreadsheet file can contain multiple worksheets. Well use only one worksheet to store our data, designated as worksheet 0 (we count from zero). Here the code gets a little tricky. You might expect the API to provide an append row method. In fact, we have to retrieve a count of rows, and then add one, to calculate the row number of the last empty row. We add data on a cell-by-cell basis, by designating the row number and column number of a cell. We add the current date and time using the Ruby API method Time.new to the first cell in the last row. Then we add name , email , and content attributes to additional columns (we refer to the current instance of the class by using the keyword self). Setting the cell value doesnt save the data. We explicity call the worksheet update the worksheet.
save

method to

Modify the Contacts Controller

Our Contact model now has a method to save data to a spreadsheet. Well update the Contacts controller to save the data. Replace the contents of the file app/controllers/contacts_controller.rb:
class ContactsController < ApplicationController def new @contact = Contact.new end

17

176

def create @contact = Contact.new(secure_params) if @contact.valid? @contact.update_spreadsheet # TODO send message flash[:notice] = "Message sent from #{@contact.name}." redirect_to root_path else render :new end end private def secure_params params.require(:contact).permit(:name, :email, :content) end end

Weve added only one line, the

@contact.update_spreadsheet

statement.

When the visitor submits the form, the ContactsController#create action is called. The create method will instantiate a new Contact model using the data from the form after laundering the parameters. If the validation check succeeds, we save data to the spreadsheet, set a flash notice, and redisplay the home page. In only a few lines of code, weve added data storage using Google Drive.

Test the Application

Make sure the web server is running:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Click the Contact link and try submitting the form. Youll see an acknowledgment message. Youll get an error Error=BadAuthentication Info=InvalidSecondFactor if your Google account is set for 2-step verification. Change your Google account settings to turn off twofactor authentication if you want to complete the test successfully.

17

177

Visit your Google Drive account (Drive is in the navigation bar when you visit the Google Search or Gmail home pages). Youll see a list of Google Drive files. The newest one will be a Learn-Rails-Example spreadsheet. Open the file and you will see the data from the contact form. Whenever a visitor submits the contact form, the spreadsheet will update within seconds.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "save data to a spreadsheet" $ git push origin master

Weve got a fully functional contact form that stores data in a Google Drive spreadsheet. Now lets add the code to email the form data to the site owner.

17

178

Chapter 23

Send Mail
Email sent from a web application is called transactional email. As a website visitor, youve probably seen transactional email such as these messages: sign up confirmation email response to a password reset request acknowledgment of a purchase notice of a change to a user profile setting A web application can send email to a visitor. It can also send messages to its owner or webmaster. On large active sites, email notices can be impractical (an admin interface is better) but for our small-volume tutorial application, it makes sense to email the contact request directly to the site owner (Foobar Kadigan is retired and enjoys receiving email).

User Story
Lets plan our work with a user story:
*Send Contact Message* As the owner of the website I want to receive email messages with a visitor's name, email address, and some text In order to communicate with visitors

To implement the user story, lets create a feature that sends the contact data as an email message.

Implementation
Rails makes it easy to send email. The ActionMailer gem is part of any Rails installation. Implementation of email closely follows the model-view-controller architecture. To implement email, youll need: model view

17

179

mailer The mailer is similar to a controller, combining data attributes from a model with a view file. Any methods we add to the mailer class can be called from a controller, triggering delivery of an email message. The model can be any weve already created. In this case, well use the Contact model, since it gives us access to the visitors name, email address, and message. Well create a mail-specific view file in the app/views/user_mailer/ folder. Our folder for mail-specific views will go in the app/views/ directory as a sibling of the app/views/layouts folder. The Rails directory structure already gives us a folder app/mailers/ for the mailer class and, not surprisingly, it is a sibling of the app/controllers/ folder. We dont have to create the necessary folders and files manually, as the command runs a utility to create what we need.
rails generate

Create View Folder and Mailer

Use the
rails generate

command to create a mailer with a folder for views:

$ rails generate mailer UserMailer

The name of the mailer isnt important; well use The

rails generate

UserMailer

because it is obvious.

command will create one file and one folder:

app/mailers/user_mailer.rb app/views/user_mailer This implements our model-view-mailer architecture.

Edit the Mailer

Add a
contact_email

method to the mailer by editing the file app/mailers/user_mailer.rb:

class UserMailer < ActionMailer::Base default from: "[email protected]" def contact_email(contact) @contact = contact

17

180 mail(to: ENV["OWNER_EMAIL"], from: @contact.email, :subject => "Website Contact") end end

The UserMailer class inherits behavior from the ActionMailer class. Well create a method definition that assigns the contact argument to the instance variable @contact . Like a controller that combines a model with a view, our mailer class makes the instance variable available in the view. The name of the method isnt important; it can be anything obvious. Well use it in the ContactsController to trigger mail delivery. Like the render method in a web page controller, the ActionMailer parent class has a method that renders the view.
mail

Youll need to use your email address in the mailer. You should have already set an environment variable for your email address in the file config/application.yml. If you havent done so, do it now. By inserting the environment variable with your email address after to: , your inbox will receive the message. If Foobar Kadigan was a real person, wed supply his email address here. We need to insert a from address in two places. First there is a default, for all messages that do not set a from address. We will use [email protected] for the default from address. The email is originating from a web application that does not receive email, so this indicates the email address should not be used for replies. For emails going to website visitors, it would be best to provide a default email address for a customer service representative on the from line, so the recipient can easily reply. Were not sending email messages to visitors so we can ignore this nicety. For our contact_email method, well insert the email address of the visitor as the from address since we are sending a message to the site owner. This makes it easy for Foobar Kadigan to click reply when he is reading the contact messages in his inbox. You can see our use of the email attribute from the Contact model in the expression :from => @contact.email . Thats all we need for mailer class. Next well create a view containing the message.

Create Mailer View

There are two types of mailer views. One contains plain text, for recipients who dont like formatted email (some people still read email from the Unix command line). The other type contains HTML markup to provide formatting. Its good to create a message of both types, though most recipients will benefit from HTML formatting.

18

181

The mailer view for formatted email looks very similar to a web page view file. It contains HTML markup plus Ruby expressions embedded in <%= ... %> delimiters. In the UserMailer class, weve assigned the Contact model to the instance variable @contact so any attributes are available for use in the message. Create a file app/views/user_mailer/contact_email.html.erb:
<!DOCTYPE html> <html> <head> <meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /> </head> <body> <h1>Website Contact</h1> <p> This visitor requested contact: </p> <p> <%= @contact.name %><br/> <%= @contact.email %><br/> </p> <p> The visitor said: </p> <p> "<%= @contact.content %>" </p> </body> </html>

You can easily imagine how this view would look as a web page. Youll soon see it as an email message in your inbox. For those recipients who like plain text, create a view without HTML markup. Create a file app/views/user_mailer/contact_email.text.erb:
You received a message from <%= @contact.name %> with email address <%= @contact.email %>. The visitor said: "<%= @contact.content %>"

Youve created views for the email message. Now we can integrate our email feature with the ContactsController.

18

182

Modify Controller
Well add code to the ContactsController:
UserMailer.contact_email(@contact).deliver

Replace the contents of the file app/controllers/contacts_controller.rb:

class ContactsController < ApplicationController def new @contact = Contact.new end def create @contact = Contact.new(secure_params) if @contact.valid? @contact.update_spreadsheet UserMailer.contact_email(@contact).deliver flash[:notice] = "Message sent from #{@contact.name}." redirect_to root_path else render :new end end private def secure_params params.require(:contact).permit(:name, :email, :content) end end

The UserMailer class is available to any controller in the application. We call the contact_email method weve created, passing the @contact instance variable as an argument, which renders the email message. Finally, the deliver method initiates delivery. For more on sending email from a Rails application, see RailsGuides: Action Mailer Basics.

Test the Application

If your web server is not running, start it:
$ rails server

18

183

Open a web browser window and navigate to http://localhost:3000/. Click the Contact link and try submitting the form. The email message should be visible in the console. If you didnt get an email message in your inbox, make sure you set your config/ environments/development.rb file to perform deliveries as described in the tutorial Configuration chapter. Be sure to restart your server if you change the configuration file. You may see a warning message when you log into your Gmail account, indicating that someone used your credentials to send email. You can dismiss the warning as you know it was yourself.

Asynchronous Mailing
You may notice a delay in the responsiveness of the Contact form after adding the email feature. Unfortunately, theres a performance penalty with our new feature. Our controller code connects to the Gmail server and waits for a response before it renders the home page and displays the acknowledgment message. The performance penalty can be avoided by changing the implementation so that the controller doesnt wait for a response from the Gmail server. We call this asynchronous behavior because sending email does not need to be in sync with displaying the acknowledgment. Eliminating a delay improves the user experience and makes the site feel more responsive. Unfortunately, asynchronous mailing, which requires a queueing system, is an advanced topic for Rails developers. Earlier I wrote that Rails, as a framework, is not complete. This is an example. The developer community has explored the possibility of implementing a standard queueing system for Rails. In fact, an early version of Rails 4.0 contained a queueing system but it was dropped because it did not fully address several complicated issues (see What happened to the Rails 4 Queue API?). For our tutorial application, and for a typical small business website, the delay caused by lack of queueing is no big deal. Keep in mind, though, as you tackle bigger projects in Rails, you may need to learn how to implement a queueing system. Youll find examples in more advanced tutorials.

Git
Lets commit our changes to the Git repository.

18

184 $ git add -A $ git commit -m "sending mail" $ git push

Youve created a Rails application that handles a form and sends email to the site owner. Mail is a practical way to connect with site visitors. Lets implement a feature that collects email addresses for mass mailing of a newsletter.

18

185

Chapter 24

Mailing List
Even as other messaging avenues become increasingly popular, such as SMS text or Facebook messages, email remains the most practical way to stay in touch with website visitors. Encouraging a visitor to provide an email address means offering an invitation to a dialog and a relationship beyond a single visit. If you have a legitimate reason to stay in touch, and youve motivated the visitor to leave an email address, youll need a mailing list service. Youve seen how Rails can send an email message. From what youve seen so far, you can imagine it would not take much code to loop through a list of email addresses from a database, sending a message to each. In the early days of the web, it was easy for any system administrator to write a script for mass mailings. Since there is negligible cost to sending bulk email, unscrupulous and ignorant operators sent email to any address they could scrape, borrow, or steal. The resulting flood of spam made checking ones inbox an icky experience and destroyed much of the early culture of the Internet. Fortunately, services such as Gmail arose to filter email. There is now a thick (but leaky) layer of screening protocols that redirect spam to a junk folder. One reason you wont use a Rails application to send bulk email is that a web application server is not the most efficient tool for sending email. More significantly, theres a good chance your email wont go through or, if it does (and someone complains), youll quickly see your IP address blacklisted. Thats why we use mailing list services to send bulk email such as newsletters or promotional offers. Considerable expertise is required to keep email from being filtered as spam (see MailChimps article Email Delivery For IT Professionals). Email service providers increase reliability of delivery. These services track deliveries and show how well your email is being delivered. Youll also get features such as management of unsubscribe requests and templates to design attractive messages. There are at least a dozen well-established email service providers that allow a Rails application to programmatically connect to the service (via an API) to add or remove email addresses. For a list, see the article Send Email with Rails. For this tutorial application, well use MailChimp because there is no cost to open an account and you can send up to 12,000 emails/month to list of 2000 or fewer subscribers for free. Spam is unsolicited email. Dont ever send spam, whether for yourself, a client, or an employer. If recipients complain, your IP address and domain name will be blacklisted. So be very careful to only send to subscribers who signed up, send what subscribers expect, and be sure to offer value. If you get complaints, or the unsubscribe rate is high, stop. Well assume weve discussed the rules with Foobar Kadigan and he is eager to offer a newsletter to his visitors that will be genuinely appreciated.

18

186

User Story
Lets plan our work with a user story:
*Subscribe to Mailing List* As a visitor to the website I want to sign up for a mailing list In order to receive news and announcements

To implement the user story, well add a mailing list feature.

Implementation
Well use the Rails model-view-controller architecture. Well need: Visitors model view for visitors#new Visitors controller with
new

and

create

methods

routing for visitors#new and visitors#create Well add a Visitor model that has a data attribute for an email address. We already have a Visitors controller that renders the home page using the file in the app/views/visitors/ folder. Well replace the contents of the view file with a nice photo, a marketing message, and a form. Our Visitors controller new and create methods will be very similar to what we created for the Contacts controller. Instead of saving data to Google Drive, or connecting to Gmail to send a message, well call a method to save the visitors email address to a MailChimp mailing list.

Gibbon Gem
The Gibbon gem is a convenient wrapper for the MailChimp API. We could connect to the MailChimp API using other gems that provide low-level plumbing such as HTTP connections (httparty) and data parsing (multi_json), but other developers have already done the work of wrapping the plumbing in a higher-level abstraction that easily fits into a Rails application. Amro Mousas Gibbon gem is popular and actively maintained. In your Gemfile, youve already added:

18

187 gem 'gibbon'

and previously run

$ bundle install

Home Page
Earlier we built a home page that provided a simple demonstration of the Ruby language. Well discard it and replace it with a page that you could adapt for a typical small-business website. We want a nice photo, space for a marketing message, and the sign up form. Replace the contents of the file app/views/visitors/new.html.erb:
<% content_for :title do %>Foobar Kadigan<% end %> <% content_for :description do %>Website of Foobar Kadigan<% end %> <img src="http://lorempixel.com/1170/600/cats/1"> <div style="text-align: center; margin-top: 20px"> <div class="span4 offset2"> <h2>Stay in touch.</h2> </div> <div class="span4"> <div> <%= simple_form_for @visitor do |f| %> <%= f.error_notification %> <%= f.input :email, label: false, :placeholder => 'Your email address...' %> <br/> <%= f.submit "Sign up for the newsletter", :class => "btn btn-primary"%> <% end %> </div> </div> </div>

We include layout.

content_for

view helpers that pass a title and description to the application

We add a photo to the page with an <img> tag. Were taking a shortcut and using a placeholder photo from the lorempixel.com service. Much of the markup is divs to create layout. The first div creates a container with centered text, offset from the photo by 20 pixels. If we were being strict about separation of concerns, wed specify this rule in a CSS stylesheet instead of using a style attribute. The next two divs apply layout rules from Twitter Bootstrap to create two columns, one for our marketing message, and one for the form.

18

188

Our marketing message is merely a placeholder. For a real website, youd likely craft a stronger call to action than merely Stay in touch. The form is very similar to the form on the Contact page, except we initialize it with the @visitor instance variable and only need a field for an email address. We suppress display of the email field label with the flag label: false and use the :placeholder parameter to create a hint in the empty input field. A submit button will contain the text, Sign up for the newsletter, and we apply Twitter Bootstrap button styling.

Photo Options
Youre free to modify this page as you wish, as long as you keep the form intact. You might wish to modify the placeholder photo. If you dont like cats, try http://lorempixel.com/1170/600/nightlife/1 or any other categories from the lorempixel.com service. You can change the size by modifying the dimensions from 1170 (pixel width) by 600 (pixel height). You can replace the placeholder photo with your own. Look for the app/assets/images folder and add an image. Instead of the HTML <img> tag, use the Rails image_tag view helper, like this:
<%= image_tag "myphoto.jpg" %>

Well need a Visitor model to initialize the form.

Visitor Model
The Visitor model is almost identical to the Contact model we created earlier, except there is just one data attribute for the email field. Well also add a subscribe method to add a visitor to a MailChimp list. Well call this method from the controller when we process the submitted form. Create a file app/models/visitor.rb:
class Visitor < ActiveRecord::Base has_no_table column :email, :string validates_presence_of :email validates_format_of :email, :with => /\A[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}\z/ i

18

189

def subscribe mailchimp = Gibbon::API.new result = mailchimp.lists.subscribe({ :id => ENV['MAILCHIMP_LIST_ID'], :email => {:email => self.email}, :double_optin => false, :update_existing => true, :send_welcome => true }) Rails.logger.info("Subscribed #{self.email} to MailChimp") if result end end

Once again, we inherit behavior from the ActiveRecord parent class and use the has_no_table keyword from the activerecord-tableless gem to disable ActiveRecords database functionality. We create the email attribute and set validation requirements. Our subscribe method does the work of connecting to the MailChimp server to add the visitor to the mailing list. We instantiate the Gibbon object which provides all the connectivity. The Gibbon gem looks in the environment variables for the MAILCHIMP_API_KEY value so we dont need to specify it here. We assign the Gibbon object to the mailchimp variable (we could name it anything). Gibbon offers a
lists.subscribe

method which takes five parameters:

id environment variable to identify the MailChimp list email address of the visitor (inside a hash) double_optin setting
true

sends a double opt-in confirmation message

update_existing updates a subscriber record if it already exists send_welcome sends a Welcome Email to the new subscriber The parameters are described further in the MailChimp API Documentation. If the application successfully adds the new subscriber, we write a message to the logger. If we get an error when trying to add the subscriber, Gibbon will raise an exception.

18

190

Visitors Controller
We already have a Visitors controller that contains a simple new method. Well change the new method, add a create method, and provide a secure_params private method to secure the controller from mass assignment exploits. Replace the contents of the file app/controllers/visitors_controller.rb:
class VisitorsController < ApplicationController def new @visitor = Visitor.new end def create @visitor = Visitor.new(secure_params) if @visitor.valid? @visitor.subscribe flash[:notice] = "Signed up #{@visitor.email}." redirect_to root_path else render :new end end private def secure_params params.require(:visitor).permit(:email) end end

Our new method now assigns the Visitor model to an instance variable instead of the Owner model. The create method is almost identical to the Contacts controller create method. We instantiate the Visitor model with scrubbed parameters from the submitted form. If the validation check succeeds, we subscribe the visitor to the MailChimp mailing list with the @visitor.subscribe method. All the work of connecting to MailChimp happens in the Visitor model. If the validation check fails, we redisplay the home page (the
new

action).

19

191

Clean Up
We no longer use the Owner model, so we can delete the file app/models/owner.rb:
$ rm app/models/owner.rb

Theres no harm if it remains but it is good practice to remove code that is no longer used.

Routing
Our routing is now more complex. In addition to rendering the visitors#new view as the application root (the home page), we need to handle the create action. We can use a resourceful route as we did with the Contacts controller. Open the file config/routes.rb. Replace the contents with this:
LearnRails::Application.routes.draw do resources :contacts, only: [:new, :create] resources :visitors, only: [:new, :create] root to: 'visitors#new' end

The root path remains visitors#new . Order is significant in the config/routes.rb file. As the final designated route, the root path will only be active if nothing above it matches the route. Weve added
resources :visitors, only: [:new, :create]

.
only: [:new, :create]

We only want two routes so weve added the restriction The

new

route has these properties:

new_visitor_path visitors new

route helper

name of the controller (VisitorsController)

controller action

http://localhost:3000/visitors/new URL generated by the route helper The

GET

HTTP method to display a page route has these properties: route helper

create

visitors_path visitors

name of the controller (VisitorsController)

19

192

create

controller action

http://localhost:3000/visitors URL generated by the route helper

POST

HTTP method to submit form data

rake routes

You can run the

command to see these in the console:

$ rake routes Prefix Verb contacts POST new_contact GET visitors POST new_visitor GET root GET page GET

URI Pattern /contacts(.:format) /contacts/new(.:format) /visitors(.:format) /visitors/new(.:format) / /pages/*id

Controller#Action contacts#create contacts#new visitors#create visitors#new visitors#new high_voltage/pages#show

The output of the

rake routes

command shows weve created the routes we need.

Test the Application

If you need to start the server:
$ rails server

Open a web browser window and navigate to http://localhost:3000/. Youll see our new home page with the placeholder photo and the sign up form. Enter your email address and click the sign up button. You should see the page redisplay with an acknowledgment message. Try entering an invalid email address such as me@foo@, or click the submit button without entering an email address, and you should see an error message. Youll have to log in to MailChimp and check your mailing list to see if the new email address was added successfully. With MailChimp, you can send a welcome message automatically when the visitor signs up for the mailing list. Use the welcome message to inform the visitor that theyve successfully subscribed to the mailing list and will receive the next newsletter email. Its a bit difficult to find the MailChimp option to create a welcome message. Strangely, MailChimp considers a welcome message a form. Heres how to find it. On the MailChimp Lists page, click the down arrow for a menu and click Signup forms. Then click Link to a form. On the Create Forms page, there is a dropdown list of Forms & Response

19

193

Emails. The gray box shows Signup form. Click the down arrow. Select the menu item named Final Welcome Email and youll be able to create a welcome message.

Git
Lets commit our changes to the Git repository.
$ git add -A $ git commit -m "mailing list" $ git push

Our tutorial application is feature complete. Lets deploy it so we can see it running as a real website.

19

194

Chapter 25

Deploy
Youve been running the default Ruby WEBrick server on your local machine. If you wanted, you could leave your computer running, set up a managed DNS service, and your web application would be accessible to anyone. But even if you wanted to leave your computer running 24 hours a day, youre probably not a security expert, WEBrick isnt tuned to handle much traffic, and your computer is distant from the interconnection hubs where most websites are hosted. For these reasons, when we move a web application from development to production, we deploy it to a web hosting service that provides a hosting platform on a server located in a strategically-located data center. Data centers offer colocation services, renting rack-mounted computers with fast Internet connections that can be configured as web servers. In the early days of the web, deploying a web application required system administration skills to configure and maintain a web server. Today, some developers like to set up their web servers from bare metal using virtual private servers from Linode, Slicehost, Rackspace, Amazon EC2, or others. With sufficent skills and study, they say there is a feeling of satisfaction from doing it yourself. But not everyone wants to be a system administrator. Most Rails developers simply use a hosted platform as a service (PaaS) provider such as Heroku, EngineYard, OpenShift, Cloud Foundry, or Shelly Cloud. You may aleady be using a shared web hosting service such as GoDaddy or DreamHost for a static website or WordPress site. Be skeptical if a shared web hosting service claims to support Rails applications; most do so badly. Shared hosting services offer file space for static websites on servers that are shared by thousands of websites. A Rails application requires considerably greater computing resources and specialized expertise. A PaaS platform provides a hardware and software stack optimized for application performance and developer convenience. Heroku is the best known and most popular PaaS provider and well use it to deploy the tutorial application. Using Heroku or another PaaS provider means you dont need skills as a system administrator to manage your web server. Instead, youll have experts maintaining the production environment, tuning system performance, and keeping the servers running. Our Rails Heroku Tutorial goes into more detail.

Heroku Costs
It costs nothing to set up a Heroku account and deploy as many applications as you want. Youll pay only if you upgrade your hosting to accommodate a busy website.

19

195

Heroku pricing is based on a measure of computing resources the company calls a dyno. Think of a dyno as a virtual server (though it is not). Heroku provides one dyno for every web application for free. For personal projects, you can run your Rails application on a single dyno and never incur a charge. A single dyno idles after one hour of inactivity, going to sleep until it receives a new web request. For a personal project, this means your web application will respond with a few seconds delay if it hasnt received a web request in over an hour. After it wakes up, it will respond quickly to every browser request. If you want your web application to respond to every request without delay, you can run two dynos. Heroku charges $35 per month for a second dyno running full time (a dyno is billed at $0.05/hour). A single dyno can serve thousands of requests per second, but performance depends greatly on your application. With the Ruby WEBrick server, Rails processes only one request at a time. Heroku doesnt support WEBrick, but as a default it supports Thin, a similar singlethreaded, non-concurrent web server. Serving a typical Rails application that takes 100ms on average to process each request, Thin can accommodate about 10 requests per second per dyno, which is adequate for a personal project. If traffic surges on your website and exceeds 10 requests per second, you can scale up. First, you can replace the default Thin web server with the Unicorn web server which handles concurrent requests. Configuring Unicorn requires more expertise than Thin, but Heroku recommends it. Second, you can double the size of Herokus dynos to handle more requests. Finally, you can buy more dynos, adding as many dynos as you need to handle traffic. This is where convenience comes at a price. You wont need system administration expertise to deploy a website on Heroku but youll pay a premium to host a high-traffic site. Heroku is ideal for hosting our application: no system administration expertise is required hosting is free performance is excellent For this tutorial application, we wont concern ourselves with the possibility that the website may get a lot of traffic. Im sure youll join me in offering hearty thanks to Heroku for providing a convenient service that beginners can use for free. Lets deploy!

Test the Application

Before deploying an application to production, a professional Rails developer runs integration or acceptance tests. If the developer follows the discipline of test-driven development,

19

196

he or she will have a complete test suite that confirms the application runs as expected. Often the developer uses a continuous integration server which automatically runs the test suite each time the code is checked into the GitHub repository. We havent used test-driven development to build this application so no test suite is available. Youve tested the application manually at each stage.

Preparing for Heroku

Youll need to prepare your Rails application for deployment to Heroku.

Gemfile
We need to modify the Gemfile for Heroku. We add a
group :production

block for gems that Heroku needs:

pg PostgreSQL gem thin web server rails_12factor logging and static assets Heroku doesnt support the SQLite database; the company provides a PostgreSQL database. Though we wont need it for our tutorial application, we must include the PostgreSQL gem for Heroku. Well mark the sqlite3 gem to be used in development only. The Thin web server is easy to use and requires no configuration. Note that Heroku recommends Unicorn for handling higher levels of traffic efficiently. Unicorn can be difficult to setup and configure, so were using Thin for our tutorial application. On Heroku, Rails 4.0 needs an extra gem to handle logging and serve CSS and JavaScript assets. The rails_12factor gem provides these services. Open your Gemfile and replace the contents with the following: Gemfile
source 'https://rubygems.org' ruby '2.0.0' gem 'rails', '4.0.0' gem 'sass-rails', '~> 4.0.0' gem 'uglifier', '>= 1.3.0' gem 'coffee-rails', '~> 4.0.0' gem 'jquery-rails' gem 'turbolinks'

19

197 gem 'jbuilder', '~> 1.2' gem 'activerecord-tableless' gem 'bootstrap-sass', '~> 2.3.2.2' gem 'figaro' gem 'gibbon' gem 'google_drive' gem 'high_voltage' gem 'simple_form', '>= 3.0.0.rc' group :development do gem 'better_errors' gem 'quiet_assets' gem 'sqlite3' end group :production do gem 'pg' gem 'rails_12factor' gem 'thin' end

We have to run bundle install because weve changed the Gemfile. The gems weve added are only needed in production so we dont install them on our local machine. When we deploy, Heroku will read the Gemfile and install the gems in the production environment. Well run bundle install with the --without production argument so we dont install the new gems locally:
$ bundle install --without production

Commit your changes to the Git repository:

$ git add -A $ git commit -m "gems for Heroku" $ git push

Precompile Assets
In development mode, the Rails asset pipeline live compiles all CSS and JavaScript files and makes them available for use. Compiling assets adds processing overhead. In production, a web application would be slowed unneccesarily if assets were compiled for every web request. Consequently, we must precompile assets before we deploy our application to production. When you precompile assets for production, the Rails asset pipeline will automatically produce concatenated and minified application.js and application.css files from files listed in the manifest files app/assets/javascripts/application.js and app/assets/stylesheets/

19

198

application.css.scss. You must commit the compiled files to your git repository before deploying. Heres how to precompile assets and commit to the Git repo:
$ $ $ $ RAILS_ENV=production rake assets:precompile
git add -A git commit -m "assets compiled for Heroku" git push

The result will be several files added to the public/assets/ folder. The filenames will contain a long unique identifier that prevents caching when you change the application CSS or JavaScript. If you dont precompile assets for production, all web pages will look strange. They wont have CSS styling.

Option to Ban Spiders

Do you want your website to show up in Google search results? If theres a link anywhere on the web to your site, within a few days (sometimes hours) the Googlebot spider will visit your site and add it to the database for the Google search engine. Most webmasters want their sites to be found in Google search results. If thats not what you want, you may want to modify the file public/robots.txt to prevent indexing by search engines. Only change this file if you want to prevent your website from appearing in search engine listings:
# public/robots.txt # To allow spiders to visit the entire site comment out the next two lines: User-Agent: * Disallow: /

To block all search engine spiders, remove the commenting from the lines.

User-Agent

and

Disallow

You can learn more about the format of the robots exclusion standard.

Humans.txt
Many websites include a robots.txt file for nosy bots so its only fair that you offer a humans.txt file for nosy people. Few people will look for it but you can add a file public/ humans.txt to credit and identify the creators and software behind the website. The HTML5 Boilerplate project offers an example file or you can borrow from RailsApps.

19

199

Sign Up for a Heroku Account

In the chapter, Accounts You May Need, I suggested you sign up for a Heroku account. To deploy an app to Heroku, you must have a Heroku account. Visit https://id.heroku.com/signup/devcenter to set up an account. Youll use a
git push

command to deploy your application to Heroku.

Be sure to use the same email address you used to configure Git locally. You can check the email address you used for Git with:
$ git config --get user.email

Heroku Toolbelt
Heroku provides a command line utility for creating and managing Heroku apps. Visit https://toolbelt.heroku.com/ to install the Heroku Toolbelt. A one-click installer is available for Mac OS X, Windows, and Linux. The installation process will install the Heroku command line utility. It also installs the Foreman gem which is useful for duplicating the Heroku production environment on a local machine. The installation process will also make sure Git is installed. To make sure the Heroku command line utility is installed, try:
$ heroku version heroku-toolbelt/...

Youll see the heroku-toolbelt version number. You should be able to login using the email address and password you used when creating your Heroku account:
$ heroku login Enter your Heroku credentials. Email: [email protected] Password: Could not find an existing public key. Would you like to generate one? [Yn] Generating new SSH public key. Uploading ssh public key /Users/adam/.ssh/id_rsa.pub

19

200

The Heroku command line utility will create SSH keys if necessary to guarantee a secure connection to Heroku.

Heroku Create
Be sure you are in your application root directory and youve committed the tutorial application to your Git repository. Use the Heroku create command to create and name your application.
$ heroku create myapp

Replace myapp with something unique. Heroku demands a unique name for every hosted application. If it is not unique, youll see an error, name is already taken. Chances are, learn-rails is already taken. If you dont specify your app name ( myapp in the example above), Heroku will supply a placeholder name. You can easily change Herokus placeholder name to a name of your choice with the heroku apps:rename command (see Renaming Apps from the CLI). Dont worry too much about getting the perfect name for your Heroku app. The name of your Heroku app wont matter if you plan to set up your Heroku app to use your own domain name. Youll just use the name for access to the instance of your app running on the Heroku servers; if you have a custom domain name, youll set up DNS (domain name service) to point your domain name to the app running on Heroku. The heroku create command sets your Heroku application as a Git remote repository. That means youll use the git push command to deploy your application to Heroku.

Set a Domain Name

Earlier, when we created the config/application.yml file and set environment variables, we left a placeholder for a domain name in the file. Now we can replace the placeholder. Open the file config/application.yml:
# Add account credentials and API keys here. # See http://railsapps.github.io/rails-environment-variables.html # This file should be listed in .gitignore to keep your settings secret! # Each entry sets a local environment variable and overrides ENV variables in the Unix shell. GMAIL_USERNAME: Your_Username GMAIL_PASSWORD: Your_Password

20

201 MAILCHIMP_API_KEY: Your_MailChimp_API_Key MAILCHIMP_LIST_ID: Your_List_ID DOMAIN_NAME: example.com OWNER_EMAIL: [email protected]

If you dont have a custom domain name, use the domain name youve chosen for deployment on Heroku. Replace example.com with myapp.herokuapp.com , replacing myapp with the name that Heroku has accepted for your application. If you already have a custom domain name in the file, you dont have to change anything, but you will have to set up Heroku to use your custom domain name. That involves setting up DNS, which we wont cover in this tutorial.

Enable Email
Youll need to enable email for production or else youll get errors when your application tries to send email from Heroku. To use Gmail from Heroku, add the following to your config/environments/production.rb file:
config.action_mailer.default_url_options = { :host => ENV["DOMAIN_NAME"] } config.action_mailer.delivery_method = :smtp config.action_mailer.perform_deliveries = true config.action_mailer.raise_delivery_errors = false config.action_mailer.default :charset => "utf-8" config.action_mailer.smtp_settings = { address: "smtp.gmail.com", port: 587, domain: ENV["DOMAIN_NAME"], authentication: "plain", enable_starttls_auto: true, user_name: ENV["GMAIL_USERNAME"], password: ENV["GMAIL_PASSWORD"] }

Youll need to specify the unique name youve selected for your hosted application. Were using an environment variable ENV["DOMAIN_NAME"] in two places in the file. Be sure you set the environment variable for the domain name in the file config/application.yml in the previous step. Be sure to add the new settings before the end keyword in the file. The settings can be added anywhere, as long as they precede the end keyword! Next well set Heroku environment variables.

20

202

Set Heroku Environment Variables

Youll need to set the configuration values from the config/application.yml file as Heroku environment variables. With the figaro gem, just run:
$ rake figaro:heroku

Alternatively, you can set Heroku environment variables directly. Heres how to set environment variables directly on Heroku with
heroku config:add

$ heroku config:add GMAIL_USERNAME='[email protected]' GMAIL_PASSWORD='secret' $ heroku config:add MAILCHIMP_API_KEY='mykey' MAILCHIMP_LIST_ID='mylistid' $ heroku config:add OWNER_EMAIL='[email protected]' DOMAIN_NAME='myapp.herokuapp.com'

You can check that the environment variables are set with:
$ heroku config

See the Heroku documentation on Configuration and Config Vars and the article Rails Environment Variables for more information.

Push to Heroku
After all this preparation, you can finally push your application to Heroku. Be sure youve run RAILS_ENV=production your CSS or JavaScript files.
rake assets:precompile

. Run it each time you change

Be sure to commit your code to the Git local repository before you push to Heroku:
$ git add -A $ git commit -m "assets compiled for Heroku" $ git push

You commit your code to Heroku just like you push your code to GitHub. Heres how to push to Heroku:

20

203 $ git push heroku master

The push to Heroku takes several minutes. Youll see a sequence of diagnostic messages in the console, beginning with:
-----> Ruby/Rails app detected

and finishing with:

-----> Launching... done

Visit Your Site

Open your Heroku site in your default web browser:
$ heroku open

Your application will be running at http://my-app-name.herokuapp.com/. If youve configured everything correctly, you should be able to sign up for the newsletter and send a contact request.

Customizing
For a real application, youll likely want to use your own domain name for your app. See Herokus article about custom domains for instructions. You may also want to improve website responsiveness by adding page caching with a content delivery network such as CloudFlare. CloudFlare can also provide an SSL connection for secure connections between the browser and server. Heroku offers many add-on services. These are particularly noteworthy: Adept Scale automated scaling of Heroku dynos New Relic performance monitoring For an in-depth look at your options, see the Rails Heroku Tutorial.

20

204

Troubleshooting
When you get errors, troubleshoot by reviewing the log files:
$ heroku logs

If necessary, use the Unix and enter:

$ heroku logs -t

tail

flag to monitor your log files. Open a new terminal window

to watch the server logs in real time.

Where to Get Help

Your best source for help with Heroku is Stack Overflow. Your issue may have been encountered and addressed by others. You can also check the Heroku Dev Center or the Heroku Google Group.

20

205

Chapter 26

Analytics
In earlier chapters, weve built the tutorial application and deployed it for hosting on Heroku. Weve left something out. Though not obvious, its very important. Analytics services provide reports about website traffic and usage. Youll use the data to increase visits and improve your site. Analytics close the communication loop with your users; your website puts out a message and analytics reports show how visitors respond. Google Analytics is the best known tracking service. It is free, easy to use, and familiar to most web developers. In this chapter well integrate Google Analytics with the tutorial application. There are several ways to install Google Analytics for Rails 4.0. The article on Analytics for Rails looks at various approaches and explains how Google Analytics works. For this tutorial, well use the Segment.io service. The service provides an API to send analytics data to dozens of different services, including Google Analytics.

Segment.io
Segment.io is a subscription service that gathers analytics data from your application and sends it to dozens of different services, including Google Analytics. The service is free for low- and medium- volume websites, providing one million API calls (page views or events) per month at no cost. There is no charge to sign up for the service. Using Segment.io means you install one JavaScript library and get access to reports from dozens of analytics services. You can see a list of supported services. The company offers helpful advice about which analytics tools to choose from. For low-volume sites, many of the analytics services are free, so Segment.io makes it easy to experiment and learn about the available analytics tools. The service is fast and reliable, so theres no downside to trying it.

Accounts You Will Need

You will need an account with Segment.io. Sign up for Segment.io.

20

206

You will need accounts with each of the services that youll use via Segment.io. Youll likely want to start with Google Analytics, so youll need a Google Analytics account and tracking ID. Visit the Google Analytics website to obtain the Tracking ID for your website. Youll need to know the domain name of your website to get an account for your website. If youve deployed to Heroku without a custom domain, use the domain that looks like myapp.herokuapp.com. Or use your custom domain if you have one. Use it for fields for Website Name, Web Site URL, and Account Name. Choose the defaults when you create your Google Analytics account and click Get Tracking ID. Your tracking ID will look like this: UA-XXXXXXX-XX . You wont need the tracking code snippet as we will use the Segment.io JavaScript snippet instead. Youll check your Google Analytics account later to verify that Google is collecting data.

Installing the JavaScript Library

Segment.io provides a JavaScript snippet that sets an API token to identify your account and installs a library named analytics.js. This is similar to how Google Analytics works. The Segment.io library loads asynchronously, so it wont affect page load speed. The Segment.io JavaScript snippet should be loaded on every page and it can be included as an application-wide asset using the Rails asset pipeline. Well add the Segment.io JavaScript snippet to a file named app/assets/javascripts/ segmentio.js. The manifest directive //= require_tree . in the file app/assets/javascripts/ application.js will ensure that the new file is included in the concatenated application JavaScript file. If youve removed the //= require_tree . directive, youll have to add a directive to include the app/assets/javascripts/segmentio.js file. Create a file app/assets/javascripts/segmentio.js and include the following:
var analytics=analytics||[];(function(){var e=["identify","track","trackLink","trackForm","trackClick","trackSubmit","page", "pageview","ab","alias","ready","group"],t=function(e){return function(){analytics.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var n=0;n<e.length;n++)analytics[e[n]]=t(e[n])})(),analytics.load=function(e){var t=document.createElement("script");t.type="text/javascript",t.async=!0, t.src=("https:"===document.location.protocol?"https://":"http://")+ "d2dq2ahtl5zl1z.cloudfront.net/analytics.js/v1/"+e+"/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n)}; analytics.load("YOUR_API_TOKEN"); $(document).on('page:load', function() { console.log('page loaded');

20

207 analytics.pageview(); analytics.trackForm($('#new_visitor'), 'Signed Up'); analytics.trackForm($('#new_contact'), 'Contact Request'); })

If you find you cant copy this code from this page, you can get it directly from the reference implementation of the tutorial application. The app/assets/javascripts/segmentio.js file is on GitHub. The Segment.io website offers a minified version of the snippet for faster page loads. Weve used it here for convenience. You can look at the non-minified version on the Segment.io website if you want to read the code and comments. You must replace YOUR_API_TOKEN with your Segment.io API token. You can find the API token on your Settings page when you log in to Segment.io (it is labelled Your API Key). Weve added extra code to the minified Segment.io JavaScript snippet. The extra code accomodates page view and event tracking, which well look at next.

Page View Tracking with Turbolinks

Rails 4.0 introduced a feature named Turbolinks to increase the perceived speed of a website. Turbolinks makes an application appear faster by only updating the body and the title of a page when a link is followed. By not reloading the full page, Turbolinks reduces browser rendering time and trips to the server. With Turbolinks, the user follows a link and sees a new page but Segment.io or Google Analytics thinks the page hasnt changed because a new page has not been loaded. You can disable Turbolinks by removing the turbolinks gem from the Gemfile. However, its nice to have both the speed of Turbolinks and tracking data. To make sure every page is tracked when Rails 4.0 Turbolinks is used, weve already appended the following JavaScript to the app/assets/javascripts/segmentio.js file:
$(document).on('page:load', function() { analytics.pageview(); });

This code follows the

analytics.load('YOUR_API_TOKEN');

statement at the end of the file.

Turbolinks fires a page:change event when a page has been replaced. The code listens for the page:load event and calls the Segment.io pageview() method.

20

208

Event Tracking
Segment.io gives us a convenient method to track page views. Page view tracking gives us data about our website traffic, showing visits to the site and information about our visitors. Its also important to learn about a visitors activity on the site. Site usage data helps us improve the site and determine whether we are meeting our business goals. This requires tracking events as well as page views. The Segment.io JavaScript library gives us two methods to track events:
trackLink trackForm

Link tracking can be used to send data to Segment.io whenever a visitor clicks a link. It is not useful for our tutorial application because we simply record a new page view when a visitor clicks a link on our site. However, if you add links to external sites and want to track clickthroughs, you could use the trackLink method. The method can also be used to track clicks that dont result in a new page view, such as changing elements on a page. The trackForm method is more useful for our tutorial application. Weve already appended it to the app/assets/javascripts/segmentio.js file:
$(document).on('page:load', function() { analytics.trackForm($('#new_visitor'), 'Signed Up'); analytics.trackForm($('#new_contact'), 'Contact Request'); })

The trackForm method takes two parameters, the ID attribute of a form and a name given to the event. Form tracking will show us how many visitors sign up for the newsletter or submit the contact request form. Obviously we can count the number of subscribers in MailChimp or look in the site owners inbox to see how many contact requests weve received. But form tracking helps us directly correlate the data with visitor data. For example, we can analyze our site usage data and see which traffic sources result in the most newsletter sign-ups. With Google Analytics enabled as a Segment.io integration, youll see form submissions appear in the Google Analytics Real-Time report, under the Events heading. You can read more about the Segment.io JavaScript library in the Segment.io documentation.

20

209

Segment.io Integrations
After installing the Segment.io JavaScript snippet in your application, visit the Segment.io integrations page to select the services that will receive your data. When you log in to Segment.io you will see a link to Integrations in the navigation bar. Each service requires a different configuration information. At a minimum, youll have to provide an account identifier or API key that you obtained when you signed up for the service. For Google Analytics, enter your Google Analytics tracking id. It looks like UA-XXXXXXX-XX . Check the box to Enable Client-Side Universal Analytics. Accept the other defaults. Click Dashboard in the navigation bar so you can monitor data sent to Segment.io from your application.

Deploy
When you are ready to deploy to Heroku, you must recompile assets and commit to the Git repo:
$ $ $ $ $ $
git add -A git commit -m "analytics"

RAILS_ENV=production rake assets:precompile

git add -A git commit -m "assets compiled for Heroku" git push

Then you can deploy to Heroku:

$ git push heroku master

When you visit the site, you should see real-time tracking of data sent to Segment.io in the Segment.io dashboard. Log into your Google Analytics account to see real-time tracking of visits to your website. Under Standard Reports see Real-Time Overview. Youll see data within seconds after visiting any page.

20

210

Improving the User Experience

Website analytics can be used to improve visitors experience of the website. Deploying the website is not the last step in your project. Unlike many earlier forms of communication (such as releasing a film, publishing a book, or broadcasting an advertisement), we can see how every visitor responds to the website. That means your work is not done when you deploy the site. Look at your usage data to see which elements of the site are getting attention and which are being used. Does no one visit the About page? Maybe the navigation link is difficult to find. Do many people visit the Contact page but few submit a contact request form? Maybe you should change the label on the button or offer other ways to contact the site owner. Effective and successful websites often are the result of systematic A/B testing (sometimes called split testing). A/B testing is a technique of creating variations on a web page, such as changing text, layout, or button colors, and using website analytics to measure the effect of the change. You can learn more about services such as Content Analytics in Google Analytics, Optimizely, or Visual Website Optimizer. These services provide complete dashboards to set up usage experiments and measure results (Optimizely is available as a Segment.io integration).

Conversion Tracking
You may only be interested in knowing that people visit your site, without measuring visitors engagement or response to the site. But in most cases, if you build a website, youll offer a way for visitors to respond, whether it is by purchasing a product, signing up for a newsletter, or clicking a like button. The ultimate measure of website effectiveness is the conversion rate. The term comes from the direct marketing industry and originally referred to a measure of how people responded to junk mail offers. For a website, the conversion rate indicates the proportion of visitors who respond to a call to action, which may be an offer to make a purchase, register for a membership, sign up for a newsletter, or any other activity which shows the visitor is engaged and interested. For our tutorial application, we can measure our website effectiveness by looking at the conversion rate for newsletter sign-ups. Were tracking page views which will give us a count of visits to the website home page. And weve got event tracking in place to count newsletter sign-ups. If 100 people visit the home page and 10 people request a newsletter, weve got a conversion rate of 10%. We can try to improve the conversion rate by improving the user experience (perhaps through A/B testing) or focusing on increasing traffic from sources that provide a higher conversion rate.

21

211

You can monitor your sites conversion rate by setting up events as goals in Google Analytics. Segment.io also integrates with many services which provide conversion tracking.

21

212

Chapter 27

Rails Challenges
Rails is popular. Rails is powerful. But Rails isnt easy to learn. You may have heard of a psychological phenomenon called resistance. When we struggle with something new, or must adapt to the unfamiliar, we resist. We get discouraged. We complain. Sometimes we feel we should quit. This chapter is here to help with your resistance. Its purpose is to acknowledge that, yes, Rails can be difficult. Tens of thousands of people are successfully using Rails. Ill hazard a guess that none are significantly smarter, more motivated, or a better student than you. Perhaps some of them had more time to study or better access to mentors, but these factors simply accelerate the speed of learning Rails. If you get discouraged, or think Rails is too hard, recognize that you are encountering your own resistance, not any genuine limitation. Take a break, set aside your learning materials, and come back when your natural curiosity and eagerness has returned. Sometimes resistance attaches to imaginary problems (like Im not smart enough). Just as often, resistance attaches to real problems, but magnifies them into insurmountable obstacles (Rails is impossible to use on Windows!). The best way to overcome these obstacles is to acknowledge the resistance, investigate the obstacle, and seek support from peers. This chapter describes some of things that make Rails difficult. These Rails challenges are obstacles, but other people overcame them. You can, too. The list is incomplete. If youve encountered a Rails challenge that isnt listed here, email me at [email protected] and I will add your suggestion to the next revision of the book.

It is difficult to install Ruby.

The installation process for Ruby on Rails is more difficult than downloading and installing any consumer software applications. You are setting up a development environment and you need system software as well as Ruby. Depending on what youve done before, you may have altered your system, introducing potentials for conflicts. This book provides links to good installation guides in the Get Started chapter. But installation instructions cant accommodate the specific configuration of your computer. Sometimes you just have to look for someone to help. Ive also suggested using Nitrous.io, a hosted development environment.

21

213

Rails is a nightmare on Windows.

Windows is very popular, so why is it difficult to develop with Rails on Windows? It seems the Rails community has a bias against Windows. It does, and theres a reason. Rails is an open source project. Most open source developers use Unix-based system tools. It is difficult and time-consuming to convert Unix-based system tools to the Microsoft Windows operating system. Open source developers prefer to spend their time maintaining and improving their Unix-based projects. And expert Windows developers are seldom interested in porting Unix-based system tools to Windows. So system utilities such as RVM are not available for Windows. And developers who create gems are seldom interested in spending time to solve the problems that arise when code has to be adapted for the idiosyncrasies of the Windows platform. This situation is not going to change, so you have to make a choice. Stay with Windows or get comfortable with Unix-based systems.

Why do I have to learn Git? It is difficult.

Real software development requires version control and Git is the standard tool for Rails developers. If all you do is build applications as a classroom exercise, you dont need to learn Git. You can skip all the parts of the book that mention Git. But sooner or later, if you start doing real projects, youll need Git. Simple Git commands are not difficult to learn. When youve developed your skills and confidence you can learn the more advanced Git functions, such as branching.

RVM seems unnecessary. Why worry about versions?

For simple projects you dont need RVM. This book introduces RVM and prepares you to handle version conflicts. As you tackle more complex projects, and as new versions of Rails are released, youll face version issues and RVM will be helpful.

Do I really need to learn about testing?

For student projects, no, you dont need to learn about testing. But as soon as money or reputation is at stake on a project, youll need to begin using test-driven development. This book doesnt teach TDD because it is overwhelming for a beginner. After you complete the book, intermediate-level tutorials will introduce you to testing. Once youve grasped the basics of Rails, testing will become easy, and it actually is fun and satisfying.

Rails error reporting is cryptic.

Actually, Rails error reporting is quite good. Stack traces are detailed and error messages are descriptive. Beginners have a problem because the stack traces and error messages provide a technical analysis of a problem in terms that an experienced developer can understand. If error reporting was simplified it might not be as intimidating but it would not as accurate. Its up to you to gain enough knowledge to understand the error messages. Finally, the error

21

214

reporting mechanism can point you to the line in your code that triggers a problem, but it cant know what you trying to do, or describe the error in anything but technical terms.

There is too much magic.

The Rails convention over configuration principle leads to obscurity. Default behavior often looks like magic because the underlying implementation is hidden in the depths of the Rails code library. If you like to know how things work, this can be frustrating. You really have only two choices when you encounter Rails magic. You can take time to dig into the source code. If you do so, youll encounter frustration as you encounter complex and sophisticated code, but you may also improve your understanding and skill as a Ruby programmer. Or you can take on faith that it just works. Often, you just need to use the convention several times in different projects to get comfortable with the magic and stop worrying that you dont fully understand it.

Rails contains lots of things I dont understand.

If you look at the Rails directory structure, youll see many files and folders. If you look at the Rails API, or pick up a Ruby tutorial, youll also see code that is unfamiliar. This book has described some of what you see. As you build more applications, you will gain proficiency and master more of Rails and Ruby. Yet even as you gain mastery of Rails, there will be aspects that remain unfamiliar. Dont let the sheer complexity stop you. The truth is, you dont have to know all of Rails or Ruby to build web applications.

There is too much to learn.

Very true. To be a full-stack web developer you need to know HTML, JavaScript, CSS, Ruby, testing, databases, and much, much more. You might think that developers who started ten years ago have an advantage because there wasnt as much to learn when they started. But today there are many more high-quality tutorials and educational programs to accelerate your learning. And resources like Google and Stack Overflow have many more answers to questions. As the knowledge domain has grown, so have the learning resources. You dont have to learn everything. Get a foundation in the basics and then dive deep as a specialist in an area that appeals to you.

It is difficult to find up-to-date advice.

Rails has been around since 2004 with major new versions released every two years. Chances are, answers to questions you find on Stack Overflow or Google were written for an older version of Rails. There is no easy way to determine if the answer is out of date. A particular aspect of Rails may have changedor not. Even worse, the answer may work, but there may be a better way that reflects current best practices. To filter the outdated in Google, use the Search Tools options for specifying a timeframe. Look closely at the date of a blog posting or Stack Overflow answer. Try to find a newer answer. Usually, if there are a series of

21

215

answers and things have changed, youll see the current best answer. If youre uncertain, dont be shy about posting your question to Stack Overflow. More importantly, make it your business to keep up with the community, reading Peter Coopers Ruby Weekly email newsletter or his daily RubyFlow site.

It is difficult to know what gems to use.

There are so many gems available for Rails. Some add useful features, like tagging or a mailing list API. Some are basic, such as gems for a database or front-end framework. Even among basic gems, Rails offers choices. Which are best? The Ruby Toolbox can help, but mostly you will find guidance from looking at example projects and noticing what other developers are using. Theres wisdom in the crowd.

Rails changes too often.

If you look at the Ruby on Rails Release History youll see there is a new major release approximately every 1.5 years. Each major release is well tested and relatively free of bugs. But new features or new approaches often require rewrites of older applications. Commercial software products often make a priority of keeping the API consistent over time. Thats not Rails. Rails is an open source project and the core team embraces innovation. The maintainers expect that youll keep up with changes.

It is difficult to transition from tutorials to building real applications.

Copying and pasting from tutorials is a good way to begin learning Rails. But youll only become a skilled Rails developer when you build something that is not shown in a tutorial. The first few hours (or days) when you start building a custom application can be very difficult. Focus on the basics that are described in this book. Start with user stories. Build pieces that you know how to do. Look for code samples on blogs or GitHub or Stack Overflow. Try spikes, little experiments that test ideas for implementation. Seek advice from peers or mentors. At first it will be slow going. But you will pick up momentum.

Im not sure where the code goes.

If you follow tutorials, youll learn where the code goes with the modelviewcontroller design pattern. With a sense of the request-response cycle, RESTful actions in the controller, and a few guidelines such as skinny controller, fat model youll be able to build intermediate-level Rails applications. Front-end code, particularly JavaScript, can be difficult because not a lot has been published about Rails best practices. In particular, the Rails asset pipeline can be confusing for anyone who has done front-end development without Rails. If you dont know what youre supposed to do, do whatever works, then look for someone who can help you by providing a code review.

21

216

People like me dont go into programming.

Most Rails developers are white or Asian young men with an engineering background. For people who dont fit the stereotypical profile, it can be hard to find role models or peers who demonstrate that Rails is something everyone can learn. The challenge can be subtle, as when you have the feeling that maybe if you were different youd find it easier to make progress. Or the challenge can be overt, when behavior of fellow students or co-workers is disturbing or hurtful (often they dont even know!). Lack of diversity, and the cluelessness that accompanies it, is common in the Rails community. But many people are working to make the community more welcoming and inclusive. Organizations such as Rails Girls and Railsbridge are creating more diversity in the community. You may find support from peers there to affirm that you, too, are entitled to knowledge and success.

21

217

Chapter 28

Comments
Credits
Daniel Kehoe wrote the book and implemented the application.

Contributors
Dozens of volunteers offered corrections and made suggestions, from fixing typos to advice about organizing the chapters. Id like to acknowledge each contributor; my apologies if I overlooked anyone. Alberto Dubois Rib, Alex Finnarn, Alexandru Muntean, Alexey Dotokin, Alexey Ershov, Brandon Schabel, Dapo Babatunde, Dave Mox, David Kim, Duany Dreyton Bezerra Sousa, Erik Trautman, Erin Nedza, Flavio Bordoni, Fritz Rodriguez Jr, Hendri Firmana, Ishan Shah, James Hamilton, Joanne Daudier, Joel Dezenzio, Jonathan Lai, Jonathan Miller, Jordan Stone, Josh Morrow, Julia Mokus, Julie Hamwood, Jutta Frieden, Laura Pierson Wadden, Marc Ignacio, Mark Blackwell, Michael Wong, Miran Omanovic, Neha Jain, Norman Cohen, Oana Sipos, Peter Rangelov, Richard Afolabi, Robin Paul, Roderick Silva, Sakib Ash, Silvia Obajdin, Stas Sucov, Stefan Streichsbier, Sven Fuchs, Tam Eastley, Timothy Jones, Tom Connolly, Tomas Olivares, Verena Brodbeck, William Yorgan, Zachary Davy

Photos
Images provided by the lorempixel.com service are used under the Creative Commons license (CC BY-SA). Visit the Flickr accounts of the photographers to learn more about their work: photo of a white cat by Tomi Tapio photo of a cat by Steve Garner photo of a cat by Ian Barbour The photo of a white cat by Tomi Tapio appears in the screenshot in the Introduction chapter and on the tutorial cover page.

21

218

Did You Like the Tutorial?

Was the book useful to you? Follow @rails_apps on Twitter and tweet some praise. Id love to know you were helped out by the tutorial. Any issues with the tutorial application? Please create an issue on GitHub. Reporting (and patching!) issues helps everyone.

21

219

Learn Ruby on Rails Copyright (C) 2013 Daniel Kehoe. All rights reserved.