1.1 Version Check

If you have the PDF, ePub, or Mobi versions of the book, check the title page for the version number and look on the webpage for the learn-rails GitHub repository to make sure you have the newest version of the book.

I suggest to use the online edition as you build the tutorial application. It is always up to date.

1.2 Get the Videos

You can watch videos as you read the book. A subscription is only $19 per month (there’s also a discount when you get the video series plus advanced tutorials). It’s easy and you’ll learn more:

• Get the Videos and Advanced Tutorials

The videos are a great introduction to Rails. With the videos and the advanced tutorials, I promise there is no better way to learn Rails.

2.1 Is It for You?

You don’t need to be a programmer to succeed with this book. You’ll be surprised how quickly you become familiar with the Unix command line interface and the Ruby programming language even if you’ve never tried programming before.

Book One provides a primer for the Unix command line, the terminal, and a text editor. If you have no experience with Unix commands, the terminal window, or a text editor, read Book One first. Everything else you need is self-contained in this book.

With this book, my aim is to introduce you to Rails and the techniques of web application development so you can launch a startup or begin a new career.

2.2 What To Expect

There is deep satisfaction in building an application and making it run. With this book, I’ll give you everything you need to build a real-world Rails application. More importantly, I’ll explain everything you build, so you understand how it works. There will be no mystery code.

When you’ve completed this tutorial, you will be ready for more advanced self-study, including the Capstone Rails Tutorials, textbook introductions to Rails such as Michael Hartl’s Ruby on Rails Tutorial, or workshops and code camps that provide intensive training in Ruby on Rails.

3.1 Example Code

If you follow this tutorial closely, you’ll have a working application that closely matches the example app in the learn-rails GitHub repository. If your application doesn’t work after following the tutorial, compare the code to the example app in the GitHub repository, which is known to work.

3.2 Version Check

The code in this tutorial was tested by many people and worked flawlessly at the time this was written. The learn-rails example application on GitHub serves as a “reference implementation” if you have problems. The example application is updated more frequently than the published tutorial.

You’ll find the version number and release date on the first page of this book (under the book title). Check the learn-rails GitHub repository to find out if you have the newest version of the book. The README page on the GitHub repo always shows the most recent version number for the book and the tutorial application.

Don’t worry if the learn-rails GitHub repository seems complicated or difficult to understand. You’ll get to know GitHub over time and it will become familiar. For now, it is only important to know that it is there in case you have problems.

Take a moment now to look at the open issues on GitHub to see what problems you may encounter as you work your way through the tutorial. You can look at the closed issues to see some of the solved problems.

If you have trouble building the application in this book, and suspect something may be out of date, you can compare the Gemfile in the repo to see if we’ve changed gems or specified version numbers to avoid compatibility issues.

You can also check the CHANGELOG and look at recent commits to see the current state of the application.

3.3 Getting Help With the Book

Let’s consider what to do if you encounter problems as you build the tutorial application in this book.

If you are in a classroom, or studying in a group, ask a peer to look at your problem. Most problems are caused by simple typos or formatting errors. Your classmate may see what you overlooked.

Stack Overflow provides a question-and-answer forum for readers of this book. As the author of this book, I can’t solve your individual problems or help you directly by email. If I did, I would not have time to create the tutorials and videos that benefit so many people. However, I watch for questions on Stack Overflow. Everyone benefits when solutions are made public.

• tag your questions on Stack Overflow with railsapps for extra attention

If your questions aren’t answered on Stack Overflow, try the Reddit forum:

• /r/rails

I sincerely hope you won’t encounter obstacles as you build the tutorial application. Thousands of beginners have successfully completed the book and, unless a gem has recently changed, you should have no problem.

Now let’s consider where to look for help when you are working on your own Rails projects.

3.4 Getting Help With Rails

3.5 References

Here are suggestions for the most important references.

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, it’s important to know additional help is available when you need it.

3.6 Meetups, Hack Nights, and Workshops

I’d 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.

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 don’t 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.

3.7 Pair Programming

Learning to code is challenging, especially if you do it alone. Make it social and you’ll learn faster and have more fun.

There’s a popular trend in the workplace for programmers to work side-by-side on the same code, sharing a keyboard and screen. It’s 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. It’s 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 codermatch.me or letspair.net.

Remote pair programming requires tools for screen sharing and video chat. Pairing sessions often use:

• Google+ Hangouts
• Screenhero
• Floobits
• Cloud9 IDE

More tools are emerging as remote pair programming becomes popular.

3.8 Pairing With a Mentor

By far, the best way to learn is to have a mentor at your side as you undertake a project. That is an opportunity that is seldom available, unless you’ve been hired to be part of a team in a company that encourages pair programming.

You can try RailsMentors, a network of volunteer mentors offering free help.

If you can pay for help, find a mentor using HackHands or AirPair. Market rates are expensive for a student, obviously, but if you are learning on the job or building an application for your own business, connecting online with a mentor might be a godsend.

AirPair connects developers for real-time help using video chat and screen sharing. Experts set their own rate and the site matches you according to your budget. Expect to pay market rates for consulting ranging from USD $40 per hour to $150 per hour or more.

HackHands promises to instantly connect you with a qualified expert at a cost of one dollar per minute for mentorship using video chat and screen sharing.

3.9 Code Review

Code review is an essential part of the development process. There’s always more than one way to implement a feature, and some ways are better than others, but you may not know it unless you ask someone to look at your code. When you pair with a mentor, you get the benefit of code review. But even if you don’t have a mentor, you can get code review online. StackExchange, the parent of StackOverflow, has a free site for code review, and a new service promises code review as a service:

• codereview.stackexchange.com

Expert code review will accelerate your learning faster than anything else.

Knowing where to go for help is important; it is just as important to stay current.

3.10 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 don’t work full-time as a Rails developer. Consequently, I urge you to stay up-to-date with news from the community.

I suggest signing up for two weekly email newsletters:

• Ruby Weekly
• Green Ruby News

Another weekly email newsletter is more technical, and focused on code arriving in the next version of Rails:

• This Week in Rails

For daily news about Rails, check Peter Cooper’s RubyFlow site which lists new blog posts from Rails developers each day.

Also take a look at this list of top blogs for Rails developers:

• 45 Ruby Blogs

If you like podcasts, check out Ruby Rogues and Envy Labs’s Ruby5.

Finally, you can follow @rails_apps on Twitter for news about the RailsApps project.

4.1 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 don’t already have one. As a developer, your GitHub account establishes your reputation in the open source community. If you’re 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 you’ve worked on recently. Don’t be reluctant to set up a GitHub account, even if you’re a beginner. It shows you are serious about learning Rails.

You’ll be asked to provide a username. This can be a nickname or short version of your real name (for example, your Twitter username).

You’ll be asked to provide an email address. It’s 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 page). In general, you won’t be exposed to stalkers or spammers (except some recruiters) if you are open about yourself on GitHub.

Later I’ll show you how to set up and use Git and GitHub.

4.2 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.

MailChimp will ask you to provide a website address and company details for your account. These details are included when email messages are sent to your subscribers. If you don’t have your own website, you can enter the URL for your GitHub account for now. Use your own name for a company if you don’t have one.

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.

4.3 SendGrid

Earlier editions of this book showed how to use a Gmail account to send email from the application. Google has taken steps to make Gmail more secure and now it can be difficult to send email from a Rails application using Gmail.

This tutorial provides instructions for SendGrid. SendGrid offers a free account that allows you to send 12,000 messages per month for free.

Scroll to the bottom of the SendGrid pricing page to see details about the free plan. Click the “Try for Free” link to set up an account. No credit card is needed.

4.4 Heroku

We’ll 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://signup.heroku.com/devcenter to set up an account.

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

5.1 Text Editor and Terminal Applications

I’ve explained how to use a text editor and terminal application in Book One. If you haven’t used the Unix command line before, refer to Book One for an introduction.

I recommend the Atom text editor but you may use Sublime Text or any others that provide syntax highlighting. Refer to Book One for important instructions about setting up the text editor so you can open a file from the command line.

5.2 Copying and Pasting Code

In the next chapter you’ll begin building a Rails application.

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). It’s a bit tedious and error-prone but you’ll have a good opportunity to examine the code closely.

Some students like to type in the code, character by character. If you have patience, it’s a worthwhile approach because you’ll become more familiar with the code than by copying and pasting.

Don’t feel shy about copying code; it’s 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 you’ve been working full-time 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.

5.3 Your Computer

You can develop web applications with Rails on computers running Mac OS X, Linux, or Microsoft Windows operating systems. Most Rails developers use macOS or Linux because the underlying Unix operating system has long been the basis for open source programming.

Later in this chapter, I’ll give links to installation instructions for macOS and Linux.

For Windows users, I have to say, installing Rails on Windows is frustrating and painful. Readers and workshop students often tell me that they’ve given up on learning Rails because installation of Ruby on Windows is 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 Cloud9, a browser-based development environment, on your Windows laptop.

5.4 Try the Terminal

Look for the Terminal application in the following places:

• MacOS: Applications - Utilities - Terminal
• Linux: Applications - Accessories - Terminal
• Windows: Taskbar Start Button - Command Prompt

On the Mac, search for the macOS Terminal application by pressing the Command-Spacebar combination (which Apple calls “Spotlight Search”) and searching for “Terminal.” The magnifying glass in the upper right corner of your screen will also launch “Spotlight Search.” Or look in the Applications/Utilities/ folder for the Terminal application. You’ll need to click the name of the application to launch the Terminal.

For Linux or Windows, The Command Line Crash Course explains how to launch a terminal application.

Launch your terminal application now.

Try out the terminal application by entering a shell command.

$ whoami

Don’t 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 whoami returns your username.

Don’t type the $ prompt.

You might see:

command not found: $

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. That’s 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.

5.5 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, I’m going to give you links to articles that will help you install Ruby.

You’ll spend at least an hour installing Ruby and Rails, so be sure to allow enough time for the task.

5.6 Your Workspace

Take a moment to think about where on your computer you’ll 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 haven’t done so already, make a folder to contain your programming projects. You don’t need to do this if you already created a workspace/ folder in the Unix chapter in Book One.

$ cd ~
$ pwd
/Users/danielkehoe
$ mkdir workspace
$ cd workspace

In this tutorial, the terms “folders” and “directories” mean the same thing.

Use the Unix cd command to change directories.

When you enter the Unix command cd ~, you’ll move to your home (or “user”) directory. The squiggly ~ “tilde” character is a Unix shortcut that indicates your home folder.

The Unix pwd command shows the “present working directory,” where you are.

The Unix mkdir command creates an empty folder and we move into it with the Unix cd command.

5.7 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.2)
• The third number denotes a patch level (Rails 4.2.1)

A major release includes new features, including changes which break backward compatibility. For example, switching from Rails 3.2 to Rails 4.0 required a significant rewrite of every Rails application.

A minor release introduces new features but doesn’t break anything. For example, Rails 3.2 added the asset pipeline, and Rails 4.2 added the Active Job feature for background processing.

A patch release fixes bugs but doesn’t introduce significant features. Usually this means you can change the version number in the Gemfile and run bundle update without making any other changes to your application.

5.8 Ruby and Rails Version Check

Check that appropriate versions of Ruby and Rails are installed in your development environment. You’ll need:

• The Ruby language (version 2.3 or newer)
• The Rails gem (version 5.1 or newer)

Open your terminal application and enter:

$ ruby -v

You might see:

ruby 2.4.1p0 (...)

You’ve got Ruby version 2.4.1, patch level “p0” (Ruby versions add an extra patch level to semantic versioning). If you’ve got a newer version of Ruby, no problem; minor updates to Ruby don’t affect Rails.

Try:

$ rails -v

You might see:

Rails 5.1.2

If you see:

Rails is not currently installed on this system.

You are not using an RVM gemset where the Rails gem is installed. Go to the Installing Rails instructions for your computer if you have not set up Rails. The next section explains more about RVM gemsets which may be all you need to find Rails.

If you have Rails 4.2 or older versions, you must update to Rails 5.1. See the Installing Rails instructions for your computer.

Versions such as 5.0.0.beta3 or 5.0.0.rc1 are beta versions or “release candidates.” You can use a release candidate in the weeks before a final release becomes available.

If you’ve got Rails 5.1.3 or newer, that’s fine. It means minor bugs have been fixed since this was written, but the book is still current. You can check for the current version of Rails here.

5.9 RVM

I promised that this book would introduce you to the practices of professional Rails developers. One of the most important utilities you’ll 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, you’ll 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.

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 you’ve followed the instructions in the article Installing Rails and installed RVM, you’ll be ready to handle multiple versions of Ruby, and multiple versions of Rails. That’s 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 global gemset as well as any others you have created, such as a gemset for Rails5.0.

Here’s how to switch between gemsets:

$ rvm gemset use global

And switch back to another:

$ rvm gemset use default

After you’ve worked on a few Rails applications, you’ll 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 or rbenv. Don’t be worried if you hear debates about RVM versus Chruby or rbenv; developers love to compare the merits of their tools. RVM is popular, well-supported, and an excellent utility to help a developer install Ruby and manage gemsets; that’s why we use it.

5.10 Project-Specific Gemset

For our learn-rails application, we’ll create a project-specific gemset using RVM. We’ll give the gemset the same name as our application.

By creating a gemset for our tutorial application, we’ll 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, we’ll install the Rails gem into the gemset. Enter these commands:

$ rvm use ruby-2.4.1@learn-rails --create
$ gem install rails

This will install the newest version of Rails 5.0. It takes a few minutes to automatically install all the gems that are needed for Rails.

It’s 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.

Let’s make sure Rails is ready to run. Open a terminal and type:

$ rails -v

You should see the message “Rails 5.1.2” (or something similar).

Now let’s explore the rails new command and get started building the tutorial application.

6.1 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, we’d have to code everything from scratch. Rails gives us the basics we need for many websites.

Still, the framework doesn’t 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 (the Bootstrap or Foundation front-end frameworks). Developers often mix and match components to make a customized Rails stack.

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 an attractive design. At the end of this book, you’ll learn about Rails Composer, a tool for building starter applications.

For now, we’ll begin with the Rails default starter application.

6.2 Workspace Folder and RVM Gemset

Are you in the folder named workspace/ you created earlier?

$ pwd
/Users/danielkehoe/workspace/

If you’re not in your workspace folder, enter a Unix command to move to the folder:

$ cd ~/workspace

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

$ rvm use ruby-2.4.1@learn-rails
$ rvm gemset list
gemsets for ruby-2.4.1...
   (default)
   global
=> learn-rails

You should see an arrow pointing to the learn-rails gemset. If not, go back to the previous “Get Started” chapter.

6.3 Use “Rails New” to Build the Application

Let’s go! We have selected a gemset, we have Rails installed, and we’re in our workspace/ folder. Let’s build a Rails application!

To create the Rails default starter application, type:

$ rails new learn-rails

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

It takes a few minutes when the build script runs bundle install. Don’t worry; just give it enough time to finish (but no more than five minutes even if your Internet connection is very slow).

In the future, you can give your application a different name. For this tutorial, it is VERY IMPORTANT that you use the name “learn-rails.” You’ll be copying code that assumes the name is “learn-rails;” it will save you trouble to use this name.

The rails new command will create ten folders and 93 files.

It will install 62 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. You’ll spend all your time inside this folder.

$ bundle exec spring binstub --all

Type the ls command to show the folders and files in a directory. Soon we’ll learn more about each of these folders and files.

$ ls
Gemfile      Rakefile     config       lib          test
Gemfile.lock app          config.ru    log          tmp
README.md    bin          db           public       vendor

6.4 Make a Sticky Gemset

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.4.1@learn-rails --ruby-version

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, you’d need to remember to enter rvm use ruby-2.4.1@learn-rails every time you start work on your project after closing the console.

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.

After creating the two hidden files, check if they are there:

$ ls -1pa
./
../
.gitignore
.ruby-gemset
.ruby-version
Gemfile
Gemfile.lock
README.md
Rakefile
app/
bin/
config/
config.ru
db/
lib/
log/
public/
test/
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. You’ll notice .ruby-gemset and .ruby-version.

You’ll 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

Box 6.2. Hidden Files in Cloud9

If you’re using Cloud9, you must change preferences to see hidden files. In the window that contains the file list, there is a gear icon (dark in color and difficult to see). Clicking the gear option will give you options:

• Show Root File System
• Show Home in Favorites
• Show Hidden Files

You must select all three options to see the hidden files.

That’s a brief diversion into Unix; let’s try running our new Rails application.

6.5 Test the Application

You’ve created a simple default web application. It’s ready to run.

$ rails server

$ rails s

=> Booting Puma
=> Rails 5.1.2 application starting in development on http://localhost:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma starting in single mode...
* Version 3.4.0 (ruby 2.4.1-p0), codename: Owl Bowl Brawl
* Min threads: 5, max threads: 5
* Environment: development
* Listening on tcp://localhost:3000
Use Ctrl-C to stop

... Could not find a JavaScript runtime ...

6.6 Get Organized for Efficiency

Before we learn about the Rails directory structure, take a minute to organize your screen real estate. During development, you’ll jump between the console in a terminal application, your text editor, and a web browser window. As a Rails developer, you’ll 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.

Figure 6.1: Getting organized for efficiency.

Here’s 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 Atom or 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. You’ll 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.

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; I’m sure you can improve upon these suggestions.

7.1 Video Option

Watch the eleven minute video if you have subscribed:

• Rails Project Directory

7.2 Project Directory

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), we’ll add the -1p option to the command.

$ ls -1p

You’ll see:

Gemfile
Gemfile.lock
README.md
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, there’s a command you can use to open the graphical file browser from the console. If you’re in the project directory, type open .. The period (or “dot”) is a Unix symbol that means “the directory I’m in.”

$ open .

Figure 7.1: Rails directory structure.

You’ll learn more about each file and folder as you proceed through the tutorial.

7.3 Get to Know the Folders and Files

To get you started, here are three 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. The third table is a preview of things to come.

7.4 The App Directory

Take time to drill down into the app/ folder in the project directory. This is easiest using the file browser.

Figure 7.2: Rails app folder.

You can also use your text editor to view the folder.

Or do it with Unix commands:

$ cd app
$ ls -1p
assets/
channels/
controllers/
helpers/
jobs/
mailers/
models/
views/

Whether you use the file browser, Unix commands, or your text editor, you are looking at the same file system.

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 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
• channels
• controllers
• helpers
• jobs
• mailers
• models
• views

You may recall our earlier description of Rails from the perspective of a software architect. In this folder, you’ll see evidence of the model–view–controller design pattern. Three folders named models/, views/, and controllers/ enforce the software architect’s “separation of concerns” and impart structure to our code. As you build the application, we’ll explain the role of the MVC components in greater detail.

Five folders 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, we’ll say view helpers are like “macros” that expand a short command into a longer string of HTML tags and content. Rails 3.1 added the assets/ folder as a location for CSS and JavaScript files. The jobs/ folder is for background jobs built with the Rails ActiveJob feature. Rails 5.0 added the channels/ folder for the ActionCable feature which uses WebSockets for real-time communication between web server and browser.

$ cd ..
$ pwd
/Users/danielkehoe/workspace/learn-rails

8.1 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.

GitHub’s support for forking (making your own copy of a repository) makes it possible to take someone else’s 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 coworker’s 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 don’t ordinarily do in the real world.

In this tutorial, you won’t encounter Git’s advanced procedures, like resolving merges or reverting to earlier versions. We’ll stick to the basics of archiving our work (and in one case, discarding work that we’ve 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, you’ll show potential employers or collaborators that you’ve 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. MacOS has GitHub for Mac, Git Tower, and other Mac Git clients. Graphical applications for Git are useful for colleagues who don’t use a Terminal application, such as graphic designers or writers. There’s no need for you to install these applications. Every developer I’ve 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, I’ll show you the basics of setting up and using Git.

8.2 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.

8.3 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 "me@example.com"

Use your real name so people will associate you with your work when they meet you in real life. There’s no reason to use a clever name unless you have something to hide. And use your full name, not just your first name.

Use the same email address for Git, your GitHub account, and Heroku to avoid headaches.

8.4 Create a Repository

Now we’ll add a Git repository to our project. It’s a basic step you’ll repeat every time you create a new Rails project.

Extending the time traveler analogy, initializing a Git repository is equivalent to setting up the time machine.

Be sure you are in your project directory, not your user home directory or somewhere else. Use the pwd command to check:

$ pwd
/Users/danielkehoe/workspace/learn-rails

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).

8.5 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, we’ll update the .gitignore file.

Take a look at the contents of the .gitignore file. We use the Unix cat command to display the contents of the file:

$ cat .gitignore
# See https://help.github.com/articles/ignoring-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/*
/tmp/*
!/log/.keep
!/tmp/.keep

# Ignore Byebug command history file.
.byebug_history

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

8.6 Git Workflow

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

$ 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.md
        Rakefile
        app/
        bin/
        config.ru
        config/
        db/
        lib/
        log/
        public/
        test/
        tmp/
        vendor/

nothing added to commit but untracked files present (use "git add" to track)

$ git add Gemfile

$ git add -A

$ git commit -m "Initial commit"

$ git status
On branch master
nothing to commit, working directory clean

$ git log
commit 8da41eec9e864ed91b4a445d8cefdf7893e2faf6
Author: Daniel Kehoe <daniel@danielkehoe.com>
Date:   Fri Dec 18 10:30:12 2015 +0700

    Initial commit

$ git log --oneline
8da41ee Initial commit

$ git remote add origin https://github.com/YOUR_GITHUB_ACCOUNT/learn-rails.git
$ git push -u origin master

8.7 The README

Changing the README file is a good way to practice with Git. It’s also a good habit to edit the README file whenever you create a new project. It’s easy to neglect the README for little projects that you’ve 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 you’ve borrowed. For this project you could say, “Excited to learn Rails with help from Daniel Kehoe’s book!”

In your text editor, open the file README.md and replace the contents:

# Learning Rails

Learning Rails with a tutorial from [learn-rails.com](http://learn-rails.com/).

GitHub lets you add formatting using your choice of markup syntax, depending on the file extension you add to the filename:

• README.md uses the GitHub Flavored Markdown syntax
• README.textile uses the Textile syntax
• README.rdoc uses the rdoc syntax

We’ll use Markdown syntax by adding the # character before the first line of text to force a headline. And we’ll add a link that leads to the learn-rails.com website.

There’s no requirement that you use Markdown syntax in your README file. Markdown simply is a popular way to add formatting to improve readability.

Use git status to see what has changed:

$ git status
On branch master
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:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

Here’s our typical workflow. We’ll stage and commit the change:

$ git add -A
$ git commit -m "update README"

Then we’ll push the change to GitHub:

$ git push origin master

If you decide not to use GitHub for this tutorial, you can skip this step (and skip it throughout the tutorial).

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

The git log command will display your project history:

$ git log --oneline
69b9b6c update README
8da41ee Initial commit

To learn more about Git, I recommend the book Learn Enough Git to Be Dangerous by my colleague Michael Hartl. An online version is available for free.

Now that you’re comfortable with Git, we can begin customizing our new Rails application.

9.1 Videos

If you have subscribed, two short videos introduce gems:

• What Are Rubygems
• Find Rubygems

9.2 RubyGems

It is a mark of honor to release a gem for public use, and a developer’s 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. That’s 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 gem’s 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 favoriting) 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, ideally, only a few open issues. When you find a gem that has many open issues and no recently closed issues, you’ve probably found a gem that has been abandoned. Also look at the commit log, which you’ll 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.

9.3 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, you’ll see photos of the Rails core team. More importantly, you’ll see a list of gems that are required to use Rails:

• actioncable - real-time communication using WebSockets
• actionmailer - framework for email delivery and testing
• actionpack - framework for routing and responding to web requests
• actionview - view templates and rendering
• activejob - queueing slow tasks to run in the background
• activemodel - architecture for model objects
• activerecord - framework for connections to databases
• activesupport - utility classes and Ruby library extensions
• bundler - utility to manage gems
• railties - console commands and generators
• sprockets-rails - support for the Rails asset pipeline

These are the “runtime dependencies” for Rails. Each of these gems has its own dependencies as well. When you install Rails, a total of 63 gems are automatically installed in your development environment.

9.4 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
• puma - web application server
• sass-rails - enables use of the SCSS syntax for stylesheets
• uglifier - JavaScript compressor
• coffee-rails - enables use of the CoffeeScript syntax for JavaScript
• turbolinks - faster loading of webpages
• jbuilder - utility for encoding JSON data

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

9.5 Where Do Gems Live?

Gems are files saved in the computer’s disk storage, containing someone else’s code that you can use in your own application.

When you run a Rails application, gems are loaded into the computer’s working memory immediately before your own custom code is loaded. Gems are handled by the Ruby interpreter no differently than your own code. It’s all Ruby code, whether you or someone else wrote it. When you are building an application in Rails, you don’t need to think about where gems are stored in your file system. It’s all handled automatically.

Experienced programmers who have used software libraries in other languages might wonder how it works. Here’s the technical explanation from the experts. Ruby has a require method that allows you to import software libraries into your programs. RubyGems extends the require method, adding gem directories to a $LOAD_PATH. When Rails loads, it will automatically require each of the gems listed in your Gemfile, finding the gems in the $LOAD_PATH directories.

If you’re a curious person, you might like to see where the gems live. You can run the gem env command to reveal the RubyGems environment details which are normally hidden from you:

$ gem env
RubyGems Environment:
  - RUBYGEMS VERSION: 2.6.4
  - RUBY VERSION: 2.4.1 (2016-04-26 patchlevel 112) [x86_64-darwin14]
  - INSTALLATION DIRECTORY: /Users/danielkehoe/.rvm/gems/ruby-2.4.1@learn-rails
  - USER INSTALLATION DIRECTORY: /Users/danielkehoe/.gem/ruby/2.3.0
  - RUBY EXECUTABLE: /Users/danielkehoe/.rvm/rubies/ruby-2.4.1/bin/ruby
  - EXECUTABLE DIRECTORY: /Users/danielkehoe/.rvm/gems/ruby-2.4.1@learn-rails/bin
  - SPEC CACHE DIRECTORY: /Users/danielkehoe/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /Users/danielkehoe/.rvm/rubies/ruby-2.4.1/etc
  - RUBYGEMS PLATFORMS:
    - ruby
    - x86_64-darwin-14
  - GEM PATHS:
     - /Users/danielkehoe/.rvm/gems/ruby-2.4.1@learn-rails
     - /Users/danielkehoe/.rvm/gems/ruby-2.4.1@global
.
.
.

If you use RVM, gems are saved to a hidden .rvm folder in your user directory. A global subfolder contains the Bundler gem. If you’ve followed the instructions in the “Get Started” chapter to install Rails, the project-specific 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.

Run the gem which command and you’ll see where the gems live:

$ gem which bundler
/Users/danielkehoe/.rvm/gems/ruby-2.4.1@global/gems/bundler-1.12.5/lib/bundler.rb
$ gem which rails
/Users/danielkehoe/.rvm/gems/ruby-2.4.1@learn-rails/gems/railties-5.1.2/lib/rails.rb

These are details you’ll never need to know, because Ruby on Rails handles it for you.

You’ll never move or delete gems directly. Instead you’ll manage gems using the Bundler utility. The key to Bundler is the Gemfile.

9.6 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.

Bundler’s 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 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’, ’5.0.0’ is “absolute” only version 5.0.0 will be used
• gem ’rails’, ’>= 5.0.0’ is “optimistic” any version newer than 5.0.0 will be used
• gem ’rails’, ’~> 5.0.0’ is “pessimistic”

“Pessimistic” versioning needs some explanation. ~> 5.0.0 means use any version greater than 5.0.0 and less than 5.1 (any patch version can be used). ~> 5.0 means use any version greater than 5.0 and less than 6.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.

Let’s take a look at the Gemfile created by the rails new command.

9.7 Gemfile for a Rails Default Application

Open the Gemfile with your text editor:

source 'https://rubygems.org'

git_source(:github) do |repo_name|
  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")
  "https://github.com/#{repo_name}.git"
end


# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '~> 5.1.2'
# Use sqlite3 as the database for Active Record
gem 'sqlite3'
# Use Puma as the app server
gem 'puma', '~> 3.7'
# Use SCSS for stylesheets
gem 'sass-rails', '~> 5.0'
# Use Uglifier as compressor for JavaScript assets
gem 'uglifier', '>= 1.3.0'
# See https://github.com/rails/execjs#readme for more supported runtimes
# gem 'therubyracer', platforms: :ruby

# Use CoffeeScript for .coffee assets and views
gem 'coffee-rails', '~> 4.2'
# Turbolinks makes navigating your web application faster. Read more: https://github.com/turbolinks/turbolinks
gem 'turbolinks', '~> 5'
# Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
gem 'jbuilder', '~> 2.5'
# Use Redis adapter to run Action Cable in production
# gem 'redis', '~> 3.0'
# Use ActiveModel has_secure_password
# gem 'bcrypt', '~> 3.1.7'

# Use Capistrano for deployment
# gem 'capistrano-rails', group: :development

group :development, :test do
  # Call 'byebug' anywhere in the code to stop execution and get a debugger console
  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
  # Adds support for Capybara system testing and selenium driver
  gem 'capybara', '~> 2.13'
  gem 'selenium-webdriver'
end

group :development do
  # Access an IRB console on exception pages or by using <%= console %> anywhere in the code.
  gem 'web-console', '>= 3.3.0'
  gem 'listen', '>= 3.0.5', '< 3.2'
  # Spring speeds up development by keeping your application running in the background. Read more: https://github.com/rails/spring
  gem 'spring'
  gem 'spring-watcher-listen', '~> 2.0.0'
end

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]

The file you see will be very similar. Some version numbers may be different if a newer Rails version was released since this was written.

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 a range of acceptable versions. In this case, the Gemfile indicates we can use any version between 5.1.2 and 5.2.

In the Gemfile you’ll see the gems for a Rails default application, such as the sqlite3 database gem, 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 won’t use a database for our application but we’ll keep the gem ’sqlite3’ entry. Configuring Rails for no database is complicated; it is easier to keep the sqlite3 gem and not use it.

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 doesn’t 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. For help, see Install Ruby on Rails - Ubuntu.

It’s wise to specify the Ruby version we’re using. This is needed for automated deployment scripts such as those used by Heroku. We can add that to the Gemfile:

ruby '2.4.1'

If you add the Ruby version and remove the extra clutter in the Gemfile it will look like this:

source 'https://rubygems.org'
ruby '2.4.1'
gem 'rails', '~> 5.1.2'

# Rails defaults
gem 'sqlite3'
gem 'puma', '~> 3.7'
gem 'sass-rails', '~> 5.0'
gem 'uglifier', '>= 1.3.0'
gem 'coffee-rails', '~> 4.2'
gem 'turbolinks', '~> 5'
gem 'jbuilder', '~> 2.5'
group :development, :test do
  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
  gem 'capybara', '~> 2.13'
  gem 'selenium-webdriver'
end
group :development do
  gem 'web-console', '>= 3.3.0'
  gem 'listen', '>= 3.0.5', '< 3.2'
  gem 'spring'
  gem 'spring-watcher-listen', '~> 2.0.0'
end

Try it now. Replace the Gemfile with the simplified code above.

9.8 Adding Gems

I’ve identified several gems that will be useful for our tutorial application.

I learned about these gems from several places:

• Ruby Toolbox
• RubyFlow
• various blog posts
• example code and starter apps on GitHub
• recommendations from colleagues

We’re adding these gems at the beginning of our development process since we already know which gems we’ll need. On a real project, you’ll often discover useful gems and add them to the Gemfile during the ongoing process of development.

Here are gems we’ll add to the Gemfile:

• bootstrap-sass - front-end framework
• gibbon - access to the MailChimp API
• high_voltage - for static pages like “about”
• jquery-rails - adds the jQuery JavaScript library

We’ll also add utilities that make development easier:

• better_errors - helps when things go wrong
• rails_layout - generates files for an application layout

Open your Gemfile and replace the contents with the following:

source 'https://rubygems.org'
ruby '2.4.1'
gem 'rails', '~> 5.1.2'

# Rails defaults
gem 'sqlite3'
gem 'puma', '~> 3.7'
gem 'sass-rails', '~> 5.0'
gem 'uglifier', '>= 1.3.0'
gem 'coffee-rails', '~> 4.2'
gem 'turbolinks', '~> 5'
gem 'jbuilder', '~> 2.5'
group :development, :test do
  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
  gem 'capybara', '~> 2.13'
  gem 'selenium-webdriver'
end
group :development do
  gem 'web-console', '>= 3.3.0'
  gem 'listen', '>= 3.0.5', '< 3.2'
  gem 'spring'
  gem 'spring-watcher-listen', '~> 2.0.0'
end

# learn-rails
gem 'bootstrap-sass'
gem 'gibbon'
gem 'high_voltage'
gem 'jquery-rails'
group :development do
  gem 'better_errors'
  gem 'rails_layout'
end

Notice that we’ve placed two gems inside a “group.” Specifying a group for development or testing ensures a gem is not loaded in production, reducing the application’s memory footprint. Rails let you specify groups for development, test, or production.

9.9 About the Rails Version

The version of Rails specified in your Gemfile should match the version that is installed in your gemset.

If you’ve got Rails 5.1, there’s no need to make additional changes to the Gemfile. Any version beginning with 5.1, such as 5.1.1, will be fine.

If you have Rails 5.2 (which was not available when this was written), you must get a new version of this book. The newest available version of the book is listed on the README page of the learn-rails GitHub repository. If a newer version of the book is not available, you can install Rails 5.0. See the articles Install Rails and Updating Rails for details about installing and switching between Rails versions.

9.10 Install the Gems

Each time you edit the Gemfile, you will run bundle install and restart your web server.

You’ve edited the Gemfile. Install the required gems on your computer:

$ bundle install

The bundle install command will download the gems from the rubygems.org server and save them to a hidden directory that is managed by the RVM gemset you’ve specified.

We’ll see all the gems and their dependencies:

Fetching gem metadata from https://rubygems.org/
Fetching version metadata from https://rubygems.org/
Fetching dependency metadata from https://rubygems.org/
Resolving dependencies...
Using rake 11.3.0
Using concurrent-ruby 1.0.2
Using i18n 0.7.0
Using minitest 5.9.1
.
.
.
(many more gems not shown... you get the idea)
.
.
.
Bundle complete! 20 Gemfile dependencies, 73 gems now installed.
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. There’s no reason to edit a Gemfile.lock file; if it is ever in error, delete it and run bundle install to recreate it.

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 is the same as the list specified in the Gemfile.lock file. Here’s 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.

9.11 Git

Let’s 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 git push origin master, you can use the shortcut git push.

If you get a message:

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 can’t 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. We’re only using it so you’ll be familiar with the workflow of professional development.

We’re ready to configure the application.

10.1 Configuration Security

GitHub is a good place to store and share code. But when your repos are public, they are not a good place for secret account credentials. In fact, any shared Git repository, even a private repo, is a bad place to store email account credentials or private API keys.

Operating systems (Linux, macOS, Windows) provide mechanisms to set local environment variables, as does Heroku and other deployment platforms. With a bit of Unix savvy, you can set environment variables using the Unix shell. Environment variables can be accessed from Rails applications and provide an ideal place to set configuration settings that must remain private.

For the best security, set credentials as Unix environment variables and only use Unix environment variables in the config/secrets.yml file.

The article Rails Environment Variables shows alternatives to using Unix environment variables, if for any reason you cannot set environment variables on your machine.

10.2 Videos

If you have subscribed, now’s a good time to watch:

• UNIX Environment Variables
• Rails Environment Variables

10.3 About Environment Variables

Unix environment variables are typically set in a file that is read when starting an interactive shell. The shell is the program that gives us the command line interface we see in the Terminal or console application. Unix gives you a choice of shell programs (with names like sh, bash, ksh, and zsh); each has a slightly different way to set environment variables. The most common shell program is bash.

Let’s find out what shell you are using:

$ echo $SHELL
/bin/bash

If you see /bin/bash, that’s great! If not, you may have to do some research to find out how to set environment variables in your shell.

You might be surprised to see a dollar sign in the command. You don’t type the first dollar sign (it is just the convention that indicates you are entering a Unix command). You’ll type echo $SHELL to ask the operating system to show the variable SHELL. The dollar sign in the command tells Unix to return a variable named SHELL. Try typing echo SHELL without the dollar sign and you’ll see echo just displays what you type.

When you open a console window, the bash shell reads a configuration file in your user home directory. You can use a Unix command to list all the files in your user home directory (the ~ “tilde” character represents your home directory):

$ ls -1pa ~
.
.
.
.bash_profile
.
.
.

On the Mac, you’ll see .bash_profile. On Linux systems, you’ll see .bashrc.

10.4 Viewing Hidden Files

The files .bash_profile or .bashrc are hidden in the file browser. You can force the Mac to display hidden files by entering the following command in the Terminal application:

defaults write com.apple.finder AppleShowAllFiles TRUE; killall Finder

Hidden files will appear in gray in the Finder window.

Use your text editor (Atom or Sublime) to open the .bash_profile or .bash_rc file.

To open the .bash_profile file with Atom:

$ atom ~/.bash_profile

In Unix, the squiggle (tilde) character is a shortcut to your user home folder.

Open either file and you’ll likely find a command such as:

export PATH=~/.bin:$PATH

That is a command that sets the PATH environment variable. The command might not be exactly the same but it is likely you will see some export commands.

You can add the environment variables anywhere in the file. For convenience, add the environment variables near the end of the file, above any existing EXPORT statement.

You should use quotes to surround configuration values (credentials) in the .bash_profile or .bashrc files.

If you don’t have a .bash_profile or .bashrc file in your user home directory, you can create one.

10.5 Set Environment Variables

You’ll set the following environment variables in your .bashrc or .bash_profile file:

• SENDGRID_USERNAME
• SENDGRID_PASSWORD
• MAILCHIMP_API_KEY
• MAILCHIMP_LIST_ID
• OWNER_EMAIL

Here are details.

export SENDGRID_USERNAME="example"
export SENDGRID_PASSWORD="secret"

export MAILCHIMP_API_KEY="Your_MailChimp_API_Key"

export MAILCHIMP_LIST_ID="Your_List_ID"

export OWNER_EMAIL="example@example.com"

$ echo "$SENDGRID_USERNAME"

10.6 The Secrets File

Use your text editor to add the Unix environment variables to the file config/secrets.yml:

# Be sure to restart your server when you modify this file.

# Your secret key is used for verifying the integrity of signed cookies.
# If you change this key, all old signed cookies will become invalid!

# Make sure the secret is at least 30 characters and all random,
# no regular words or you'll be exposed to dictionary attacks.
# You can use `rails secret` to generate a secure secret key.

# Make sure the secrets in this file are kept private
# if you're sharing your code publicly.

# Shared secrets are available across all environments.

# shared:
#   api_key: a1B2c3D4e5F6

# Environmental secrets are only available for that specific environment.

development:
  email_provider_username: <%= ENV["SENDGRID_USERNAME"] %>
  email_provider_password: <%= ENV["SENDGRID_PASSWORD"] %>
  domain_name: example.com
  mailchimp_api_key: <%= ENV["MAILCHIMP_API_KEY"] %>
  mailchimp_list_id: <%= ENV["MAILCHIMP_LIST_ID"] %>
  owner_email: <%= ENV["OWNER_EMAIL"] %>
  secret_key_base: very_long_random_string

test:
  secret_key_base: very_long_random_string

# Do not keep production secrets in the unencrypted secrets file.
# Instead, either read values from the environment.
# Or, use `bin/rails secrets:setup` to configure encrypted secrets
# and move the `production:` environment over there.

production:
  email_provider_username: <%= ENV["SENDGRID_USERNAME"] %>
  email_provider_password: <%= ENV["SENDGRID_PASSWORD"] %>
  domain_name: example.com
  mailchimp_api_key: <%= ENV["MAILCHIMP_API_KEY"] %>
  mailchimp_list_id: <%= ENV["MAILCHIMP_LIST_ID"] %>
  owner_email: <%= ENV["OWNER_EMAIL"] %>
  secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>

Be sure to use spaces, not tabs. Make sure there is a space after each colon and before the value for each entry or you will get a message “Internal Server Error: mapping values are not allowed” when you start the web server.

You used quotes to surround configuration values in the .bashrc or .bash_profile files. Here, in the config/secrets.yml file, you don’t need quotes when you are importing Unix environment variables.

development:
  email_provider_username: <%= ENV["SENDGRID_USERNAME"] %>
  email_provider_password: <%= ENV["SENDGRID_PASSWORD"] %>

development:
  email_provider_username: example
  email_provider_password: 's#cr*t'

: { } [ ] & * # ? | - < > = ! % @ \

10.7 Secret Key Base

It’s not necessary to set SECRET_KEY_BASE as an environment variable on the computer you use for development. Rails generates a unique SECRET_KEY_BASE in the config/secrets.yml file each time you create a new Rails application and you don’t need to replace it. If someone sees the SECRET_KEY_BASE in the config/secrets.yml file in your GitHub repo, there isn’t anything they can do with it, since they don’t have access to your local machine.

For your future reference, in case you want to change the SECRET_KEY_BASE, here’s how. Go to your Rails application directory and create a new secret token:

$ rails secret
very_long_random_string

And, if you wish, add it to your .bash_profile or .bashrc file:

export SECRET_KEY_BASE="very_long_random_string"

You should always use the environment variable <%= ENV["SECRET_KEY_BASE"] %> in the production section of your config/secrets.yml file, otherwise, someone who sees the secret token in your GitHub repo can gain access to your application in production. You’ll set the environment variables for production when you deploy to Heroku.

10.8 Configure Email

Email messages are visible in the console and the log file when you test the application. If you don’t want to actually send email, you can skip this step. But it’s more fun when your application can actually send email.

You can learn more in the article Send Email with Rails.

config.assets.debug = true

config.action_mailer.smtp_settings = {
  address: "smtp.sendgrid.net",
  port: 587,
  domain: Rails.application.secrets.domain_name,
  authentication: "plain",
  enable_starttls_auto: true,
  user_name: Rails.application.secrets.email_provider_username,
  password: Rails.application.secrets.email_provider_password
}
# ActionMailer Config
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
config.action_mailer.delivery_method = :smtp
config.action_mailer.raise_delivery_errors = true
# Send email in development mode?
config.action_mailer.perform_deliveries = true

# Send email in development mode?
config.action_mailer.perform_deliveries = true

10.9 Git

Make sure you’re in your application root directory.

Let’s commit our changes to the Git repository and push to GitHub:

$ git add -A
$ git commit -m "add configuration"
$ git push

We’re ready to create a home page for the application.

11.1 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/. You’ll see the Rails default information page.

For the next step, you’ll need to know how to use a text editor such as Atom or Sublime Text. You can find free tutorials on YouTube. Or, if you prefer a book, try Michael Hartl’s Learn Enough Text Editor to Be Dangerous.

Use your text editor to create and save a file public/index.html:

<h1>Hello World</h1>

Refresh the browser window and you’ll 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.

11.2 Routing Error

What happens when no file matches the requested web address?

Enter the URL http://localhost:3000/about.html in your browser.

You’ll see an error page that shows a routing error.

If you are using Cloud9, add “/about.html” to the URL in the preview browser window.

11.3 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. You’ll see the new “About” page.

By the way, you’ve just done test-driven development (TDD).

11.4 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.

If you’ve got only one terminal window open, you’ll have to stop the Rails server with Control-c to get your terminal prompt. Here is where it is helpful to have two terminal sessions going in different tabs.

Let’s set the “About” page as the home page.

Open the file config/routes.rb. Remove all the comments and replace the file with this:

Rails.application.routes.draw do
  root to: redirect('/about.html')
end

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/. You’ll see the “About” page.

If you still see the “Hello World” page, you didn’t remove the the public/index.html file. Rails will use the index file in the public folder before it checks the routing file for a redirect.

You’ve just seen an example of Rails magic. Some developers complain that the “convention over configuration” principle is black magic. It’s not obvious why pages are delivered from the public folder; it just happens. If you don’t 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.

11.5 Using the “About” Page

We’ve created an “About” page so we can learn about routing.

For the next chapter, we’ll use the static “About” page to investigate how a web application works.

Later in the tutorial we’ll create a new “About” page using a different approach.

12.1 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 the web is nothing more than 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 request-response 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. We’ll see that everything that happens in a web application takes place within the flow of the request-response cycle.

Let’s look at the request-response cycle.

Figure 12.1: The request-response cycle.

12.1.1 Inside the Browser

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

Start the application server if it is not already running:

$ rails server

Developers use various web browsers during development. I’ll provide instructions for Chrome, since it is the most popular. Even if you prefer Mozilla Firefox or Apple Safari, 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 (on a Mac). On Linux, use Ctrl-Shift-N to get in incognito mode with Chrome. 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 macOS, 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.

Initiate the request-response cycle by visiting the “About” page at http://localhost:3000/about.html.

In the Developer Tools view, under the Network tab, you’ll 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.

Figure 12.2: Viewing a request in the Developer Tools View.

Be sure to select the Network tab in the Developer Tools view.

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.

Figure 12.3: Viewing request headers in the Developer Tools View.

Under the heading “General,” you can see the request is composed of:

• request URL (http://localhost:3000/about.html)
• request method (GET)
• status code (200 OK or 304 Not Modified)

You can also see request and response headers:

• request headers (including the User Agent identifier)
• response headers (including last-modified date/time)

You can see the HTML sent to the browser by clicking the Preview or Response tabs in the view under the Network tab.

Here’s the point of the exercise: The browser’s Developer Tools view shows all the data exchanged between the browser and server. You’re looking at everything that passes through the plumbing.

Started GET "/" for ::1 at ...

12.2 How the Browser Works

What happens after the browser receives a response from the server?

The response is not complete until all files are received (or the browser reaches a time-out limit). Modern browsers retrieve files asynchronously; the order and location of the files in the initial HTML file doesn’t matter because the browser will try to load all the files before displaying the page.

12.3 How the Application Works

Now that we’ve investigated the request-response cycle, let’s dig deeper to understand what happens inside the Rails application in response to a browser request. To do so, we’ll need to understand the model–view–controller concept.

12.3.2 The Model View Controller Concept

The model–view–controller concept is key to understanding how a Rails application responds to a browser request.

Here is a diagram that shows what happens in the server during the request-response cycle.

Figure 12.4: Model–View–Controller in Rails.

You learned earlier that, from the perspective of a software architect, Rails is organized to conform to the model–view–controller 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 doesn’t 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.

Figure 12.5: Model–View–Controller stack in Rails.

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.

Here’s 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 user’s recent tweets from Twitter or a user’s 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). It’s 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 user’s profile. View files look much like ordinary HTML files but typically contain data in the form of Ruby variables. Often you’ll 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. We’ll create model, view, and controller files in the next chapter.

12.4 Remove the About Page

We’ve been using the static “About” page to investigate the request-response cycle.

We’re done, so delete the file public/about.html:

$ rm public/about.html

Earlier, we set up the config/routes.rb file. You can leave it in place. We’ll change it in the next chapter.

Now we’ll look at ways to implement the home page using the full power of Rails.

13.1 User Story

We’ll 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 we’ll replace this silly home page with a useful web page that encourages visitors to sign up for a mailing list.

13.2 Routes, Model, View, and Controller

We’ll use the model-view-controller design pattern as we build our new home page.

First, we’ll set up a route so a request URL gets directed to the appropriate controller.

We’ll set up a model so we obtain data we need for the home page.

We’ll set up a view that contains the HTML needed to display our home page.

And finally, we’ll create a controller that responds to the request, obtaining data from the model and rendering the view, sending a response to the web browser.

We can create the routes, model, view, and controller in any order. All must exist before our web application will respond to a request for a home page. In this tutorial, I’ve chosen to create the routes, model, view, and controller in an order that is convenient for learning.

13.3 The Name Game

Much of the art of programming lies in choosing suitable names for our creations.

We’ll need a model as a source for data about the site owner. Choosing the most obvious name, we’ll 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:

• VisitorsController - the file will be app/controllers/visitors_controller.rb

Later we’ll see this is a good choice because we’ll 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).

13.4 Naming Conventions

Rails is picky about class names and filenames. That’s 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, here’s a note about typographic terminology:

• a string is a sequence of characters
• you’re 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, you’ll follow rules for class names:

• class Visitor - the model class name is capitalized and singular
• class VisitorsController < ApplicationController - for a controller, combine a pluralized 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, you’ll encounter unexpected problems and frustration.

13.5 Routing

We’ll create the route before we implement the model and controller.

Open the file config/routes.rb. Replace the contents with this:

Rails.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.

Don’t be overly concerned about understanding the exact syntax of the code. It will 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 don’t need to restart the server after changing routes.

If you need to start the server:

$ rails server

Visit the page http://localhost:3000/. You’ll see an error message because we haven’t implemented the controller. The error message, “uninitialized constant VisitorsController,” means Rails is looking for a VisitorsController and can’t find it.

13.6 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.

To keep things simple, our tutorial application doesn’t need a database. Instead of inheriting from ActiveRecord, we create a Ruby class with methods that return the owner’s 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 (don’t include the colon punctuation that follows):

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 you’ll see is the owner’s 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 computer’s 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 (for “method definition”) and ending with end.

• def name … end
• def birthdate … end
• def countdown … end

Each method contains simple Ruby code that assigns data to a variable. Later, we’ll retrieve the data for use in our view file by instantiating the class and calling a method. Don’t be discouraged by the software architects’ terminology; the concepts are simple and we’ll 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.

Looking more closely at the Ruby code inside the method definitions, you’ll 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 object’s 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. Ruby’s 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, 12, 22) to the birthdate variable.

Note that Ruby has specific expectations about the syntax of numbers. The Date.new(...) method expects integers. Imagine a September birthday. You must use Date.new(1990, 9, 22). If you enter a date in the format Date.new(1990, 09, 22), you’ll get a syntax error “Invalid octal digit” when you test the application. Ruby expects numbers that begin with zero to be octal numbers; you’ll get an error because octal numbers can’t contain the digit “9.”

Our countdown method contains the most complex code in the class.

First, we set a variable today with today’s 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 computer’s system clock.

Next we create a birthday variable and assign a new date that combines today’s year with the month and day of the birthdate. This gives us the date of Foobar Kadigan’s 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 Kadigan’s 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 owner’s 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 year’s birthday. Then we subtract today from birthday.next_year to calculate the number of days remaining until the owner’s 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.

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 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, we’ll 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.

Let’s see how we can put this functionality to use on a web page.

13.7 View

The Owner model provides the data we want to see on the Home page.

We’ll 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 (don’t include the colon punctuation that follows):

<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>

We’ve created a visitors/ folder within the app/views/ directory. We have only a single new view but if we had more views associated with the Visitors controller, they’d 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, we’ll 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 replaced by the result of evaluating the code. In other words, <%= @owner.name %> will appear on the page as Foobar Kadigan.

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 owner’s 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 you’re 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 you’ve 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.

13.8 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. In this context, 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 (sometimes called “snake_case”).

Create a file app/controllers/visitors_controller.rb (don’t include the colon punctuation that follows):

class VisitorsController < ApplicationController

  def new
    @owner = Owner.new
  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 don’t instantiate the Owner model, we’ll 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.

You’ve 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 what’s 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.

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

13.9 Scaffolding

This tutorial aims to give you a solid foundation in basic concepts. The model–view–controller pattern is one of the most important. I’ve found the best way to understand model–view–controller architecture is to create and examine the model, view, and controller files.

As you continue your study of Rails, you’ll 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, I’ve observed that working Rails developers seldom use scaffolding. There’s nothing wrong with it; it just seems that scaffolding doesn’t offer much that can’t be done as quickly by hand.

13.10 Test the Application

We’ve created a model, view, and controller. Now let’s run the application.

Enter the command:

$ rails server

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

Figure 13.1: Dynamic home page shows days until a birthday.

It’s 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 structure of Rails.

13.11 Git

At this point, you might have the Rails server running in your console window. We’re 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 that’s not necessary. You can open more than one console view. Your terminal application lets you open multiple windows or tabs. If you open multiple tabs, you can easily switch between console views without using a lot of screen real estate. If you haven’t tried it, now is a good time. On the Mac, Command+t opens a new tab in the terminal application. It is convenient to have a console tab open for the server and another for various Unix commands.

Let’s commit our changes to the Git repository and push to GitHub:

$ git add -A
$ git commit -m "dynamic home page"
$ git push

Now let’s take a look at troubleshooting.

14.1 Git

In this chapter we’ll make changes to the application just for troubleshooting.

Before you get started, make sure the work you’ve 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, we’re going to throw away the work we’ve done in this chapter. We don’t want to accidentally throw away work from the previous chapter so make sure it is committed to the repository.

14.2 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.

Let’s try it.

$ irb
>>

The command irb launches the program and displays a prompt that shows your Ruby version, a line number, and an arrow. I’ll just show a simple prompt in the examples, instead.

If you enter a valid Ruby expression, the interpreter will display the result of evaluating the expression.

Try simple arithmetic:

>> n = 2
 => 2
>> 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.

>> n = 10
=> 10
>> if n < 10
>>   puts "small"
>> else
?>   puts "big"
>> end
big
=> nil
>>

>> load './mytest.rb'

$ irb
>> exit

14.3 Rails Console

IRB only evaluates expressions that are defined in the Ruby API. IRB doesn’t know Rails.

It’d be great to have a tool like IRB that evaluates any expression defined in the Rails API. The tool exists; it’s 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 5.x.x)
>>

The Rails console behaves like IRB but loads your Rails development environment. The prompt shows it is ready to evaluate an expression.

Let’s use the Rails console to examine our Owner model:

>> myboss = Owner.new
 => #<Owner:0x007fc18e91faf8>

We’ve 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 you’re unsure about the difference between an instance and a class, we’ve just seen that we can make one or more instances of a class by calling the Owner.new method. When we specify the Owner class, the class definition is loaded into the computer’s 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.

Let’s assign the name of our boss to a variable called name:

>> name = myboss.name
 => "Foobar Kadigan"

Our variable myboss is an instance of an Owner class so it responds to the method Owner.name by returning the owner’s name.

We want to show respect to our boss so we’ll perform some string manipulation:

>> name = 'Mr. ' + name
 => "Mr. Foobar Kadigan"

We’re 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 computer’s chips, but they have no meaning until another program uses them.

Enter Control-d or type exit to quit the Rails console.

The Rails console is a useful utility. It is like a handy calculator for your code. Use it when you need to experiment or try out short code snippets.

14.4 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.

Here’s what you see in the log after you visit the application home page:

Started GET "/" for ::1 at ...
Processing by VisitorsController#new as HTML
  Rendering visitors/new.html.erb within layouts/application
  Rendered visitors/new.html.erb within layouts/application (6.6ms)
Completed 200 OK in 650ms (Views: 634.4ms | ActiveRecord: 0.0ms)

You may have more than one console window open in the terminal application. If you don’t see your log output in your terminal, check if you have tabs with other windows.

Here’s the best part. You can add your own messages to the log output by using the Rails logger. Let’s 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 you’ll see this in the console output:

Started GET "/" for ::1 at ...
Processing by VisitorsController#new as HTML
DEBUG: entering new method
DEBUG: Owner name is Foobar Kadigan
  Rendering visitors/new.html.erb within layouts/application
  Rendered visitors/new.html.erb within layouts/application (1.1ms)
Completed 200 OK in 81ms (Views: 72.2ms | ActiveRecord: 0.0ms)

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. You’ll never need diagnostics at this level of detail in Rails, but the logger is extremely useful when you are trying to understand unexpected behavior.

Let’s add logger statements to the Owner model. Modify the file app/models/owner.rb:

class Owner

  def name
    name = 'Foobar Kadigan'
  end

  def birthdate
    birthdate = Date.new(1990, 12, 22)
  end

  def countdown
    Rails.logger.debug 'DEBUG: entering Owner countdown method'
    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

We added the Rails.logger.debug statement to the Owner.countdown method.

Visit the home page and here’s what you’ll see in the console output:

Started GET "/" for ::1 at ...
Processing by VisitorsController#new as HTML
DEBUG: entering new method
DEBUG: Owner name is Foobar Kadigan
  Rendering visitors/new.html.erb within layouts/application
DEBUG: entering Owner countdown method
  Rendered visitors/new.html.erb within layouts/application (0.7ms)
Completed 200 OK in 69ms (Views: 61.1ms | ActiveRecord: 0.0ms)

You’ll often need to “get inside” the model or controller to see what’s 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 logger on its own. In a model, you have to write Rails.logger (both class and method).

You can use any of the methods logger.debug, logger.info, logger.warn, logger.error, or logger.fatal to write log messages. By default, you’ll 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.

14.5 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, we’ll see messages showing the server’s traverse of the model-view-controller architecture.

Started GET "/" for ::1 at ...
Processing by VisitorsController#new as HTML
DEBUG: entering new method
DEBUG: Owner name is Foobar Kadigan
  Rendering visitors/new.html.erb within layouts/application
DEBUG: entering Owner countdown method
  Rendered visitors/new.html.erb within layouts/application (0.7ms)
Completed 200 OK in 69ms (Views: 61.1ms | ActiveRecord: 0.0ms)

Notice how the diagnostic messages in the console window match the headers in the browser Developer Tools view. The browser’s “Request Method:GET” matches the server’s “Started GET.” The browser’s “Status Code: 200” matches the server’s “Completed 200 OK” (you might have to clear the browser’s 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.

As we learned, the model-view-controller architecture is an abstract design pattern. We’ve seen it reflected in the file structure of the Rails application directory. Now we can see it as activity in the server log.

14.6 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.

Let’s 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 you’ll see an error page:

Figure 14.1: Error page.

You’ll see this error page because we’ve installed the better_errors gem. Without the better_errors gem, you’d 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 ::1 at ...
Processing by VisitorsController#new as HTML
DEBUG: entering new method
DEBUG: Owner name is Foobar Kadigan
Completed 500 Internal Server Error in 8ms (ActiveRecord: 0.0ms)

NameError - uninitialized constant VisitorsController::DISASTER:
  app/controllers/visitors_controller.rb:7:in `new'
  .
  .
  .

To save space, I’m only showing the top line of the stack trace. I’ve eliminated about sixty lines from the stack trace.

Don’t 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 top line of the stack trace is important.

In this case, both the error page and the top line of the stack trace show the application failed (I prefer to say, “barfed”) when it encountered an “uninitialized constant” at line 7 of the app/controllers/visitors_controller.rb file in the new method. It’s easy to find line 7 in the file and see that is exactly where we added a string that Rails doesn’t understand.

The point of this exercise is to encourage you to read the top line of the stack trace and use it to diagnose the problem. I’m always surprised how many developers ignore the stack trace, probably because it looks intimidating.

14.7 Raising an Exception

As you just saw, you can purposefully break your application by adding characters that Rails doesn’t understand. However, there is a better way to force your program to halt, called raising an exception.

Let’s try it. 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
    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 you’d like in quotes following raise.

Here’s the console log after you try to visit the home page:

Started GET "/" for ::1 at ...
Processing by VisitorsController#new as HTML
DEBUG: entering new method
DEBUG: Owner name is Foobar Kadigan
Completed 500 Internal Server Error in 6ms (ActiveRecord: 0.0ms)

RuntimeError - Deliberate Failure:
  app/controllers/visitors_controller.rb:7:in `new'
  .
  .
  .

Before we continue, let’s 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 a user enters a birthdate that is not in the past. Rails includes various exception handlers to display errors in production so users will see a helpful web page explaining the error.

14.8 Git

There’s 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 there’s an easier way.

Check which files have changed:

$ git status
# Changes not staged for commit:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." 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 you’ve made since the most recent commit. Check the status to make sure:

$ git status
# On branch master
nothing to commit, working directory clean

We’ve cleaned up after our troubleshooting exercise.

15.1 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 you’ll 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, you’ll need to know enough of the Ruby language to implement the features you need. But as a student, you’ll 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 you’ve already learned. And you’ll extend your knowledge so you’ll be prepared for the Ruby you’ll encounter in upcoming chapters.

15.2 Ruby Example

To improve your reading knowledge of Ruby, we’ll work with an example file that contains a variety of Ruby expressions.

We won’t use this file in our tutorial application, so you’ll delete it at the end of this chapter. But we’ll 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 don’t fit in the Rails API. We’ll create the file in the lib/ folder. That’s the folder you’ll use for any supporting Ruby code that doesn’t fit elsewhere in the Rails framework.

Create a file lib/example.rb:

class Example < Object

  # This is a comment.

  attr_accessor :honorific
  attr_accessor :name
  attr_accessor :date

  def initialize(name,date)
    @name = name
    @date = date.nil? ? Date.today : date
  end

  def backwards_name
    @name.reverse
  end

  def to_s
    @name
  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:

'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. If you’re beginning a career as a Rails developer, this won’t 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.

15.3 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, you’ll recognize Ruby keywords because you’ve seen them before.

You’ll also recognize a developer’s 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, you’ll rightly guess that myapp or fluffycat are not part of the Ruby language.

If you’re 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.

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 we’ll do next.

15.4 Ruby Files

When we write code, we save it in files. We’ve added our miscellaneous example file to the lib/ folder.

By convention, Ruby files end with the file extension .rb.

$ irb
>> load 'lib/example.rb'
=> true
>>  require 'date'
=> true
>> ex = Example.new('Daniel',nil)
=> #<Example:0x007fb46c9eecd8 @name="Daniel", @date=#<Date: 2015-12-23 ...
>> list = ex.december_birthdays
=> ["Ludwig van Beethoven", "Dave Brubeck", "Keith Richards"]
>>

15.5 Whitespace and Line Endings

Whitespace characters such as spaces and tabs are generally ignored in Ruby code, except when they are included in strings. There are several special cases where whitespace is significant in Ruby expressions but you are not likely to encounter these cases as a beginning Rails developer.

Some programming languages (Java and the C family) require a semicolon as a terminator character at the end of statements. Ruby does not require a semicolon to terminate a statement. Instead, if the Ruby code on a line is a complete expression, the line ending signifies the end of the statement. If the line ends with a + or other operator, or a backslash character, the statement is split into multiple lines.

15.6 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 don’t want the code to run. This is a common trick when you want to “turn off” some part of your code but you don’t want to delete it just yet, because you are trying out alternatives.

15.7 The Heart of Programming

Three principles are at the heart of all programming:

• syntax
• conditional execution
• transformation

Computers allow no ambiguity. Code must exactly follow the syntax of a language. Typos, guesses, and code that is almost-but-not-quite right will simply fail, often without any helpful error messages.

Computers seem intelligent because they can execute code conditionally. You can write a program so that given one set of conditions, certain parts of the code will execute, and given different conditions, other parts of the code will execute.

Lastly, programs are written to transform abstractions from one form to another. That’s why computer programs look like math. When we learn simple arithmetic, we learn we can take the symbols for numbers and add them together to make a different number. Computer programs do more than add numbers; a program can transform words and other abstractions.

15.8 Assignment

In Ruby, like many other programming languages, the equals sign indicates we are assigning a value.

  name = 'Foobar Kadigan'

Assignment is the first step to transformation. Here ’Foobar Kadigan’ is a string of letters. The equals sign is the assignment operator. And name is a variable that stores the value so it can be easily reused. We don’t have to type ’Foobar Kadigan’ every time we need a name; we can use name instead.

Just as we can assign a value to a variable, we can reassign a new value whenever we want. That is why we call them variables; the value can vary.

  name = 'Mr. Foobar Kadigan'

Variables can be assigned strings of letters, numbers, or anything else. “Anything else” is very broad because we can use Ruby to make complex structures that contain data and also “do work.” These complex structures are objects and we say that Ruby is object-oriented because it is easy to work with objects in Ruby.

15.9 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.

15.10 Classes

You don’t have to create classes to program in Ruby. If you only write simple programs, you won’t 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, you’ll 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

The end statement indicates all the preceding code is part of the Example class.

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

Here is the Example class without the explicit subclassing from Object:

class Example
.
.
.
end

Much of the art of programming is knowing what classes are available in the API and deciding when to subclass to inherit useful methods.

15.11 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.

A method definition begins with the keyword def and (predictably) ends with end.

  def backwards_name
    @name.reverse
  end

Initializing the object and calling the method returns a result:

ex = Example.new('Daniel',nil)
my_backwards_name = ex.backwards_name
  => leinaD

We can also override a method from the parent class.

  def to_s
    @name
  end

Here we are overriding the to_s (“to string”) method from the parent Object class.

Ordinarily, the to_s method returns the object’s class name and an object id. Here we will return the string assigned to the variable @name.

Most times you won’t override the to_s (“to string”) method. This example shows how you can override any method inherited from a parent class.

15.12 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.

Some classes, such as Date, provide class methods which can be called directly on the class without instantiating it first. For example, you can run this in the Rails console:

Date.today
 => Tue, 15 Oct 2013

More often, methods are called on variables which are instances of a class. For example:

birthdate = Date.new(1990, 12, 22)
 => Sat, 22 Dec 1990
birthmonth = birthdate.month
 => 12

We can apply method chaining to objects. For example, String has methods reverse and upcase (among many others). We could write:

nonsense = 'foobar'
 => "foobar"
reversed = nonsense.reverse
 => "raboof"
capitalized = reversed.upcase
 => "RABOOF"

It is easier to use method chaining and write:

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

Classes create a structure for our software programs and methods do all the work.

15.13 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.

  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 don’t define an initialize method, the new method still works, inherited from Object, so we can always instantiate any class.

15.14 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.

Our initialize method 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.

15.15 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 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 someone’s 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).

  :name

15.16 Attributes

In an object, methods do the work and data is stored as variables. We can use the initialize method to input data to the object. We can’t access data in variables from outside the object unless it is exposed as attributes.

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.

In Ruby, attributes are also called properties.

Here we use the attr_accessor directive to specify that we want to expose honorific, name and date attributes.

  attr_accessor :honorific
  attr_accessor :name
  attr_accessor :date

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 are just specialized methods that expose data outside the object.

15.17 Instance Variable

Inside an object, an ordinary variable only can be used within the method in which it appears. If you use a variable with the same name in two different methods, it will have a different value in each method. The scope of a variable is limited to the method in which it is used.

Often you want a variable to be available throughout an instance, within 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

The values assigned to instance variables are unique for every instance of the class. If you create multiple instances of a class, each will have its own values for its instance variables. Here we create two instances of the Example class. The @name instance variable will be “Daniel” in the first instance and “Foobar” in the second instance.

  ex1 = Example.new('Daniel',nil)
  ex2 = Example.new('Foobar',nil)

An instance variable is not visible outside the object in which it appears; but when you create an attr_accessor, it creates an instance variable and makes it accessible outside the object.

15.18 Double Bar Equals Operator

I’ve suggested that the best way to get help is to use Google or Stack Overflow to look for answers. But that’s difficult when you don’t know what symbols are called. Try googling “||=” and you’ll get no results. Instead, try googling “bar bar equals ruby” or “double pipe equals ruby” and you’ll find many explanations of the “or equals” operator. This is an example of mysterious shorthand code you’ll 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.

  @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.

15.19 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 else, in which case an alternative is executed.

  if date.month == 12
    .
    .
    .
  end

Sometimes you’ll see unless instead of if, which is a convenient way of saying “execute the following if the condition is false.”

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.

15.20 Ternary Operator

A basic conditional structure might look like this:

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

We test if date is undefined (nil). If nil, we assign today’s 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 today’s 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 you’ll 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.

For more Ruby code that has been condensed into obscurity, see an article on Ruby Golf. Ruby golf is the sport of writing code that uses as few characters as possible.

15.21 Interpolation

Rubyists love to find special uses for orthography such as hashmarks and curly braces. It seems Rubyists feel sorry for punctuation marks that don’t 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'
  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.

15.22 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. This is common when you need a simple utility method that is used by several other methods.

Any methods that follow the keyword private should only be used by methods in the same class (or a subclass).

  private

You often see private methods in Rails. Ruby provides a protected keyword as well, but the difference between protected and private is subtle and protected is seldom seen in Rails applications.

15.23 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; 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.

You’ll recognize a Hash when you see curly braces (again, Rubyists give a job to under-utilized 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. You’ll often see hashrockets in code written before Ruby 1.9. Ruby 1.9 introduced a new syntax using colons instead of hashrockets.

Whether with colons or hashrockets, you’ll often see Hashes used in Rails.

With Ruby 1.9 and later, here’s how we 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.

Ordinarily, a symbol is defined with a leading colon character. In a Hash, a trailing colon makes a string into a symbol.

If you want to transform a string containing spaces into a symbol in a Hash, you can do it, though the syntax is awkward:

  birthdays = {
    'Ludwig van Beethoven': Date.new(1770,12,16)
  }

15.24 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 don’t 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 push method:

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

In our example code, we use the << shovel operator to add items to the array:

  born_in_december << name

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

15.25 Iterator

Of all the methods available for a Ruby collection such as Hash or Array, the iterator may be the most useful.

You’ll recognize an iterator when you see the each method applied to a Hash or Array:

  famous_birthdays.each

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

15.26 Block

You can recognize a block in Ruby when you see a do ... end structure. A block is a common way to process each item when an iterator such as each is applied to a Hash or Array.

In our example, we iterate over the 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

When you use a block within a method, any variable in your method is available within the block. That’s why we can add name to the array born_in_december.

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 you’ll 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 don’t see a method definition, you can use a block to evaluate a sequence of statements and obtain a result.

15.27 Rails and More Keywords

We’ve looked at only a few of the keywords and constructs you will see in Ruby code. The exercise has improved your Ruby literacy, so you’ll have an easier time reading Ruby code.

Nothing in the exercise is Rails. The example 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 aren’t previously defined. Software architects call this metaprogramming which simply means clever programming that twists and reworks the programming language.

When you add a gem to a Rails project, you’ll 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, you’ll be able to pick apart the complexity and make sense of any code.

15.28 More Ruby

To develop your proficiency as a Rails developer, I hope you will make an effort to learn Ruby as you learn Rails. Don’t be lazy; when you encounter a bit of Ruby you don’t 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.